Advanced build features

The WebSphere Commerce Build tool provides many advanced build features to support complex configurations. Use these features to improve your build process.


Extracting source code by incremental update

The WebSphere Commerce Build tool provides an option to extract source code by incremental update instead of a full checkout. This option allows quicker source code extraction time, especially when the quantity of changes between build levels is small. To enable the update mode for source code extraction, follow the steps below:

  1. Open WCB_installdir/build.properties with a text editor and set the following properties:

    • Set the extract.update.mode property to true, so that the source code extraction process will not delete the source directory but instead update it.

    • Set the source.dir to a static path. The default path ${basedir}/source/${build.label} is not static because build.label might change every build. A static path can be, for example, ${basedir}/source. If the multiple build type support feature is used, it can be set to, for example, ${basedir}/source/${build.type}, so that each build type has its own independent static source directory for incremental updates.

  2. Set up the source extraction Ant script with one of the Ant script samples for various SCMs that were updated to support incremental update.

When we use this feature, any operations that modify source code must be done in the working directory instead of the source directory if you customize the build process. This practice ensures that incremental updates to the source directory can be done accurately.


Excluding static web assets in web modules from the deployment packages

The WebSphere Commerce Build tool provides a way to exclude static web assets in web modules from the deployment packages. This is useful for reducing the process usage of building and deploying static content, such as image and HTML files, that are rarely changed. For each web module that requires exclusion of static web assets, follow the steps below:

  1. If the exclusion is achieved by including a subset of files, create a new file called web-content-includes.txt at the root of the web module, then add the inclusion patterns, relative to the root of the web content directory in the web module, to the file.

  2. If the exclusion is achieved by excluding a subset of files, create a new file called web-content-excludes.txt at the root of the web module, then add the exclusion patterns, relative to the root of the web content directory in the web module, to the file.

  3. Check in the new files to the repository for use by the build process.

The build process detects the existence of these files and uses them to exclude static web contents from web modules. One implication of using this feature is that the deployment package might not be able to set up a new environment since not all assets are included. Ensure that the users of the deployment packages are aware of this limitation. Consider the example where all images from the Aurora store folder in the Stores module are to be excluded from the deployment packages. To use this feature, we can create an exclusion file workspace/Stores/web-content-excludes.txt in the repository with the following contents:


Excluding EAR assets from the deployment packages

The WebSphere Commerce Build tool provides a way to exclude EAR assets from the deployment packages. This option is useful for excluding EAR assets that are not changed by our customization, and Java EE modules with bindings specific to the development environment that causes configuration and application startup issues if they were deployed to another target environment. Complete the following steps to use this feature:

  1. If the exclusion is achieved by including a subset of files, create a new file called ear-dir-includes.txt at the root of the WC project, then add the inclusion patterns to the file.

  2. If the exclusion is achieved by excluding a subset of files, create a new file called ear-dir-excludes.txt at the root of the WC project, then add the exclusion patterns to the file.

  3. Check in the new files to the repository for use by the build process.

The build process detects the existence of these files and uses them to exclude EAR assets. One implication of using this feature is that the deployment package might not be able to set up a new environment since not all assets are included. Ensure that the users of the deployment packages are aware of this limitation.

Consider the example where all JAR files in the root of theWC project are to be excluded from the deployment packages. To use this feature, we can create an exclusion file workspace/WC/ear-dir-excludes.txt in the repository with the following contents:


Stand-alone properties file encoding utility

For convenience, a stand-alone properties file encoding utility is included in the WebSphere Commerce Build tool. After the setenv script is configured when you configure the build settings, complete the following steps to use the utility:

  1. Change directory to WCB_installdir.

  2. Run the following command, where file is the properties file to be encoded:

    • (Windows) wcbd-encode-properties.bat -Dfile=file

    • (AIX) (Linux) wcbd-encode-properties -Dfile=file


Support for multiple build types

The WebSphere Commerce Build tool supports multiple build configurations based on build type. To use this feature, complete the following steps below to configure and run the build process:

  1. When you configure the build settings, instead of creating WCB_installdir/build.properties and WCB_installdir/build.private.properties, create the files as WCB_installdir/build-build-type.properties and WCB_installdir/build-build-type.private.properties, where build-type is an identifier for the build type.

  2. When you run the build process, specify the following option when you call the wcbd-ant.bat or wcbd-ant command: 

      -Dbuild.type=build-type

The build type identifier is added to the log directory name and the deployment package file name. A new build.type property is also defined in the wcbd-build-info.properties file that is generated and added into the deployment packages.


Email notifications of build status

The build process can be configured to send email notifications upon success or failure. For failure notifications, the archived build log file is attached for convenience. Follow the steps below to enable this functionality in the build settings:

  1. Open WCB_installdir/build.properties with a text editor and set the properties under the "Properties for email notification" section. Refer to the comments in the file for details.

  2. If the SMTP server requires authentication, open WCB_installdir/build.private.properties with a text editor and set the following properties:

    • mail.user

    • mail.password


Additional logging and tracing

Ant provides both a verbose and a debug option to provide additional tracing that is useful for problem determination. To enable verbose mode, provide either the -v or -verbose option when you call the wcbd-ant.bat or wcbd-ant command to run the build process. Likewise, to enable debug mode, provide either the -d or -debug option when you call the wcbd-ant.bat or wcbd-ant command to run the build process.

The WebSphere Commerce Build tool provides a custom logger that captures performance data of the build process. The logger outputs the start and end time, and the elapsed time for each target that is run, to the console. The following is a sample section of the performance data that is produced by the logger for the extract target in the build process:

To use the logger, provide the following options when you call the wcbd-ant.bat or wcbd-ant command to run the build process:

Note: Ant does not capture the verbose, debug nor logger output in the log file that is normally generated by the build process. The additional output is displayed only in the console, therefore the standard output and error streams should be redirected to a separate log file when you run the build process with these logging and tracing options. This logging can be done by appending the following options when you call the wcbd-ant.bat or wcbd-ant command to run the build process, where log-file is the log file to which the console output is written:


Debug options for EJBDeploy

The following properties in the build settings provide a mean to generate more debug information for EJBDeploy:

Debug options for EJBDeploy
Property name Usage
ejbdeploy.codegen Set this property to true to keep the Java source files generated by EJBDeploy.
ejbdeploy.keep.generated Set this property to true to keep the working directory after EJBDeploy completes. The working directory is typically ${working.compile.dir}/${type}/${module.name}
ejbdeploy.quiet Set this property to false to disable quiet mode for EJBDeploy so that detailed logging information are displayed.
ejbdeploy.no.validate Set this property to false to display validation messages from EJBDeploy.
ejbdeploy.trace Set this property to true to enable internal tracing for EJBDeploy.
ejbdeploy.jvm.max.memory Set this property to a higher value than the default 256 MB if EJBDeploy is running out of memory.

If the command fails in the build process, open WCB_installdir/build.properties with a text editor to set these properties, and then run the build process again.


Related concepts
WebSphere Commerce Build tool repository structure


Related tasks
Setting up source extraction Ant script
Configure packaging settings
Building packages


Related reference
Build configuration references