• BuildOptionsDoc

• This document defines configuration "parameters" for the BuildRobot

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

• See also BuildDoc which describes how to actually build projects

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

• See also PackageDoc

<Build-Options-Doc>

<!--

• The following elements are required

-->

<Sandbox> Specify the sandbox path. The ROOTDIR

• environment variable is set to this value.

</Sandbox>

<ChangeLogInfoFile> Specify the name of the file (relative to the sandbox)

• that holds the last build stamp. This file is used to generate change comments and contains a single line which is the last CVS tag applied using the build stamp. This file is checked out using <Branch> or <TagOverride> if specified. New ChangeLogInfoFile files should be checked into CVS, as empty files, prior to running the build robot.

</ChangeLogInfoFile>

<ConfigMapFile> Specify the filename, relative to the sandbox,

• of a ConfigMap document. Defaults to configMap.xml in the <BuildModule>

</ConfigMapFile>

<BuildFile> Specify the path (relative to the sandbox) of

• the build XML file. Can be an absolute path.

</BuildFile>

<MajorBuildDescription>

• Specify the name of the build type. This value currently doesn't appear anywhere.

</MajorBuildDescription>

<BuildDescription> Specify the name of this particular build. Appears

• in the web page that lists all builds of a particular type.

</BuildDescription>

<Configuration> Specify a Meta-Configuration name to build

• One of (for VC++): Win32 Debug Win32 Unicode Debug Win32 Release Win32 Unicode Release Win32 Release Symbols Win32 Unicode Release Symbols

  alldebug (for Java) allrelease (for Java)

  You may also invent your own configuration names.

  Multiplicity: 1..*

• <Sequence>1<Sequence>

  • Specifies that the configuration must be built and packaged before another configuration is processed. This is typically not specified for VC++ configuration but is specified with Java configurations. The difference is that Java .class files are stored in the same directory for both debug and release. On the other hand, VC++ projects output targets to different directories depending on the build type, so the build robot can build all of the configurations up front and then package everything up.

</Configuration>

<WebPath> Specify the UNC path of the root where the build

• web pages are stored (\\acme\c$\inetpub\wwwroot\build)

</WebPath>

<WebAddress> Specify the URL of the top-level build page which

• corresponds to WebPath

</WebAddress>

<WebSubdir> Specify the path (relative to WebAddress) to the webpage

• containing builds of this type

</WebSubdir>

<!--

The following elements are optional

-->

<CVSROOT> Specify the CVS root </CVSROOT>

<BuildModule> Specify the module of the 'build' files,

• e.g., the module that contains configmap.xml. This module generally contains XML configuration files used by the build robot and can also include SLN and DSW files, but these files can be located anywhere in the CVS repository. Defaults to 'build'

</BuildModule>

<BuildStamp> A build stamp uniquely identifies a build.

• When a build fails, you can to specify the stamp of the build that failed so that a build can be started from where it left off. Otherwise leave this blank and stamps will be generated automatically

</BuildStamp>

<UseLastBuildStamp>1</UseLastBuildStamp>

• If this element is present, the build robot will use the last build stamp in the file specified in <ChangeLogInfoFile>. This file must already exist in the sandbox -- it is not checked out. This feature is handy when you want to break a large build process into two build processes. In order for this to work properly the <WebSubdir> or <WebPath> elements must be different in the two Build-Option-Doc documents.

<Tag> Provide a CVS tag that will be used to tag all of

• the files retrieved from the sandbox. See <ShouldTag/> below. The build robot also tags all files using the "build stamp" as the tag name, unless you specify <NoBuildStampTag>1</NoBuildStampTag>.

  Multiplicity: *

</Tag>

<BuildStampPrefix> Specify the prefix for automatically

• generated build stamps

</BuildStampPrefix>

<Branch> Specify the CVS branch name to pull code from

• This is ignored for modules that specify a <Tag> in the build XML file.

</Branch>

<TagOverride> Specify the CVS tag name to use, even if modules

• listed in the build XML file specify a <Tag>

</TagOverride>

<BuildNumberFile> Specify the name of the file, relative to

• the sandbox, that contains the build number and build stamp. This file can be branched (see ShouldReadBuildNumberFilesFromBranch below).

  The build robot increments the build number and checks in the new number.

  The build number and version file should be different files. VersionFile and BuildNumberFile are separate to allow the version to change based on the branch while the build number can continue on to infinity.

  See an example

  Multiplicity: *

</BuildNumberFile>

<VersionFile> Specify the name of the file that contains product

• version information, relative to the sandbox. The version string is displayed in the build web page and it's embedded in the version resource of DLLs and EXEs. See an example.

  Note: This setting is only applicable to VC++ and vs.NET C++ projects, because it is used to change the version resource in resource files (.RC).

  Multiplicity: *

</VersionFile>

<Copyright> Specify the copyright text to be used in Visual Studio project

• resource (.RC) files. Alternative to VersionFile above.

</Copyright>

<Company> Specify the company name to be used in Visual Studio project

• resource (.RC) files. Alternative to VersionFile above.

</Company>

<Version> Specify the version text to be used in Visual Studio project

• resource (.RC) files. Alternative to VersionFile above.

</Version>

<PackageDestination> When ZIP files need to be stored on a different machine than

• the main webserver (WebPath), specify a PackageDestination, which should be a UNC, where these files should be stored. Also specify <PackageURL>. <WebSubdir> is appended to the specified directory.

</PackageDestination>

<PackageURL> Specify the root URL where packaged files from the build

• are located. Can be file or http protocol. Should be specified if <PackageDestination> is specified.

  If using the http protocol, allow listing directories on the web server.

</PackageURL>

<DefaultZipCompression>

• Specify 0 for no compression and 9 for maximum compression (defaults to 9).

</DefaultZipCompression>

<!--

-- Notification

--

-- Notify users that a build has started and ended via Email,

-- News (NNTP), Windows "net send", and/ir IRC chat.

--

-- See ShouldEmailNotification and

-- ShouldSuppressBuildStartNotification below

-->

<NetNotify>

• Provide the name of a Windows user or computer to notify via a Windows network message. Note that Microsoft is going to turn off the "Messenger Service" by default in future versions of Windows (beginning in Windows Server 2003, I think). Multiplicity: *

</NetNotify>

<SMTPNotify>

• Provide email address(es) to send notification to. Can be comma or semicolon delimited. Semicolon delimiter only works in 1.8.1 and later. Can also be specified in the GlobalsDoc. Multiplicity: *

</SMTPNotify>

<NNTPServer>

• Provide the name of a newsgroup server to post notifications to. Can also be specified in the GlobalsDoc. Multiplicity: 0,1

</NNTPServer>

<NNTPDebug>

• Specify 1 to log all NNTP conversations to the build log file. Can also be specified in the GlobalsDoc. Multiplicity: 0,1

</NNTPDebug>

<Newsgroup>

• Provide the name of the newsgroup(s) to post notifications to. This can be a list of names depending on the NNTP server. Can also be specified in the GlobalsDoc under BuildNewsgroup. Multiplicity: 0,1

</Newsgroup>

<IRCServer>

• Provide the name of an IRC Server to post notifications to. Multiplicity: 0,1

</IRCServer>

<IRCServerPort>

• Provide the port number of an IRC Server to post notifications to (optional). Multiplicity: 0,1

</IRCServer>

<IRCChannel>

• Provide the name of the IRC Channel to send notifications to. Multiplicity: 0,1

</IRCChannel>

<IRCNick>

• Provide the name of the IRC nick to use when sending notifications. Defaults to buildmaster. Multiplicity: 0,1

</IRCNick>

<!--

-- Flags

--

-- To turn on a feature, set the element text to 1

-->

<NoCVS>1</NoCVS>

• Suppresses all CVS activities

<NoMSDEV>1</NoMSDEV>

• Ignore Microsoft Developer Studio 6.0 DSP and DSW files (doesn't affect Visual Studio 2003 projects)

<ShouldEmailNotification>1</ShouldEmailNotification>

• Send an email, IRC, newsgroup post, etc. when the build process begins and ends. Uses NetNotify

<ShouldSuppressBuildStartNotification>1</ShouldSuppressBuildStartNotification>

• Don't send notification when a build starts. Only send notification when the build process ends.

<ShouldClearLog>1</ShouldClearLog>

• Clear the log file before proceeding

<ShouldCleanSandbox>1</ShouldCleanSandbox>

• Empty the sandbox before retrieving code

<ShouldGetSource>1</ShouldGetSource>

• Retrieve source code

<ShouldIncrementBuildNumber>1</ShouldIncrementBuildNumber>

• Increment the build number

<ShouldUpdateVersionResources>1</ShouldUpdateVersionResources>

• Modify the resource file for the project - modify Visual Studio Projects' version resource to hold the build number, product version, etc.

<ShouldBuild>1</ShouldBuild>

• Build (compile, etc.) all projects

<OutputAllProjects>1</OutputAllProjects>

• Output all projects to the web application, even if there are no warnings or errors. This is handy for testing the build robot initially.

<ShouldTag>1</ShouldTag>

• Tag all files retrieved from CVS after the build has completed with the build timestamp and/or the tag specified in the <Tag> element.

<ForceTag>1</ForceTag>

• Tag files even if there were build errors.

<NoBuildStampTag>1</NoBuildStampTag>

• Do not tag files using the build timestamp. When this element is not present, the build robot tags all files retrieved from CVS after all builds have completed. The files are tagged twice if the <Tag> element contains a CVS tag name.

  When this element present, the build robot will no longer be able to create daily change log summaries.

<ShouldPackage>1</ShouldPackage>

• Package the target files into a ZIP archive and place on the web site for download. Only packages if there are no build errors.

<ShouldForcePackage>1</ShouldForcePackage>

• Package the files even if there are build errors

<ShouldPostToWeb>1</ShouldPostToWeb>

• Post this build to the build list on the build website

<ShouldOutputXML>1</ShouldOutputXML>

• Generate build status to be viewed on the website

<ShouldCreateManifest>1</ShouldCreateManifest>

• Generate a manifest file that contains all of the files that were retrieved from CVS

<ShouldCreateChangeLog>1</ShouldCreateChangeLog>

• Generate a change log containing check-ins made by developers since the last build

<ShouldUpdateChangeLogInfo>1</ShouldUpdateChangeLogInfo>

• Update the last build stamp file only if there were no errors when building the projects

<ShouldForceUpdateChangeLogInfo>1</ShouldForceUpdateChangeLogInfo>

• Update the last build stamp file even if there were errors when building the projects

<ShouldReadBuildNumberFilesFromBranch>1</ShouldReadBuildNumberFilesFromBranch>

• Read and modify build number files in the specified CVS branch (see Branch above)

<ShouldEmailChangeLog>1</ShouldEmailChangeLog>

• Post CVS change log newsgroup if specified. SMTP email is not supported because the file could become excessively large.

<LogPackage>1</LogPackage>

• Log extra information during packaging

<LogProjConfig>1</LogProjConfig>

• Log extra project configuration inforation during the build process

</Build-Options-Doc>