Customizing the IDE-Generated Build Script

The build scripts the IDE generates for you in standard projects are based on common scenarios that work for many development situations. But if the script does not do what you want it to do, you can add to, override parts of, or change the script entirely.

When you create a standard project, the IDE generates two build scripts: build-impl.xml and build.xml.

The build-impl.xml file is generated based on the type of project template you started with and is regenerated based on any changes that occur in the project's associated project.xml file. Do not edit build-impl.xml directly, because any changes you make there will be lost any time the file is regenerated.

The build.xml file serves as the master build script. By default, it has no targets of its own. It imports build-impl.xml. You can freely edit build.xml.

To help make sense of the Ant script, you can use the Ant Debugger to step through execution of the script so you can quickly see the order in which the various targets are called. See Debugging Ant Scripts in Chapter 16 for more information.

Adding a Target

To add a target to the build script of a standard project:

1. In the Files window, expand the project's main folder.

2. Double-click the build.xml file to open it in the Source Editor.

3. Below the import element, type any targets you would like to add to the build script.

Adding a Subtarget

To make customization of build scripts easier, the generated build scripts include several empty targets that are called from main targets.

For example, the compile target depends on pre-compile and post-compile targets, which have nothing in them. If you need to add any steps to the build process just before or after compilation of your files, you can customize these targets without having to add to the depends attribute of the compile target.

To add to a target using one of the existing empty subtargets:

1. In the Files window, expand the project's nbproject folder and open the build-impl.xml file.

2. Copy the empty target you want to use, paste it into the project's build.xml file, and then make your modifications to it there.

For example, you could call Ant's rmic task in the post-compile target to run the rmic compiler on all classes with names beginning with Remote (as shown in the snippet below):

<target name="-post-compile">     <rmic base="${build.classes.dir}" includes="**/Remote*.class"/> </target>

For further convenience, some of the main targets also include "-pre-pre" targets that handle some basic steps before the empty targets are called. For example, the -pre-pre-compile target, which creates the directory to hold the class files to be compiled, is called before the -pre-compile target.

Overriding an Existing Target

If adding subtargets to a main target is not sufficient for what you need to accomplish, you can completely override part of a build script.

To override a target in a standard project's build script:

1. In the Files window, expand the projects nbproject folder and open the build-impl.xml file.

2. Copy the target you want to override, paste it into the project's build.xml file, and then make your modifications to it there.

When a target appears in both the build-impl.xml and build.xml files, the version in the build.xml file takes precedence.

If you are merely modifying the depends attribute of the target, you do not have to copy the whole body of the target. You can copy just the target element without its subelements. The subelements will be imported from the build-impl.xml file.

Inside the Generated Build Scripts

Here is a look at all of the pieces of the project metadata and how they work together.

When you create a standard project, the IDE creates the files listed in Table 3-4.

Table 3-4. Metadata Files for a Standard Project

File	Description
build.xml	This script is the master build script for the project. When you call a project-related command from the IDE, the IDE calls a target in this file. You can freely edit this file if you want to make customizations to your build process. This file is generated when you create the project but is not regenerated afterward. Any configuration you do in the IDE that is relevant to the build script is reflected in the build-impl.xml file, which is imported by build.xml. If a target with the same name appears in both build.xml and build-impl.xml, the target in build.xml takes precedence.
nbproject/build-impl.xml	Included in standard projects (but not free-form projects), this file contains the meat of the build script and is imported by build.xml. It is generated based on the type of project and the contents of that project's project.xml file. Do not edit this file.
nbproject/project.properties	Included in standard projects (but not free-form projects), this file contains values that the build script uses when building your project. These values include things such as the name and location of the directory for your compiled files and references to properties set elsewhere in the project. Changes you make in your Project Properties dialog box are propagated here. You can also modify this file directly in the Source Editor.
nbproject/project.xml	Provides the basic metadata that determines how the project works in the IDE. For standard projects, this file determines how build-impl.xml and project.properties are generated. For free-form projects, this file serves as the glue between your build script and the IDE's user interface. This file is generally editable, but you are likely to need to edit it only for freeform projects.
nbproject/genfiles.xml	Used by the IDE to help keep track of the state of the build script (such as whether the build-impl.xml file needs to be regenerated). Do not edit this file.
nbproject/private/private.properties	Holds properties that are specific to your installation of the IDE. These properties are not to be versioned, but they can be used by headless builds run on your machine.

There is also a build.properties file that is created in your IDE's user directory. This file holds properties for the location of libraries that are packaged with the IDE, any libraries you specify with the IDE's Library Manager, and any versions of the Java platform you register with the IDE's Java Platform Manager. The private.properties file references the build.properties file with its user.properties.file property.