HOME > Community > Projects > nbbuild

Ant: The Gory Details

Authors: Jesse Glick, Rudolf Balada
Version: September 30, 2002

The Ant build system for NetBeans is broken up for modularity into several independent build scripts working together. These will be described in turn.

It is assumed that the builder has checked out a copy of the IDE sources, to include pseudomodules nbbuild, core, openide, and openidex, as well as all desired IDE modules, and that these are located on disk in the repository structure.

The physical organization is that wherever reasonable, files are built close to their source. For example, Java sources are compiled to class files next to the sources. JARs and other build products of a module are placed in a build area underneath the module's source tree. Global build products, such as the IDE itself, are placed underneath the nbbuild pseudomodule's source tree.

Most build targets are incremental: after completing the target once, you can make minor changes to the IDE sources and rerun the target; only necessary steps to bring everything up-to-date will be taken. This makes the system suited for development-time as well as production-time use.

If you are not yet familiar with the basics of how Ant works, please see its home page for documentation and explanation.

The Master Script

Again in nbbuild lives the master script, build.xml, which is used to drive a build of the entire IDE. It's parametrized by file build.properties and user.build.properties, where you can put all properties and values you might want to set. The build.xml has three main functions: run sub-builds for all modules (and pseudomodules) that will be included in the IDE; merge the results of these sub-builds into a single IDE installation area, and run the first-start function to create a workable IDE; and drive the creation of NBMs and update descriptions for modules. Its interesting overridable properties and targets will be discussed.

`buildnumber` Property

You can specify a build number. This is purely informational and can be any string. It will appear in the "implementation version" of the IDE, be displayed in the splash and about screens, the title of the Main Window, and also be the default implementation version for modules (which shows up in the log and can help identify which build a module came from, or whether it was updated).

`firststart.args` and `tryme.args` Properties

These properties give IDE options to be passed to it during the first-start procedure, and test runs, respectively. You should probably not try to change firststart.args, but tryme.args can be set if you customarily run the IDE with special startup arguments (locale, font size, etc.).

`nogui` Property

If you set this property there will be passed arguments -nogui and -nosplash to IDE during first start. That invokes IDE without graphics output.

`javahome` Property

Set to the location of your JDK (or JRE), if different from the version of Java used to run Ant itself.

`netbeans.japanese` Property

May be set to true to include Japanese-locale resources in the build.

`bootstrap` Target

This target simply compiles the NetBeans-specific Ant extensions (custom tasks) needed for some parts of the build, and forms a nbantext.jar file which other targets and scripts request to have in their classpath when declaring custom tasks. Note that almost all other targets make sure the bootstrap JAR has been built before even beginning.

There is also a bootstrap-javadoc target to build Javadoc documentation for these extension tasks.

`build` and `build-nozip` Targets

Build NetBeans. The former creates a complete ZIP file suitable for distribution, while the latter just leaves the file on disk in nbbuild/netbeans/ (for example, for use with the tryme target).

These targets essentially build all modules and then NbMerge the results together in the nbbuild/netbeans/ directory.

See instructions for running the resulting build.

`all-`modulename Targets

Targets beginning with the prefix all- are used to drive the subbuild for the module named in the suffix. Such targets should specify whatever dependencies on other subbuilds are needed (generally for classpath inclusions).

`sanity-check` Target

After running build (or build-nozip) you can run this target to sanity-check NetBeans. It will try to start it (using nbbuild/testuserdir as the test user directory) and immediately shut down. If there are major problems in the build, they will often be visible in stack traces and so on during this process. (These are printed to console in dev builds; for release branches, see nbbuild/testuserdir/system/ide.log instead.) If the sources are in good shape, there should be no exceptions (stack traces) printed. A couple of warning or accidentally unremoved debugging messages are not cause for concern, though.

`tryme` Target

This target just runs the IDE normally, building it first if it has not been. Thus you may easily try it out and confirm that it works.

`build-nbms` Target

Builds NBM files for various modules in subbuilds, and also creates an update description XML file which can be served via HTTP to the IDE's Update Center, permitting new versions of modules to be installed by users. You have to run at least merge target before this one.

`build-javadoc` Target

Builds javadoc for various modules (see config.modules.javadoc and config.fixedmodules.javadoc properties in build.properties).

`clean` Target

Cleans almost all build products from the whole source tree.

`real-clean` Target

Additionally cleans existing builds and log files; and finally the Ant extensions. Take care on Windows 2000 and newer Microsoft Windows OSes when using Ant >= 1.4.x, because the system locks the file nbantext.jar (the Ant extensions) and it's impossible to remove locked file, so the clean target may fail or not work properly and the file is kept there. Actualy it's set to ignore the error when removing the file and fully trust it will be rebuild in next round, but it's not a good idea.