Command Line Build batch file

This forum is for all Flare related Tips and Tricks.
Have a tip or trick you use while working in Flare? Share it here.
Ken Billing
Propeller Head
Posts: 55
Joined: Mon Dec 17, 2007 11:33 am

Re: Command Line Build batch file

Post by Ken Billing »

The crux of the batch file is the following line that lists the topic files in ascending date order so that the newest is listed last. The FOR statement should set the environment variable NewestTopicDate to the date/time of each file, resulting in the variable being set to the date/time of the newest file. The problem is that the %~t substitution reference doesn't work as it should. I've tried several other of the substitution references and they work fine. Perhaps its a data formatting issue, I don't know. I had to set this aside and get some real work done. :wink:

Code: Select all

FOR /F "delims=" %%I IN ('DIR /B /O:D "Content\*.htm"') DO SET NewestTopicDate=%%~tI
The batch file could contain a similar line to do the same for the Project\TOCs folder to set another environment variable to the date of the newest TOC. Yet another line will do the same for the target folder output file.

Next, a line similar to the following will compare the dates to determine if the target is outdated and if so, execute a build.

Code: Select all

 IF /I %NewestTopicDate% GTR %NewestTargetDate% (
madbuild.exe -build MyProject.flprj -target MyTarget >> BuildResults.log
:: Add build completion line to log
echo Project build completed >> BuildResults.log

:: Begin FTP transfer
FTP -s:MyScript.ftp

:: Add transfer completion line to log
echo Build transferred to FTP >> BuildResults.log
)
The code above is somewhat simplified for clarity.
Ken Billing | Technical Writer
BlueCielo ECM Solutions
http://www.bluecieloecm.com

Image
TheGreatAndPowerfulOz
Sr. Propeller Head
Posts: 130
Joined: Mon Apr 24, 2006 12:52 pm
Location: Glen Mills, PA

Re: Command Line Build batch file

Post by TheGreatAndPowerfulOz »

Well, at long last the glory days of the .BAT file are over! Flare V6 now offers batch building/publishing of project targets.

I just installed Flare V6 and tried it out; works great! Hooray!! :D
Austin Wright

Flare 2022 r3 (18.2.8431.26678) :: TopNav HTML5 / PDF output
Ken Billing
Propeller Head
Posts: 55
Joined: Mon Dec 17, 2007 11:33 am

Re: Command Line Build batch file

Post by Ken Billing »

I submitted an enhancement request for conditional builds, by the way. Maybe 7?
Ken Billing | Technical Writer
BlueCielo ECM Solutions
http://www.bluecieloecm.com

Image
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Command Line Build batch file

Post by NorthEast »

TheGreatAndPowerfulOz wrote:Well, at long last the glory days of the .BAT file are over! Flare V6 now offers batch building/publishing of project targets.

I just installed Flare V6 and tried it out; works great! Hooray!! :D
I had a look too, seems to work ok.

One thing I did notice - when I add the target batch file, Flare wants to include it in source control.
Now thinking ahead, if I did that, that'd mean everyone working on the project would also have a local copy of the batch target too. So wouldn't that cause numerous simultaneous builds on all our PCs, all trying to publish to the same folder?
doc_guy
Propellus Maximus
Posts: 1979
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West
Contact:

Re: Command Line Build batch file

Post by doc_guy »

Dave, your logic there is sound. I think you're right. It would.

You might want to exclude that file type from your repository, so it never gets picked up.
Paul Pehrson
My Blog

Image
TheGreatAndPowerfulOz
Sr. Propeller Head
Posts: 130
Joined: Mon Apr 24, 2006 12:52 pm
Location: Glen Mills, PA

Re: Command Line Build batch file

Post by TheGreatAndPowerfulOz »

doc_guy wrote:You might want to exclude that file type from your repository, so it never gets picked up.
I hadn't considered the notion which Dave brings up, and I was *just about* to add my new target batch files to source control. Whew!

So, forgive my ignorance, but how does one "exclude that file type from [the] repository"?
Austin Wright

Flare 2022 r3 (18.2.8431.26678) :: TopNav HTML5 / PDF output
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Command Line Build batch file

Post by NorthEast »

TheGreatAndPowerfulOz wrote:
doc_guy wrote:You might want to exclude that file type from your repository, so it never gets picked up.
I hadn't considered the notion which Dave brings up, and I was *just about* to add my new target batch files to source control. Whew!

So, forgive my ignorance, but how does one "exclude that file type from [the] repository"?
I've not found any way to exclude files in VSS 2005 (or Flare); but I'm not familiar with TFS or anything else.

I can live with it; it's just a bit annoying to have a file permanently in the pending check-ins list, and I don't want to add it by accident.
TheGreatAndPowerfulOz
Sr. Propeller Head
Posts: 130
Joined: Mon Apr 24, 2006 12:52 pm
Location: Glen Mills, PA

Re: Command Line Build batch file

Post by TheGreatAndPowerfulOz »

Dave Lee wrote:I can live with it; it's just a bit annoying to have a file permanently in the pending check-ins list, and I don't want to add it by accident.
My thoughts exactly. I'm using VSS 2005, as well, and I don't see any way to exclude files. It'd be nice to not have the target batch files hanging around as "pending add"...
Austin Wright

Flare 2022 r3 (18.2.8431.26678) :: TopNav HTML5 / PDF output
Ken Billing
Propeller Head
Posts: 55
Joined: Mon Dec 17, 2007 11:33 am

Re: Command Line Build batch file

Post by Ken Billing »

Okay boys and girls, I've refined my conditional build batch file(s) to the point where they work well and thought I'd contribute them for the benefit of others here. I've found a few solutions to problems in this forum and want to pay it forward.

The major reason for this exercise in the first place was to keep my targets up to date without generating unnecessary builds. If you use Flare's batch targets and schedule them to occur nightly, every project gets rebuilt every night which, in itself isn't a bad thing, but it makes delivery or review decisions based only on changed files more difficult. Plus, if your documentation library is fairly big, it can take a lot of time and processing power to rebuild everything nightly. That's more time and opportunity for something to go wrong and unnoticed. Conditional builds keep it to a minimum. Work smarter, not harder is my motto!

A few caveats are in order first, followed by high-level explanations of each batch file.

1. These batch files WILL need to be modified to suit your project folder structure, requirements, etc. This method relies on all of the projects residing in folders at the same level. See the explanation below for more details. The batch files also need to reside in the same folder together or the calls need to modified to include appropriate paths.

2. No error checking is implemented at this time. You can add your own. Reviewing the output log file reduces the need for it, but to follow good programming practice, it should be added. If I get a round tuit, I'll post updates here.

3. I schedule this batch file to run nightly, resulting in only my modified projects being freshly built the next morning without unnecessary builds of unchanged projects. I follow it with a weekly batch file to archive all of the results into a RAR file and upload it to our development teams overseas. They can then easily see what deliverables have changed and which have not based on the file dates and times.

On with the show! The first batch file establishes a home directory. This directory is the parent of the project folders that will be processed and stores the output log file. The batch file then reads a simple list of project subfolder names from a text file and iterates through each subfolder, calling a second batch file that performs the checking of files for that project. The second batch file is also separate so that I can run it from a command line or other batch file to check an individual project.

Code: Select all

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
::                                                          ::
:: CheckAllBuilds.cmd                                       ::
::                                                          ::
:: Batch file to check the build status of a list of        ::
:: Flare projects contained in Projects.txt                 ::
::                                                          ::
:: Created by Ken Billing                                   ::
::                                                          ::
:: Calls CheckBuild.cmd with each project name              ::
:: Logs results in CheckAllBuilds.log                       ::
::                                                          ::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

@ECHO Off
:: Set CMD window title
TITLE CheckAllBuilds

SETLOCAL ENABLEDELAYEDEXPANSION

SET HomeDir=%CD%

:: Start new log file
ECHO %DATE% %TIME% Check of all builds started. > "%HomeDir%"\CheckAllBuilds.log
ECHO HomeDir = %HomeDir% >> "%HomeDir%"\CheckAllBuilds.log

FOR /F "usebackq delims==" %%P in (Projects.txt) DO (
    ECHO ============================================================== >> "%HomeDir%"\CheckAllBuilds.log
    ECHO !DATE! !TIME! Checking "%%P". >> "%HomeDir%"\CheckAllBuilds.log
    CALL CheckBuild.cmd "%%P"
)

ECHO %DATE% %TIME% Check of all builds finished. >> "%HomeDir%"\CheckAllBuilds.log
The second batch file does the heavy lifting. It initializes several environment variables to store the newest target and topic file names and dates/times. It then finds the newest topic file in subfolders of the Content folder. This batch file does not look for other types of updated files, such as images or TOCs. Those could be added to the process using the same technique if you often change those files independent of your topic files.

IMPORTANT: All of my topic files reside in subfolders of Content except topics (Table of Contents, Glossary, Index, etc. master pages) that are used commonly across all projects. To process files residing directly in Content requires modification of this batch file accordingly.

It then proceeds to find the newest CHM target file. Although I also generate other targets in my projects, I key off of the CHM file since it's our primary deliverable. Your situation may be different. Note that you will also need to substitute your user name for "Ken_Billing" in the batch file. I use the same target name for this CHM file in every project too, "Microsoft HTML Help" so that the batch file applies equally well to every project.

Lastly, it compares the dates and times of the newest topic and target files that it found. If a topic is newer than the target, it calls a third batch file to rebuild that project. Two subroutines can be found at the bottom of the file, that are called for every file that the batch file examines. Note that I store the date/time values as single number in the output log file. This actually makes them easier to read and compare. Alternative display statements are provided if you want to use them, but are commented out.

Code: Select all

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
::                                                          ::
:: CheckBuild.cmd                                           ::
::                                                          ::
:: Batch file to check the date of the current HTML Help    ::
:: target against current topics files for one Flare        ::
:: project.                                                 ::
::                                                          ::
:: Created by Ken Billing                                   ::
::                                                          ::
:: Called from CheckAllBuilds.cmd                           ::
:: Accepts project name read from Projects.txt              ::
:: Calls MakeBuild.cmd with same project name               ::
:: Logs results in CheckAllBuilds.log                       ::
::                                                          ::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

@ECHO On
:: Set CMD window title
TITLE CheckBuild %1%

SETLOCAL ENABLEDELAYEDEXPANSION
SET NewestTopic=
SET NewestTopicDate=0
SET Result=0

CD %1%
:: Test for presence of build output to check
IF EXIST Output\Ken_Billing\Microsoft HTML Help\*.chm (
:: File must be in current folder to get the date
CD Content
:::::::::::::::::::::::::::::::::::::
:: Get newest topic filename and date
FOR /D %%D IN (*.) DO (
    ECHO Checking topics in %%D >> "%HomeDir%"\CheckAllBuilds.log
    CALL :CompareTopicDates "%%D"
    CD %%D
    )
)
CD %HomeDir%
ECHO Newest topic = %NewestTopic% >> "%HomeDir%"\CheckAllBuilds.log
ECHO Newest topic date = %NewestTopicDate% >> "%HomeDir%"\CheckAllBuilds.log
::Alternate parsing for friendly date display
::%NewestTopicDate:~4,2%-%NewestTopicDate:~6,2%-%NewestTopicDate:~0,4%  %NewestTopicDate:~8,2%:%NewestTopicDate:~10,2% >> "%HomeDir%"\CheckAllBuilds.log

::::::::::::::::::::::::::::::::::::::
:: Get newest target filename and date
:: File must be in current folder to get the date
CD %1%
CD Output\Ken_Billing\Microsoft HTML Help

SET NewestTarget=
SET NewestTargetDate=0

IF EXIST *.chm (
    FOR /F "usebackq delims==" %%F IN (`DIR /B /T:W /O:D "*.chm"`) DO (
        SET NewestTarget=%%F
        CALL :FileDateToString "%%F"
    )
)
SET NewestTargetDate=%Result%
CD %HomeDir%
ECHO Newest target date = %NewestTargetDate% >> "%HomeDir%"\CheckAllBuilds.log
::Alternate parsing for friendly date display
::%NewestTargetDate:~4,2%-%NewestTargetDate:~6,2%-%NewestTargetDate:~0,4%  %NewestTargetDate:~8,2%:%NewestTargetDate:~10,2% >> "%HomeDir%"\CheckAllBuilds.log

:::::::::::::::::::::::::::::::::::::::::::::::::::::
:: Compare dates as strings because they are too long
:: to compare as numbers
IF "%NewestTopicDate%" GTR "%NewestTargetDate%" (
    CALL MakeBuild.cmd %1%
) ELSE (
    ECHO %DATE% %TIME% Targets are up to date. >> "%HomeDir%"\CheckAllBuilds.log
)

:: Report errors
::IF %ERRORLEVEL% GTR 0 ECHO An error occurred!

GOTO :EOF

::::::::::::::::::::::::::::::
: COMPARETOPICDATES
:: Compares the file dates of all HTM files in a given folder against
:: the date of the file saved in the NewestTopic env variable and
:: if one is newer, updates the variables with the newer file name and date
::ECHO Entered CompareTopicDates! >> CheckAllBuilds.log
CD %1%

FOR /F "usebackq delims==" %%F IN (`DIR /B /T:W /O:D "*.htm"`) DO (
    CALL :FileDateToString "%%F"
    IF "!Result!" GTR "!NewestTopicDate!" (
        SET NewestTopic=%%F
    )
:: Cannot execute multiple statements in nested IF, so evaluate
:: the second statement separately
    IF "!Result!" GTR "!NewestTopicDate!" (
    SET NewestTopicDate=!Result!
    )
)
CD ..
GOTO :EOF

:::::::::::::::::::::::::::::
: FILEDATETOSTRING
:: Parses user-friendly MM/DD/YYYY HH:MM AP strings into comparable strings
:: and converts 12 hour format time to 24 hour format
:: Get friendly file date string
SET Result=
SET FileDate=%~t1
:: Parse out hour
SET Hour=%FileDate:~11,2%
:: If AM, remove the zero. Bug.
:: IF %Hour:~0,1% == 0 SET Hour=%Hour:~1,1%
:: If PM, convert to 24 hour format
IF "%FileDate:~17,1%" == "P" SET /a Hour=%Hour%+12
:: Concatenate strings and save the result
SET Result=%FileDate:~6,4%%FileDate:~0,2%%FileDate:~3,2%%Hour%%FileDate:~14,2%
:: ECHO Result is: %Result%
GOTO :EOF

Last, but not least, is the batch file to perform the actual build. This file is also separate so that I can execute it to build an individual project. This one is relatively simple compared to the last and is also similar. It uses the DIR command to find the file name of the Flare project, which can be different from the folder name stored in Projects.txt. It executes madbuild by passing it the project file name with the -batch switch and the batch target named Build All that exists in every project. In my case, Build All builds all of the targets, not just the CHM. You can use the batch target name here, supply your own preferred batch target name, or change the batch file to build a single target.

This batch file stores its output in a separate log file for each project since there is so much info produced. This keeps the main output log file smaller and more readable. You can check individual builds by reviewing the individual log files.

Code: Select all

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
::                                                          ::
:: MakeBuild.cmd                                            ::
::                                                          ::
:: Batch file to automate building                          ::
:: one Flare target                                         ::
::                                                          ::
:: Created by Ken Billing                                   ::
:: Based on an example by Steve Salter                      ::
::                                                          ::
:: Called from CheckBuild.cmd                               ::
:: Accepts project name read from Projects.txt              ::
:: Logs results in <ProjectName>_Build.log                  ::
::                                                          ::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

@ECHO On
:: Set CMD window title
TITLE MakeBuild %1%

SETLOCAL

:: Log start of processing
ECHO %DATE% %TIME% Building batch target Build All for %1% >> CheckAllBuilds.log

:: Change to project directory
CD %1%
FOR /F "delims=" %%I IN ('DIR *.flprj /B') DO (
    "C:\Program Files\Madcap Software\Madcap Flare V6.1\Flare.app\madbuild" -project "%%I" -batch "Build All"> %%I_Build.log
)

CD %HomeDir%
:: Add build completion line to log
ECHO %DATE% %TIME% Targets of Build All built for %1% >> CheckAllBuilds.log
That's it!

These are provided as-is, without support, and as examples for building your own solutions. I'll try to answer general questions about hows and whys, but have a day job that requires most of my attention. I'm sure you all understand.

Flare itself might provide an option in batch targets someday to only build stale targets, so this could become obsolete. Until then, it works good for me!

Enjoy,
Ken
Ken Billing | Technical Writer
BlueCielo ECM Solutions
http://www.bluecieloecm.com

Image
lemalsaint
Jr. Propeller Head
Posts: 6
Joined: Mon Jul 05, 2010 6:39 am

Re: Command Line Build batch file

Post by lemalsaint »

Does the madbuild.exe, which I call for batcg-gerneration, connect to the source controll and check for changes before building the project?

The scenario is our buildserver which generates up-to-date help files on nightly build.

Thanks for help
Madcap Guru
Sr. Propeller Head
Posts: 238
Joined: Tue Mar 17, 2009 10:41 pm

Re: Command Line Build batch file

Post by Madcap Guru »

Madbuild does not connect to sourcecontrol you would need to create a batch file to pull it out of source control manually
Rick Ferrell
____________________________

Former Flare and Robohelp Support
Image
samjones6
Sr. Propeller Head
Posts: 168
Joined: Tue Mar 08, 2011 5:03 pm

Re: Command Line Build batch file

Post by samjones6 »

Ken Billing wrote:I submitted an enhancement request for conditional builds, by the way. Maybe 7?
This is pretty easy to do using either:

- A perforce trigger (if you use perforce version control)

or

- A continuous integration system (cruise control, finalbuilder, whatever) that can monitor your SCM system for new files in the project dir.


Me? I have the build system build web help every night, whether it needs it or not.....
samjones6
Sr. Propeller Head
Posts: 168
Joined: Tue Mar 08, 2011 5:03 pm

Re: Command Line Build batch file

Post by samjones6 »

Some discussion of madbuild limitations and how to work around em here:

http://forums.madcapsoftware.com/viewto ... 13&t=13131
ilyssaallison
Jr. Propeller Head
Posts: 3
Joined: Tue Aug 23, 2011 9:25 am

Re: Command Line Build batch file

Post by ilyssaallison »

Hello: Can someone please guide me through the process of building a project thorugh the command line. One I create a project, what do I do next to build from the command line? When I hit F6, it only outputs the project to my webpage. Thanks for your help!
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Command Line Build batch file

Post by NorthEast »

ilyssaallison wrote:Hello: Can someone please guide me through the process of building a project thorugh the command line. One I create a project, what do I do next to build from the command line? When I hit F6, it only outputs the project to my webpage. Thanks for your help!
Flare's help tells you how to build from the command line; see here:

http://webhelp.madcapsoftware.com/flare ... d_Line.htm
ilyssaallison
Jr. Propeller Head
Posts: 3
Joined: Tue Aug 23, 2011 9:25 am

Re: Command Line Build batch file

Post by ilyssaallison »

Hello : Does anyone know if it is possible to create a project by the command line? Thanks
LTinker68
Master Propellus Maximus
Posts: 7247
Joined: Thu Feb 16, 2006 9:38 pm

Re: Command Line Build batch file

Post by LTinker68 »

Create a project, as in you want to create a WebHelp project called ProjectB that's stored at C:\HelpProjects\, for example, as opposed to opening the Flare GUI and going to File > New Project?
Image

Lisa
Eagles may soar, but weasels aren't sucked into jet engines.
Warning! Loose nut behind the keyboard.
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Command Line Build batch file

Post by NorthEast »

ilyssaallison wrote:Hello : Does anyone know if it is possible to create a project by the command line? Thanks
You can't create a project using the madbuild command line; and I'm not aware of any other commands in Flare.
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: Command Line Build batch file

Post by RamonS »

The only thing that comes to mind is taking a standard project and making a copy of it. I do wonder about the purpose. Why create a new project from command line when you need Flare afterwards anyway to add content?
owilkes
Propeller Head
Posts: 68
Joined: Wed Apr 20, 2011 10:01 am
Location: London

Re: Command Line Build batch file

Post by owilkes »

Top thread, everyone. I initially was thinking 'but surely Batch Build takes care of this...' but then realised:

1. My build machine needs to get the latest content (Word documents) that it then reimports for the fresh morning build

- and I saw this could be done through the batch script.

2. We'd like to send an email to confirm when it is all done

- and this could probably be done through the mapisend.exe (I think, will need to test this)

3. (here's the point of the post...) We'd really like to also run some reports on the output - to confirm whether the new content that goes in brings a bunch of issues with it...

Any idea if this can be done? Is there any way to auto-generate my 'CriticalIssues' report after the build? Having to run them online seems like sooo Flare v2.

Also, does using this batch save the error logs anywhere?

Many thanks
techwriter31
Propellus Maximus
Posts: 551
Joined: Wed Mar 05, 2008 10:50 am

Re: Command Line Build batch file

Post by techwriter31 »

Last week I set up a batch target to build several help files on a daily basis, using the built-in Windows Task Scheduler option. After the targets are automatically generated, a log file is added to the Reports folder, with a list of any errors that may be present.
Kellie
owilkes
Propeller Head
Posts: 68
Joined: Wed Apr 20, 2011 10:01 am
Location: London

Re: Command Line Build batch file

Post by owilkes »

Thanks Kellie.

that tells me of any errors encountered during the build (which is nice) but it doesn't tell me, for example, of any unused content or unused styles etc - problems with the content, that the build itself doesn't register as an error.

Have submitted a feature request....
sdcinvan
Propellus Maximus
Posts: 1260
Joined: Wed Aug 21, 2013 11:46 am
Location: Vancouver, Canada

Re: Command Line Build batch file

Post by sdcinvan »

This is a fantastically detailed reference to the CLI but being mostly from 2006, is it still relevant for MadCap v9? I know that madbuild.exe still exists.
Shawn in Vancouver, Canada
Main tools used: Flare 11.x, InDesign, Google Docs, Lectora, Captivate.
Report bugs: https://www.madcapsoftware.com/feedback/bugs.aspx ▪ Feature requests: https://www.madcapsoftware.com/feedback ... quest.aspx[/i]
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Command Line Build batch file

Post by NorthEast »

You can still use madbuild in v9, it's covered in the help here: http://webhelp.madcapsoftware.com/flare ... d_Line.htm

Note that since this thread was started, you can now set up batch targets in Flare to build and publish multiple targets.
sdcinvan
Propellus Maximus
Posts: 1260
Joined: Wed Aug 21, 2013 11:46 am
Location: Vancouver, Canada

Re: Command Line Build batch file

Post by sdcinvan »

Dave Lee wrote:You can still use madbuild in v9, it's covered in the help here: http://webhelp.madcapsoftware.com/flare ... d_Line.htm

Note that since this thread was started, you can now set up batch targets in Flare to build and publish multiple targets.

Awesome, thank you Dave.
Shawn in Vancouver, Canada
Main tools used: Flare 11.x, InDesign, Google Docs, Lectora, Captivate.
Report bugs: https://www.madcapsoftware.com/feedback/bugs.aspx ▪ Feature requests: https://www.madcapsoftware.com/feedback ... quest.aspx[/i]
Post Reply