Building Applications

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

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:

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:

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:

<target name="-post-compile">
  <rmic base="${build.classes.dir}" includes="**/Remote*.class"/>
</target>
<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:

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 .


Previous - TOC - Next


Copyright and Trademark Notice