This section explains the basics on building standard and free-form projects in the IDE, and how you can customize the build process by modifying the Ant build script the IDE uses when building your project.

In this section you will learn about the following:

• Using Ant Build Scripts
• Building Projects, Packages, and Files
• Fixing Compilation Errors
• Filtering Output Files
• Customizing the Build Process
• Build Files in Standard Projects
• Build Files in Free-form Projects
• Writing Custom Ant Tasks
• Mapping Custom Ant Targets to Project Commands

Using Ant Build Scripts

Ant build scripts are XML files that contain targets, which in turn contain tasks. Ant tasks are executable bits of code that handle the processing instructions for your source code. For example, you use the javac task to compile code, the java task to execute a class, and so forth. You can use Ant's built-in tasks, use tasks written by third parties, or write your own Ant tasks. You do not need to know Ant to work with the IDE. If you are looking for resources on learning Ant, see http://ant.apache.org/resources.html .

You use Ant build scripts to build your project in the following ways:

• Standard projects. In standard projects the IDE generates the build script based on the options you enter in the New Project wizard and the project's Project Properties dialog box. You can set all the basic compilation and runtime options in the project's Project Properties dialog box and the IDE automatically updates your project's Ant script. If you know how to work with Ant, you can customize a standard project's Ant script or write your own Ant script for your project.
• Free-form projects. In free-form projects, the IDE relies on your existing Ant script to provide targets for IDE actions, such as building, running, and debugging.

Building Projects, Packages, and Files

Compilation in the IDE is simple. Once you have ensured that your project's compilation classpath is set correctly., you need only select the project, package, or file you want to compile and choose the appropriate Build or Compile command. The IDE then compiles the files.

To compile a project, package, or file in the IDE, select it in the Projects window and do one of the following:

• In the main menu, choose Build > Build Main Project (F11) to build the main project. Alternately, you can click the Build button in the toolbar.
• In the main menu, choose Build > Clean and Build Main Project (Shift-F11) to clean and build the main project. Alternately, you can click the Clean & Build button in the toolbar.
• In the Projects window, right-click the project node and choose Build Project to build the project.
• In the Projects window, right-click the project and choose Clean Project to clean the project.
• In the Projects window, right-click the package and choose Compile Package (F9) to compile a package.
• In the Projects window, right-click the file and choose Compile File (F9) to compile a file. Alternatively, choose Build > Compile File (F9). Note that if you are using a free-form project, this command is disabled by default. You have to write an Ant target for compiling the currently selected file in the IDE and map it to the Compile File command.

Whenever you invoke compile commands, the IDE displays the output including any compilation errors encountered in the Output window, as described in the following section.

If you expand a standard project's project directory node in the Files window, you will notice that the IDE compiles classes to the build folder. In addition, the IDE builds a JAR file for Java projects from your project sources automatically. The JAR file is generated to the dist directory of your project folder. In free-form projects, your Ant script controls output file creation.

Fixing Compilation Errors

The IDE displays output messages and any compilation errors in the Output Window. This multi-tabbed window is displayed automatically whenever you generate compilation errors, debug your program, generate Javadoc documentation, and so on. You can also open this window manually by choosing Window > Output (Ctrl-4).

One important function of the Output window is to notify you of errors found while compiling your program. The error message is displayed in blue underlined text and is linked to the line in the source code that caused the error, as illustrated in the image below. The Output window also provides links to errors found when running Ant build scripts. Whenever you click an error link in the Output window, the Source Editor jumps to the line containing the error automatically. You can also use the F12 and Shift-F12 keyboard shortcuts to move to the next and previous error in the file.

Output window showing compilation errors

Every action that is run by an Ant script, such as compiling, running, and debugging files, sends its output to the same Output window tab. If you need to save the messages displayed in the Output window, you can copy and paste it to a separate file. You can also set Ant to print the command output for each new target to a new Output window tab by choosing Tools > Options, clicking the Ant node in the Miscellaneous category, and deselecting the checkbox for the Reuse Output Tabs from Finished Processes property.

Filtering Output Files

When you create a JAR file or a WAR file, you usually want to include just the compiled .class files and any other resource files located in your source directory, such as resource bundles or XML documents. The default filter does this for you by excluding all .java , .nbattrs , and .form files from your output file.

You can create additional filters using regular expressions to control the Output files. To specify which files to exclude, right-click your project in the Projects window and choose Properties to open the Project Properties dialog box. In the left pane, click on Packaging. In the right pane, enter regular expressions in the text box to specify the files to exclude when packaging the JAR or WAR files. In addition to the default expressions, here are some additional regular expressions you can use:

Regular Expression	Description
\.html$	Exclude all HTML files
\.java$	Exclude all Java files
(\.html$)|(\.java$)	Exclude all HTML and Java files
(Key)|(\.gif$)	Exclude all GIF files and any files with Key in their name

For a guide to regular expression syntax, see jakarta.apache.org .

Customizing the Build Process

By customizing your Ant script you can customize how your project is built. For example, you can write an Ant target that compiles the currently selected file and then map the target to the IDE's Run File command.

In standard projects , Ant scripts are stored in your project folder. The main Ant script for a standard project is build.xml . The IDE calls targets in build.xml whenever you run IDE commands. This file contains a single import statement that imports targets from build-impl.xml . In build.xml , you can override any of the targets from build-impl.xml or write new targets.

In free-form projects , the IDE uses targets in an existing Ant script to build, run, clean, test, and debug your application. If the Ant script does not contain targets for some of these functions, the functions are unavailable. To implement these functions you write targets either in your Ant script or in a secondary Ant script. You can then map commands in the IDE to these targets.

 

Build Files in Standard Projects

In standard projects, build-impl.xml is the Ant script that contains all of the instructions for building, running, and debugging the project. You should never edit this file. You can, however, open it to examine the Ant targets that are available to be overridden, and then modify build.xml to override any of the targets, or write new targets.

With standard projects, you can customize the build process by doing any of the following:

• Entering basic options, like classpath settings and JAR filters, in the New Project wizard when you create a project, or afterwards in the Project Properties dialog box.
• Editing properties in nbproject/project.properties . This file stores Ant properties with important information about your project, such as the location of your source and output folders. You can override the properties in this file. Be careful when editing this file. For example, the output folder is deleted every time you clean your project. You should therefore never set the output folder to the same location as your source folder without first configuring the clean target to not delete the output folder.
• Customizing existing or creating new Ant targets by doing any of the following:
• Add instructions to be processed before or after an Ant target is run. Each of the main targets in build-impl.xml also has a -pre and -post target that you can override in build.xml . For example, to get RMI working with regular projects, type the following in build.xml :

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

• Change the instructions in an Ant target. Copy the target from build-impl.xml to build.xml and make any changes to the target.
• Create new targets in build.xml . You can also add the new target to the dependencies of any of the IDE's existing targets. Override the existing target in build.xml then add the new target to the existing target's depends property. For example, the following adds the new-target target to the run target's dependencies:

<target name="new-target">
    <!-- target body... -->
</new-target>
 
<target name="run" depends="new-target,myprojname-impl.run"/>

Notice that you do not need to copy the body of the run target into build.xml .

The following table lists some common tasks for redefining a JAR file that you may find useful:

To perform this task	Follow these steps
Specify which files are added to a JAR file.	Right-click the project node in the Projects window and choose Properties. Click the Packaging subnode (under Build) and configure the filter and compression settings using the Exclude from JAR File field. For more, see Filtering Output Files
Change a JAR file's name and location.	In the Files window, go to the nbproject folder in your project folder and open project.properties in the Source Editor. Enter the full path to the JAR file in the dist.jar property.
Specify the manifest file for a JAR file.	In project.properties , type the name of the manifest file in the manifest.file property. The file name must be specified relative to the project's build.xml file. Note that if you are using the Java Application template, the IDE creates a manifest file for you.
Disable the generation of a JAR file for a project.	In the Files window, open your project folder and open build.xml . Override the jar target to have no contents and no dependencies. For example, add the following to build.xml : <target name="jar" />

Build Files in Free-form Projects

In free-form projects, the IDE uses targets in an existing Ant script to build, run, clean, test, and debug your application. If the Ant script does not contain targets for some of these functions, the functions are unavailable. To implement these functions you write targets either in your Ant script or in a secondary Ant script. You can then map commands in the IDE to these targets.

If you want to run an IDE command and you do not have a target for that command, the IDE can generate the target for you. When the IDE generates the target, the target is generated in a separate build script and automatically mapped to the command.

For examples of writing Ant targets in free-form projects, see the following article:

• Advanced Free-form Project Configuration

Writing Custom Ant Tasks

You can use custom Ant tasks to expand on the functionality provided by Ant's built-in tasks. Custom tasks are often used to define properties, create nested elements, or write text directly between tags using the addText method.

To create a custom Ant task in the IDE, press Ctrl-N and select the Custom Task template from the Ant Build Scripts folder. When you create the custom Ant task file, the template opens in the Source Editor. The template contains sample code for many of the common operations performed by Ant tasks. After each section of code, the template also shows you how to use the task in an Ant script.

Mapping Custom Ant Targets to Project Commands

In free-form projects, you map IDE commands to targets in your Ant script. By doing so, you can, for example, add an item for a Debug Project target to the project's contextual menu.

Click Build and Run in the left panel of the Project Properties dialog box.

Run targets in the Project Properties dialog box

For each command, choose an Ant target from the drop-down. The drop-down contains each of the targets in your Ant script. However, if your Ant script uses an <import> statement to import targets from another Ant script, the targets do not show up in the drop-down list in the Project Properties dialog box. To map commands to these targets, type the names of the targets into the list.

You map other commands, like those that run on individual files, by editing the project.xml file manually. For details, see Advanced Free-form Project Configuration .