Configuring Ant for codeBeamer: Builds in Separate JVMs
Launching Ant in a Separate JVM
codeBeamer launches Ant in a separate JVM, instead of running it in codeBeamer's JVM. This has the following benefits:
Robust – memory (typically OutOfMemoryError) or other resource problems of the Ant sub-process will not affect codeBeamer at all. Anything can fail, the codeBeamer server will be up and running.
Atomic – each Ant invocation lives in its own sandbox. If you have a build sequence that first runs an Ant script, then calculates metrics with another script, the two steps will run in two separate JVMs.
Secure – you can customize what operating system user account will be used as the owner of the build process. Properly setting up the operating system access rights of this account, any kind of security model is supported.
Customizable – you can fine-tune your Ant environment by modifying the wrapper scripts that lauch Ant.
Better control over the classpath – collisions with codeBeamer's classloader will not affect your builds.
For your convenience, Ant is included in the standard codeBeamer installation, under its own directory $CODEBEAMER_HOME/ant. Customizing Ant (for example, adding optional task definitions) is absolutely possible, but you have to be very careful, because your changes will affect all the builds in all the projects. Beside extending Ant's functionality by adding new JARs to $CODEBEAMER_HOME/ant/lib, your primary customization points are the Ant wrapper scripts: $CODEBEAMER_HOME/ant/bin/ant.bat on Windows and $CODEBEAMER_HOME/ant/bin/ant on Linux (or other Unix-like) platforms. Modifying these, you can add your own loggers, add further project-independent properties or fine-tune the JRE commandline options. Customization happens in the same exact way as with regular Ant installations, so these are not detailed here, please refer to the Ant Manual http://ant.apache.org/manual/index.html.
Environment for Ant Builds
The initial set of runtime properties passed to Ant consists of the following:
CB_INSTALLDIR – codeBeamer home directory
CB_USER_ID – identifier of the user who initiated this build
CB_PROJ_ID – identifier of the project where this build belongs to
CB_PROJECT_NAME – name of the project that this build belongs to
CB_DOCDIR – directory where codeBeamer stores the documents that belong to this project
CB_SRCDIR – directory where codeBeamer stores the source code that belong to this project
CB_PROJECT_DIR – root directory of this codeBeamer project
CB_REMOTE_API_URL – connection point for the remote API of this codeBeamer instance (for internal use)
CB_PASSIVE_MODE – communication properties (for internal use)
Of course, all the additional properties that you specify in the "Customize Build" screen will be added, too. You can learn more about the details of invocation by studying the codeBeamer system log.
codeBeamer-specific Custom Ant Tasks
When writing your build scripts, you can use some special task definitions for better integration with codeBeamer. codeBeamer is shipped with the following custom Ant tasks:
CBExportReport – executes a codeBeamer report and saves its result to a local file in MS Excel format.
CBPost – posts a message to a codeBeamer forum.
CBRelease – uploads files from the local file system to the codeBeamer Document Management System.
Note that these task definitions are immediately available for your scripts, there is no need for adding <taskdef> elements.
The <CBExportReport> Task
Report ID to generate.
Relative or absolute path of the file where the generated report will be stored.
Boolean ("true" or "false"), whether to include tracker item comments in the report. Defaults to "false".
Boolean ("true" or "false"), whether to Include tracker item descriptions in the report. Defaults to "false".
Format of the report output file. Supported formats: "pdf", "excel", "wiki", "xml", "csv". Defaults to "excel".
The <CBPost> Task
Forum ID to post to.
Thread ID when replying to an existing thread.
'W' for Wiki, 'T' for plain text or 'H' for HTML.
Relative or absolute path of the file to attach.
The <CBRelease> Task
Comma-separated list of files to upload.
Target filename in the codeBeamer Document Manager if a single file is to copy.
Target dirname in the codeBeamer Document Manager. Defaults to the root directory.