Advanced build features

• Support for multiple target environments
• Extracting source code by incremental update
• Excluding static Web assets in Web modules from the deployment packages
• Excluding EAR assets from the deployment packages
• Stand-alone properties file encoding utility
• Support for multiple build types
• Centralized server deployment
• E-mail notifications of build status
• Additional logging and tracing
• Debug options for EJBDeploy

Support for multiple target environments

The Build and Deployment tool supports target-specific deployment of database and EAR assets by employing a specific file structure and naming convention. Deployment targets can generally be categorized by use, such as production, test, and development. Each deployment target should be assigned an identifier which is used by the tool to facilitate target-specific deployment. For example, the values prod, test, and dev can be used as identifiers for the aforementioned deployment targets respectively.

Uncompressed EAR assets (such as EAR properties files, EAR XML files, and files in Web modules) can employ a specific file naming convention to identify the specific target environment to which the files are deployed. A file of name name.extension specific to a target environment target-env can be renamed to name.targetable.target-env.extension and checked into the repository.

Consider the scenario where the Struts configuration for the Stores module is different between the development environment (identified as dev) and the production environment (identified as prod). For example, the development environment might have some configuration settings that are not ready to be deployed to the production environment. To ensure that the right version of the file is deployed to each environment, the files can be renamed and checked into the repository as follows:

• workspace/Stores/WebContent/WEB-INF/struts-config-ext.targetable.dev.xml
• workspace/Stores/WebContent/WEB-INF/struts-config-ext.targetable.prod.xml

During the deployment process, a deployment target value is provided when the deployment process is run. If this value is dev (that is, deploy to the development environment), the struts-config-ext.targetable.dev.xml file will be renamed to the original name struts-config-ext.xml and deployed to the system. Such feature is especially useful for files that differ between target environments, such as wc-server.xml and files that contain environment-specific paths, URLs and port numbers. It also provides developers access to files for all target environments in the development environment, making it easy to change and manage. It is imperative that developers are aware of, and leverage these features to support a multiple deployment target environment to avoid additional build and maintenance effort.

Extracting source code by incremental update

The Build and Deployment 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 WCBD_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 will have 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 have been updated to support incremental update.

When using 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 is to ensure that incremental updates to the source directory can be done accurately.

Excluding static Web assets in Web modules from the deployment packages

The Build and Deployment tool provides a way to exclude static Web assets in Web modules from the deployment packages. This is useful for reducing the overhead 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 will detect the existence of these files and use them to exclude static Web contents from Web modules as appropriate. One implication of using this feature is that the deployment package may not be able to set up a completely new environment since not all assets are included. You must ensure that the users of the deployment packages are aware of this limitation.

Madisons/images/**

Excluding EAR assets from the deployment packages

The Build and Deployment tool provides a way to exclude EAR assets from the deployment packages. This is useful for excluding out-of-the-box EAR assets that are not changed by your customization, and Java EE modules with bindings specific to the development environment that will cause configuration and application startup issues if they were deployed to another target environment. Follow the steps below 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 will detect the existence of these files and use them to exclude EAR assets as appropriate. One implication of using this feature is that the deployment package may not be able to set up a completely new environment since not all assets are included. You must 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, you can create an exclusion file workspace/WC/ear-dir-excludes.txt in the repository with the following contents:

*.jar

Stand-alone properties file encoding utility

For convenience, a stand-alone properties file encoding utility has been added to the Build and Deployment tool. After the setenv script is configured when you configure the build settings, follow the steps below to use the utility:

1. Change directory to WCBD_installdir.
2. Run the following command, where file is the properties file to be encoded:
   • wcbd-encode-properties.bat -Dfile=file
   • wcbd-encode-properties -Dfile=file

Support for multiple build types

The Build and Deployment tool provides support for multiple build configurations based on build type. To use this feature, follow the steps below to configure and run the build process:

1. When you configure the build settings, instead of creating WCBD_installdir/build.properties and WCBD_installdir/build.private.properties, create the files as WCBD_installdir/build-build-type.properties and WCBD_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 calling the wcbd-ant.bat or wcbd-ant command:

   -Dbuild.type=build-type

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

Centralized server deployment

To facilitate the centralization of the build and server deployment processes, the Build and Deployment tool provides a way to run the server deployment process on multiple target environments after the server deployment package is created in the build process. Follow the steps below to use this feature:

1. Place all server deployment customization assets, if any, into the WCBD_installdir/deploy/server directory.
2. Pre-configure the server deployment settings to facilitate remote server deployment from the build system and place all files into the WCBD_installdir/deploy/server directory. These files may include:
   • The static Web assets deployment Ant script and properties files, if any.
   • The WebSphere Commerce configuration file synchronization Ant script and properties files, if any.
   • The Data Load utility customization deployment Ant script and properties files, if any.
   • The setenv script and the deployment properties files for all target environment to be updated by the centralized deployment.
3. Open WCBD_installdir/build.properties with a text editor and set the properties under the "Properties for centralized server deployment" section accordingly. Refer to the comments in the file for details.

To extend support for this feature, the server deployment process can now be run, in a remote deployment scenario, with a Websphere Commerce Developer installation.

E-mail notifications of build status

The build process can be configured to send e-mail notifications upon success and/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 WCBD_installdir/build.properties with a text editor and set the properties under the "Properties for e-mail notification" section accordingly. Refer to the comments in the file for details.
2. If the SMTP server requires authentication, open WCBD_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 are useful for problem determination. To enable verbose mode, provide either the -v or -verbose option when calling 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 calling the wcbd-ant.bat or wcbd-ant command to run the build process.

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

[Wed, 21 Jul 2010 10:56:54 -0400] wcbd-build > extract

extract:
[echoNL] Extracting source code with C:\IBM\WCDE_ENT70\wcbd/extract-local.xml.
[delete] Deleting directory C:\IBM\WCDE_ENT70\wcbd\source\empty
[mkdir] Created dir: C:\IBM\WCDE_ENT70\wcbd\source\empty
[Wed, 21 Jul 2010 10:56:54 -0400] extract-local > all

all:
[delete] Deleting directory C:\IBM\WCDE_ENT70\wcbd\source\empty
[mkdir] Created dir: C:\IBM\WCDE_ENT70\wcbd\source\empty
[copy] Copying 448 files to C:\IBM\WCDE_ENT70\wcbd\source\empty
[copy] Copied 191 empty directories to 5 empty directories under C:\IBM\WCDE_ENT70\wcbd\source\empty
[Wed, 21 Jul 2010 10:56:55 -0400] extract-local < all (1 second)
[Wed, 21 Jul 2010 10:56:55 -0400] wcbd-build < extract (1 second) 

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

-logger com.ibm.commerce.wcbd.ant.logger.PerformanceLogger

> log-file 2>&1

Debug options for EJBDeploy

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