Usage Tips

•	Check out the sample projects that are installed with Visual Build. A shortcut to the samples folder is available in the Visual Build group in the Start menu.

•	See the Visual Build FAQ for additional samples and answers to common questions.

•	Bracket characters [ and ] within a field normally denote a script expression to be inserted into a field (i.e., [vbld_GetFileContents("filename")]); to insert literal brackets, use two bracket characters [[ or ]].

•	The percent sign character % within a field normally denotes a macro to be expanded within a field (i.e., %PROJFILE%); to insert a literal percent character, use two percent characters %%.

•	To prompt the user for a value during the build (for instance to provide a unique build number), there are several methods that can be used:

Reference an undefined macro in a project step (i.e., %MY_PROMPT%). When that step is built, a dialog will be displayed prompting the user for the macro value (applies only to the GUI App). After the value has been entered, a temporary macro will be created with that value, and that value will be substituted in all steps that reference it (the temporary macro value will be discarded when the Visual Build instance is closed or rebuilt). One drawback to this method is that the user needs to know what an appropriate value for the macro should be.

2)	To display a custom message when prompting, create a Run Script action which uses the InputBox function to prompt for a value, and store the value in a temporary macro.

If you want to provide even greater control over the prompted values (for instance, to prompt for many inputs or provide custom drop-down choices), you can create a custom user action (in the language of your choice) which prompts for all values and stores the user inputs in temporary macros. All three methods are demonstrated in the Prompt.bld sample.

•

Group your project steps by different indentation levels to improve organization and to take advantage of relative Start In paths. Clicking the check box for a step quickly checks or unchecks all child steps as well. Clicking the folder icon of the top level Project steps item checks or unchecks all steps in the project.

•	To force an individual step with a status of Completed or Skipped to be built again, rebuild the step or uncheck (this clears its status) and check the step again.

•	Wrap Run Program action command filenames and parameters in double quotes (") if they contain spaces so that they are treated as a single argument.

•

Any internal or external OS command, batch file, or command script can be called prefixing a Run Program command with the %DOSCMD% call system macro. This includes COPY, XCOPY, MKDIR, RMDIR, MOVE, ATTRIB, FIND, DEL, DIR, FORMAT, SYS, etc., plus any batch/CMD language statements (FOR, TYPE, ECHO, NET, etc.) or files. The output will be captured and displayed in the Output pane and log file if logging is enabled.

•	To retrieve the contents of a file and use it within a step of the build, it can be returned via the system script function [vbld_GetFileContents("filename")].

•	To write the contents of a file to the build log, use a Run Program action with a command of %DOSCMD% TYPE "<filename>". or a Log Message action with a message of [vbld_GetFileContents("filename")].

•

Several methods are available for modularizing builds. First, subroutines can be defined and called from a project (subroutines can call other subroutines). Global subroutines can be used for functionality that is needed across multiple projects. And chaining can be used to invoke other Visual Build projects using the VisBuildPro Project action.

•	There are many ways to pass dynamic values to or communicate between multiple projects:

1.	Temporary macro values can be passed on the command-line.

The global macros collection can be used to communicate in both directions. Any changes to global macros are saved before each step is built and reloaded after a step completes if they were modified externally, and the global macros are automatically saved when the Application object is disposed of. Global macros can be updated using a Set Macro action or a Run Script action (using the code Application.Macros(vbldGlobal).Add "MY_MACRO", "some value"); the macros can be read by referencing the macro in a step (i.e., %MY_MACRO%) or via the script code vbld_AllMacros.Item("MY_MACRO").Value.

3.	Values can be read and written from the registry via the Write Registry and Read Registry actions.

4.	Values can be read and written from a file via the Write INI and Read INI actions.

5.	Values can be read and written from an XML file (see the XML.bld sample).

•

Define a default value for a macro in a project macro (for instance, to use in a conditional build rule to determine which parts of a project are built), and then override that macro via a temporary macro (by passing as a parameter in a VisBuildPro Project action) in the situations where the default need to be overridden.

•	Several methods are available use a different log file for each project:

1.	Enter the filename on the Logging tab of the Project Properties dialog.

2.	Define a LOGFILE project macro.

3.	To use project-specific log files for every project, use a filename of %PROJDIR%\%PROJROOT%.<ext> on the Logging tab of the Application Options dialog.

•	To apply the same conditional build rule to multiple steps, add a Group step that defines the build rule, then indent all the conditional steps below this one.