• BuildDoc

• See BuildRobot

• See BuildOptionsDoc for additional configuration parameters for the BuildRobot.

• See PackageDoc

• This document can contain expressions -- for example to reference environment variables. See BuildRobotExpressions.

• This information is accurate for 1.8.2 and later. This documentation is no longer accurate for previous versions of the toolkit.

<Build-Doc>

<Source> Specify the directory to retrieve.

• Multiplicity: *

  This tag is optional. Projects listed in the <Build> tags are loaded on the fly if they aren't specified in <Source>.

• <Tag> Specify the tag (or branch) to get.

  • Multiplicity: 0,1

  </Tag>

  <Path> Specify the path, relative to the

  • sandbox, to change the directory to before running the cvs checkout command

    Multiplicity: 0,1

  </Path>

  <Dir> Specify the path, relative to either the

  • sandbox or the <Path> (if given), to load the files into. Refer to the cvs documentation for the checkout -d option. Note that cvs doesn't accept '/' symbols in the path, specified in -d option. Backslashes ('\') should be used instead

    Multiplicity: 0,1

  </Dir>

  <NoSubdirs>1</NoSubdirs>

  • Don't get subdirectories when retrieving files from CVS

    Multiplicity: 0,1

  <DisableCheckoutVerification>1</DisableCheckoutVerification>

  • When the element text is 1, this causes the build robot to avoid verifying that the specified file or directory was checked out. Useful when the Source element contains a CVS module name instead of a physical directory name. Version 1.8.2.15 and later.

    Multiplicity: 0,1

  <CVSROOT> The CVS "root" to use when performing the CVS command

  • Multiplicity: 0,1

  </CVSROOT>

  <CVSGlobalOptions>

  • CVS options specified before the CVS command

    Multiplicity: 0,1

  </CVSGlobalOptions>

  <CVSOptions> CVS options specified after the CVS command

  • Multiplicity: 0,1

  </CVSOptions>

</Source>

<Link> This causes a hyperlink to be added to the "links" section

• of the web application.

  Multiplicity: *

• <LinkIf> If the value evaluates to zero (0) or blank string,

  • this Link element is ignored.

    Multiplicity: 0,1

  </LinkIf>

  <Name> Specify the name of the hyperlink

  • Multipicity: 1

  </Name>

  <Href> Specify the hyperlink URL for the anchor tag

  • Multiplicity: 1

  </Href>

  <Configuration> Specify a configuration name that this link applies to.

  • This link is ignored if the BuildOptionsDoc doesn't include at least one of the configurations provided.

    Multiplicity: *

  </Configuration>

</Link>

<Build> Specify a file (.DSP, .DSW, .MAK, .IDL, .SLN, .VCPROJ,

• MAKEFILE) to build, or an executable or script to run.

  See here for information regarding script support.

  If the file you specify is checked into CVS, the filename should be relative to the sandbox.

  Files are processed in the order in which they appear in this document.

  You can specify a directory name. It's assumed that the directory contains a project (DSW or DSP) file with the same name as the directory.

  You can specify the path (relative to the sandbox) of an IDL file. The file will be compiled into a TLB via 'mktlb.pl'. You may pass parameters to mktlb.pl via <Parameters>.

  For scripts and executables, specify the path of the command to execute with no arguments. List arguments in the <Parameters> tag. The current directory is the root of the sandbox unless you append a <Path> tag.

  The external program or makefile can write to "bld.txt" in the current directory in order to transmit status back to the build script. bld.txt contains one line of the form "errors, warnings" in which "errors" and "warnings" are numbers. The script can also write to bldlog.txt, containing the output of the script - if this file is not found, the STDOUT output is written to the log.

  See also <ScriptIsOutsideSandbox> and <Async>.

  Multiplicity: *

• <BuildIf> Provide a string or expression. When the value

  • evaluates to zero (0) or blank, this build tag is ignored.

    Multiplicity: 0,1

  </BuildIf>

  <DisableCheckoutVerification>1</DisableCheckoutVerification>

  • When the element text is 1, this causes the build robot to avoid verifying that the specified file or directory was checked out. Useful when the Source element contains a CVS module name instead of a physical directory name. Version 1.8.2.15 and later.

    Multiplicity: 0,1

  <Tag> Specify the name of a CVS tag to used when and

  • if files need to be checked out from CVS

    Multiplicity: 0,1

  </Tag>

  <CVSROOT> The CVS "root" to use when performing the CVS command

  • Multiplicity: 0,1

  </CVSROOT>

  <CVSGlobalOptions>

  • CVS options specified before the CVS command

    Multiplicity: 0,1

  </CVSGlobalOptions>

  <CVSOptions> CVS options specified after the CVS command

  • Multiplicity: 0,1

  </CVSOptions>

  <NoSubdirs>1</NoSubdirs>

  • If source code needs to be retrieved from CVS, don't get subdirectories.

    Multiplicity: 0,1

  <Key> Should contain an incrementing number. It is used to

  • generate a unique string in order to determine whether the build robot has already built the project -- this unique string consists of the text from the following elements:

    Build, Path, Parameters, Key, Targets

    Multiplicity: 0,1

  </Key>

  <Once>1</Once> Process this <Build> step only once, regardless

  • of the number of configurations that will be built.

    Multiplicity: 0,1

    Note: This does not work with vs.net or VC++ projects

  <Configuration> Specify the name(s) of the build configuration(s) that this

  • entry applies to. If none are specified, all configurations are built. This must be a meta-configuration name.

    Multiplicity: *

  </Configuration>

  <Sequence>1</Sequence>

  • Build and package the project one configuration at a time. Java projects output to the same output directory regardless of Debug or Release builds, so building multiple configurations requires an intermediate package step. All configurations marked with <Sequence/> are built under a single configuration, and then the package module is invoked, but only for those packages that are marked <Sequence/>.

    You must specify <SequenceConfiguration>s in the build options document in order for <Sequence> projects to be built.

    Multiplicity: 0,1

  <AfterTagging>1</AfterTagging>

  • This is no longer supported.

  <IfNoErrors>1</IfNoErrors>

  • Only process this item if there were no build errors.

    Multiplicity: 0,1

  <Clean>1</Clean>

  • When used with java makefiles, it sets the targets to "clean output thirdpartyjar", even if there are already targets specified.

    When used with SLN or vcproj files, it sends /clean to devenv without building anything.

    Multiplicity: 0,1

    Note: This only works with vs.NET projects and the Java makefiles

  <Rebuild>1</Rebuild>

  • Remove build outputs before building.

    When used with Java makefiles, it adds the targets "clean output thirdpartyjar"

    Note that when used with SLN files, this can have unexpected consequences because it deletes all targets for all projects in the SLN file, and unless you order the projects carefully in the SLN file, the build can fail even if you used 'mktlb.pl' program.

    Multiplicity: 0,1

    Note: This only works with vs.NET projects and the Java makefiles

  <Exclude> Specify a project to exclude from the build

  • If a project is not given, the entire build entry will be excluded. Project names should be DSP filenames relative to the sandbox.

    Multiplicity: *

    Note: This only works with DSW files.

  </Exclude>

  <CheckExitCode>1</CheckExitCode>

  • Not for VC++ or VS.NET projects. Check the exit code of executables. Nonzero exit code is considered to be an error. Generally used in replace of <Filter>.

    Multiplicity: 0,1

  <Filter> Specify a script to execute which is run after

  • the script. The script specified is given one parameter which is the name of the file that contains the output of the executed script (STDERR and STDOUT) in the <Build> element. The filter script writes to bld.txt and bldlog.txt in the current directory. The toolkit ships with several custom filters. See here.

    Multiplicity: 0,1

    Note: This does not apply to VC++ and vs.NET projects

  </Filter>

  <ScriptIsOutsideSandbox>1</ScriptIsOutsideSandbox>

  • When set to 1, the sandbox's root path is not added to the script specified in the <Build> element. This also causes the build robot to avoid checking out the script from CVS. See also the <Path> element.

    Multiplicity: 0,1

    Note: This does not apply to VC++ and vs.NET projects

  <Async>1</Async>Do not wait for the script or executable

  • to finish. Generally used with <Execute>

    Multiplicity: 0,1

    Note: This does not apply to VC++ and vs.NET projects

  <Path> The directory to run the command in, either as an

  • absolute pathname or relative to the sandbox. If relative to the sandbox, the directory is checked out of CVS (if it doesn't already exist).

    Multiplicity: 0,1

    Note: Does not apply to VC++ and vs.net projects.

  </Path>

  <NoSubdirsForPath>1</NoSubdirsForPath>

  • If 1, don't get subdirectories from CVS if <Path> is specified and the directory needs to be retrieved from CVS. Version 1.8.2.15 and later.

    Multiplicity: 0,1

  <Parameters> Parameters for the script. This can be overridden

  • by the config-map file. This is a space-delimited set of parameters. Each parameter supports $ and = expressions -- if an = expression needs to contain a space you should use <Param> instead.

    Multiplicity: 0,1

    See also Targets and Param.

    Note: Does not apply to VC++ projects.

  </Parameters>

  <Param> Specify one parameter for the script. Must

  • leave <Parameters> blank in order for this tag to be recognized. Supports $ and = expressions. If the value evaluates to a blank string, it is ignored.

    Multiplicity: *

    Note: Does not apply to VC++ projects.

  </Param>

  <Make>1</Make> Force using make (default if filename is 'makefile'

  • or ends with .mak)

    Multiplicity: 0,1

  <Nmake>1</Nmake>Force using Microsoft's nmake program instead of make

  • Multiplicity: 0,1

  <Targets> Provide text that is sent to make or nmake as the

  • targets to build. If not provided for makefiles, the configuration name is used. This can be overridden by the config-map file.

    Multiplicity: 0,1

    Note: Does not apply to VC++ and vs.net projects.

  </Targets>

  <Multiple>1</Multiple>

  • Indicates that multiple projects are built via "make" or a batch file. "Multiple projects" means that one command builds code (e.g., Java code) in multiple directories. The build robot will report errors separately for each directory. The build robot documentation specifies the expected format of the output -- see http://www.devguy.com/fp/cfgmgmt/tools/buildRobot.htm#multiple

    Multiplicity: 0,1

    Note: This does not work with vs.net or VC++ projects

  <Ant>1</Ant> This indicates that the command runs Apache Ant. The

  • build robot will report errors separately for each directory that contains Java code.

    Multiplicity: 0,1

  <RepeatUntilSuccessful>

  • If errors occur, re-execute the command until there are no errors. Only applicable when <Execute> is present and <Multiple> is not. Provide the maximum number of retries -- for example, if you provide the value 1, the build robot will make one additional attempt to execute the command.

    Multiplicity: 0,1

    Note: This does not work with vs.net or VC++ projects

  </RepeatUntilSuccessful>

  <IgnoreErrors>1</IgnoreErrors>

  • Ignore any errors encountered while building the project(s)

    Multiplicity: 0,1

  <OutputAllProjects>1</OutputAllProjects>

  • Output all projects built to the web application, even if there are no warnings or errors.

  <LogFile> Specify the filename to send output to -- if the

  • file already exists, an underscore is added to the name until a unique name has been created. The name you provide doesn't require an extension -- ".txt" is always used.

    Multiplicity: 0,1

  </LogFile>

  <ProjectName> Specify the name of the project, which is shown in

  • the build web page when warnings or errors occur.

    Multiplicity: 0,1

  </ProjectName>

</Build>

<Package> Packages tell this script how to copy the resulting files.

• Specify the name of the package file to open. See PackageDoc.

  Multiplicity: *

• <PackageIf> If the value evaluates to zero (0) or empty string,

  • this Package element is ignored.

    Multiplicity: 0,1

  </PackageIf>

  <Configuration> Specify the configuration name that this package applies

  • to. If there are no configurations listed, this package is processed exactly once.

    Multiplicity: *

  </Configuration>

  <Sequence>1</Sequence>

  • Causes the package to be processed after finishing a configuration instead of building all configurations up front. This is needed for Java projects because the debug and release class files go into the same directory. You must specify <SequenceConfiguration>s in the build options document in order for <Sequence> packages to be executed.

    Multiplicity: 0,1

  <Module> Name of a module to package (specified in the package xml file) </Module> Multiplicity: *

  <Project> Name of a project to package (specified in the package xml file) </Project> Multiplicity: *

  <Type> Type of package to export (specified in the package xml file) </Type> Multiplicity: *

  <Destination> Alternative to <Zip> and <Copy>

  • The destination defaults to the location of the build web page or a build-specific directory under the directory provided via the "PackageDirectory" option in the build configuration file.

    Provide the full path where the package should be written to, e.g., \\machinename\inetpub\wwwroot. Or provide a path that is relative to the "web subdir." If the value is an absolute path name, the build robot does not create a "Link" in the web app for this <Package> entry. Presumably the destination would not be traversable over the web, so the link is omitted.

    Multiplicity: *

  </Destination>

  <Copy> Alternative to <Zip>

  • Set the element text to 1 or provide the directory where the files should be copied to, relative to the "package" directory for the current build. Adds a hyperlink to the specified directory on the build web page.

    Multiplicity: 0,1

  </Copy>

  <Zip> Alternative to <Copy>

  • Zip up the files and create a hyperlink to the zip archive on the build web page. Set the element text to 1 or provide the name of the zipfile archive.

    Multiplicity: 0..1

  • <Store/> Store only - no compression

    • Multiplicity: 0,1

  </Zip>

  <LinkName> The name of the hyperlink to the ZIP file

  • or <Copy> directory.

    Multiplicity: 0..1

  </LinkName>

</Package>

</Build-Doc>