MAST - Mighty Automated Build - Configuring and Building

This section assumes that you have already done everything in the previous section.

Now that you have the MAB stub script in prod_dir and your product sources arranged properly, you're ready to configure MAB and build your product.

Step 1: Choose a short name for your product.

This is a one-word, all-lowercase designation for your product that will be the name of its .zip file and top-level directory. We will call our hypothetical product myproduct for the purposes of this discussion.

Step 2: Create a properties file.

This is an ordinary text file in prod_dir. Create a new text file in this directory called (product_short_name)-build.properties. The file must have this exact name. In our case, the name of the file will be myproduct-build.properties. Open this file in your favorite text editor. This file is a standard Java properties format file, the format of which is described here. Be sure to familiarize yourself with this format before continuing. (Highlights: # and ! indicate comments when placed at the start of a line, properties are name-value pairs, multi-line property values should escape the line-end with a backslash (\), and if you want to actually include a backslash, you should put a double-backslash in there (\\)).

Step 3: Write the project.longname property.

Choose a full name for your project; this is the proper name for the product you're building. In this case, we'll choose My Sample Java Product. We write that in the properties file as:

project.longname= My Sample Java Product

Step 4: Write the project.toplevelpackages property.

Here, we indicate the names of the top-level packages that will be included in the build. These should be the names of subdirectories of prod_dir. In the case of our previously specified sample directory structure:

prod_dir/
 |
 +-package1/
 | |
 | +-subpackage2/
 | | |
 | | +-SomeClass.java
 | |
 | +-SomeOtherClass.java
 |
 +-package2/ 
   |
   +-SomeThirdClass.java

project.toplevelpackages=package1:package2

Step 5: Write the output.directory property.

This step is optional, but recommended. If you do not write an output.directory property, then MAB will output to the current directory (.). This is not very desirable. The output directory is the directory where you want the built files and such to go. Specify this in whatever platform-specific way is required to specify a pathname. On UNIX, we might specify it as:

output.directory=/home/edashofy/builds/

On Windows, it will be something like this (remember, double-backslashes!):

output.directory=C:\\Builds\\

Step 6: Write a project.description property.

This step is optional, but recommended. The project.description property has a longer description of your product that goes in the build properties file that will be included in your program. This is used by the Mighty Automated Deployment system. This description should be a few sentences, at most. Example:

project.description = This is a really cool Java \
                      project that you should download \
                      and use.

Step 7: Write a mab.javadoc.params property.

This step is optional. The mab.javadoc.params property specifies additional command-line properties to be passed to the javadoc tool to affect its output. All code compiled by MAB is also Javadoc'ed automatically. Example:

mab.javadoc.params=-author \
                   -footer "(C)2003 My Corporation.  All Rights Reserved ." \
                   -package \
                   -link http://java.sun.com/j2se/1.4/docs/api/

Step 8: Write a mab.jar.manifest property.

This step is optional. If you want to include a manifest file in the .jar file that will be built, then you can specify its name here. It should be placed in prod_dir. Let's say it's called manifest.txt (it will get renamed to manifest.mf by the JAR tool later), the property would be:

mab.jar.manifest=manifest.txt

Step 9: Write a mab.mixlibs property.

This step is optional. If your software requires third-party libraries that ship as .jar or .zip files, it can be awfully inconvenient to require that your users manually add these to the classpath in order to run your program, or include references to these .jar files in your manifest only to have the program break when people unzip it or don't run it in a particular way.

The mab.mixlibs property lets you specify a directory containing .jar or .zip files that will not only be automatically added to the classpath when building, but will also be "mixed in" to YOUR .jar file when your .jar file is being created. Thus, the contents of the archives in the directory specified by mab.mixlibs will be included in your archive along with your own software.

An example of this property if your directory were called mixlibs/ would be:

mab.mixlibs=mixlibs

Step 10: Write a mab.mixin property.

This is a bit harder to explain. Recall from the previous section that the default output of MAB is a file structure that looks like this:

build_dir/
 |
 +-myproduct.zip 
 | (contains contents of myproduct directory,
 |  below)
 |
 +-myproduct/
   |
   +-doc/
   |  |
   |  +-(contains javadoc documentation)
   |
   +-lib/
   |  |
   |  +-myproduct.jar
   |    (contains .class files and resources)
   |
   +-src/
     |
     +-(contains source files)

We want to be able to include additional static files in the build and also perhaps some new directories. Let's assume we have written a shellscript called runmyproduct.sh that we want to include in a bin/ directory, and a LICENSE.TXT file that we want to include in the myproduct directory. We can accomplish this by creating a directory as a subdirectory of prod_dir and putting this structure there to be "mixed in" to the build. Let's call this directory mixin. So, we would create:

prod_dir/
 |
 +-(other contents omitted for space)
 |
 +-mixin/
   |
   +-LICENSE.TXT
   |
   +-bin/
     |
     +-runmyproduct.sh

We then specify the name of the mixin directory in the mab.mixin property in the properties file, as such:

mab.mixin=mixin

Step 11: Write mab.task.prejar, mab.task.postjar, and mab.task.postbuild properties.

This step is optional, and most users will not need these properties. These properties allow you to specify the names of additional auxiliary Ant files with default tasks to run at different points in the build process, namely right before the class files are JARed, right after the class files are JARed, and after the build is complete. This is useful for integrating specialized tasks into the build process. For instance, you might create a file called signjar.xml in prod_dir that looks like this:

<?xml version="1.0"?>

<project name="signjar" default="signit" basedir=".">

  <target name="signit">
    <signjar jar="${outroot}/lib/${project.name}.jar"
             storepass="seekrit"
             alias="keyalias"/>
  </target>

</project>

This task digitally signs the JAR file and is run after the JAR file has been created. So, the mab.task.postjar property in this case would be:

mab.task.postjar=signjar.xml

Step 12: Save and check your properties file.

This exhausts the currently supported properties in MAB. Additional properties may become available as MAB evolves and will be documented here. An example properties file for our hypothetical product might look like:

# Build properties for MyProduct

project.longname= My Sample Java Product

project.toplevelpackages=package1:package2

project.description = This is a really cool Java \
                      project that you should download \
                      and use.

output.directory=/home/edashofy/builds/

mab.jar.manifest=manifest.txt

mab.javadoc.params=-author \
                   -footer "(C)2003 My Corporation.  All Rights Reserved ." \
                   -package \
                   -link http://java.sun.com/j2se/1.4/docs/api/

mab.task.postjar=signjar.xml

This completes the configuration of MAB. Now you can run it to build your product.

Step 13: Run MAB and build.

Since MAB is just an Ant script, running MAB really means running Ant. Make sure that the bin/ directory of Apache Ant is on your PATH and ensure that your CLASSPATH is set properly for the build. Also make sure to set the environment variable JAVA_HOME to the directory where you installed your J2SDK.

If you have everything set up, open a command prompt and change directory to prod_dir. From there, you have to execute Ant with one additional command-line property: the short name of your project that you chose back in Step 1. Recall that we chose myproduct. Run Ant as follows:

ant -Dproject.name=product_short_name

So, for our hypothetical product, we would run:

ant -Dproject.name=myproduct

Note that you must be connected to the Internet for this to work, because the MAB stub script does not actually do the building. Rather, it retrieves the actual MAB build script from this website using an HTTP GET request and then passes control to that script. This ensures that you always have the latest MAB build script, even if we add features or fix bugs in the script, without you specifically having to download it or have us notify you when the script changes.

The build process should begin. Errors, warnings, etc. will be output to standard output. If the build is successful, the built software should appear in build_dir.

That's all there is to MAB. If you have questions or comments about MAB, please email Eric Dashofy.