Build Process (Work in Progress -- See 1.0 Build below for current build process)
For any type of build, you must do the initial configuration step below.
There are 3 styles of builds, the full build as done on the build server, a component build and a module build.
Configuration
- Install ANT 1.7.1
- Extract trunk (or whatever branch)
- Go to the zero.build module (BUILD/zero.build)
- Copy zero.properties.template to zero.properties
- Obtain the prereqs
- ant -f zbuild.xml setup
- Download jdks and eclipse from aeneis.raleigh.ibm.com, the versions can be found in build.properties
The default locations are listed below but can be adjusted in your zero.properties
- Eclipse should be unzipped in your {prereqs directory}/eclipse/3.3.2
- The JDK should be unzipped in your {prereqs directory}/jdks/{jdk version}
For Mac, please read the comment in build.mac.properties
- You need Visual Studio on Windows or gcc on Linux to do the native builds
- Set the JAVA_HOME variable to your installed JDK path so that the native builds can pick up the JNI header files
Optional steps for Component and Module builds
- Build the build tools
- Go to the BUILD/zero.build directory
- ant
- Many of the partial build targets need a CLI built; this is not required for a full build but is for DOC
- Go to the CORE/zero.core.build directory
- ant cli-build
Comment (JDO): Is Emma optional (ie just wanting to do a doc build)?
Emma is not needed for a doc build.
Optional prerequisites
To perform the additional documentation checks, xhtml validation and link checking, you need to install 2 additional tools.
- Offline HTMLHelp.com Validator (validate v1.2.2)
- w3c Link Checker (checklink v4.4)
To build the App Builder with Javascript compression, you will need a full source build of Dojo (version 1.1.1) with Shrinksafe compression. (See below)
Validate v1.2.2
The tool and instructions to install can be found
here.
Once installed, place a copy of the
validate script into BUILD/zero.build/prereqs/validate-1.2.2
checklink v4.4
The tool and instructions to install can be found
here.
You will need to download the latest version of checklink from their
CVS tree.
Once installed, place a copy of the
checklink script into BUILD/zero.build/prereqs/checklink-4.4
Dojo v1.1.1 source build with Shrinksafe compression
The compressed build requires dojo-release-1.1.1-src.zip from
here
If you are doing a full build, copy the zip above into a directory of your choice and reference it using -Ddojo.src.zip=<fully-qualified zip file> when you execute the ant build command. The build will unzip the zip into your ${zero.build}/prereqs directory.
If you are doing a component build of the App Builder, you can download and unzip the appropriate Dojo code automatically by building the "setup" target before executing the component build. The setup target will download the zip and unzip it into your ${zero.build}/prereqs directory.
A Local Build
To run a build
- Go to the BUILD/zero.build directory
- ant -f zbuild.xml BUILD
- ant -f zbuild.xml TEST
Note: The build output is stored at BUILD/zero.build/export
Note: The Command Line (cli) is installed at BUILD/zero.build/export
To clean a build
- ant -f zbuild.xml CLEAN
To run a doc build
- Ensure you have a CLI built
- ant cli-build from CORE/zero.core.build directory
- ant -f zbuild.xml DOC from BUILD/zero.build directory
- You can skip javadoc by adding a -Dskip.javadoc=true
- Results from the doc build are not aggregated but are in each module's export directory
- Developer's Guide: CORE/zero.devguide.doc/export/docs
- Getting Started: DEVTOOLS/zero.gettingstarted.doc/export
To run all tests
- Ensure you run a full BUILD
- ant -f zbuild.xml TEST from BUILD/zero.build directory
- The BVT tests will run now with a TEST build. You can skip BVT by adding a -Dskip.BVT=true
- Results from the TEST build are all aggregated in zero.build/export/tests
To run BVT tests
- Ensure you run a full BUILD
- ant -f zbuild.xml BVT from BUILD/zero.build directory
- The BVT tests' output is redirected to a file, so the build process will be quiet while BVT is running
- The stdout/stderr of the BVT is written to /zero.build/export/tests/bvt/bvt.log
Note: To exclude BVT modules, you can edit your zero.properties and modify the skip.bvt.modules item. The default is to skip the installer tests.
Note: To configure which tests are run, edit the following line from BVT/zero.bvt.build/build.xml. By default, the "includes" attribute will run all test projects found under the BVT tree which end in "bvt". For example, to run just the AppBuilder tests, the value should be "zero.ide.bvt/build.xml".
<fileset dir=".." includes="*bvt/build.xml" excludes="zero.bvt.build/build.xml,zero.php.bvt/build.xml" />
Component build e.g. CORE/zero.core.build
To build a component, follow the configuration steps above.
You either have a command line that you have downloaded or you have a command line that you have built.
To perform any of the build commands, issue
- ant build
- ant publish
- ant test
- ant clean
- ant doc
- ant javadoc
Note: To specify the cli location, use -Dzerohome=<path to cli>
Build a module
A module build is similar to a component build except you must specify where zero.build is located.
ant -Dzero.build={zero.build} {command}
Building the command line
- From CORE/zero.core.build
- ant cli-build
Note: You can change the install location by adding a -Dzerohome={zerohome dir}
Common errors
Using the wrong repository
You can dictate the repository to use by adding a
-Drepository={path to repository} to the command line.
A repository that does not exist
- If you were using a downloaded Command Line, it will rebuild the repository for you as needed.
- If you were using a built Command Line, you will need to re-install the CLI or hand build the repository.
- To re-install the CLI, just go to CORE/zero.core.build, and type ant install-cli.
- To build the repository by hand, see the build target in BUILD/zero.build/ant/component.xml.
Tasks
- build
- publish
- test
- doc
- clean
Building Native Code
If you do not have a supported compiler installed on your machine, then the native components of Zero will not build. This will not fail the build or the test run, but some tests within the full tree will fail. The failures should be confined to the zero.management.tests suite.
To install a valid compiler, do the following depending on platform:
- Linux -- install GCC and supporting tools. All free.
- Mac -- install Xcode tools from Max OS X CD.
- Windows -- A default install of Visual Studio 2005 will be automatically picked up and used for native compiles. This is the easiest option. If you do not have license for Visual Studio 2005, you can use the free compiler included with Visual C++ Express 2005. Do the following:
- Install the free Microsoft Visual C++ Express 2005. The link is down on the download page -- You must get the 2005 version. Install into the default location.
- Install the Microsoft Platform SDK. These directions for installing the Microsoft Platform SDK integrate Visual C++ Express and the Platform SDK. That is required for debugging, but for building, all you need is to install the SDK.
- Before running the "ant -f zbuild.xml BUILD" build command, run the setenv.bat file from the SDK. It will be in the top of the default install directory of the Platform SDK. (for example: C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\SetEnv.Cmd)
- Run the build as normal. The compiler from Visual C++ will be found automatically, and the required libraries will be found from the SDK via the environment setup by the setenv.cmd script.
NOTE: For ANT 1.7, jsch-0.1.29 or earlier must be used. ANT 1.7.1 can use later versions (
http://issues.apache.org/bugzilla/show_bug.cgi?id=41090)
Tenants of our build tools/scripts
- All generated artifacts should go into the ${export} directory.
- ANT 1.7 and JUnit 4.1 are provided by zero.tools. There should never be a need to create a dependency for either. The classpath for all compilation include the JARs from zero.tools.
Older Build Process
1.0 Build
M5 Build
M4 Build
