After installation, the IDE will configure a single default Internal Compilation Service. To configure the default Internal Compilation Service, select Tools → Options. In the Options window that appears, expand the nodes Building → Compiler Types. Select the Internal Compilation child node and you should see a Property Sheet appear in the right pane as shown in Figure 5-1.

The various configuration options for the Internal Configuration Service are described in Table 5-1; additionally, Figure 5-1 shows configurations for the service that are on the expert tab of the property sheet.

Figure 5-1. The Internal Compiler Service

Sometimes it is necessary to have different configurations of the same service for the sake of passing different compiler options to different files. For example, one Java source file may need to be compiled with debugging information whereas another, in the same project, does not. In this case you can create a new compiler service configuration. To create a new configuration, right-click on the Compiler Types node and select New → Internal Compilation from the context menu. Enter a name for the new compiler configuration and click the Finish button. Your new compiler should be added to the list of Compiler Types. Refer to Table 5-1 and Table 5-2 to configure your new Internal Compiler Service as desired. Now you can associate Java source files with either the default service or the one you just created.

External Compilation Services allow you to use compilers other than the default one used by the Internal Compiler Service. For example, you might want to compile some Java source files using the JDK 1.1, some using JDK 1.4, and others using JDK 1.3. Because the Internal Compiler Service only allows you to customize one compiler, it cannot be used to accomplish this task. If you installed the IDE under 1.3 (the IDE cannot be installed under 1.1), the Internal Compiler will use the 1.3 javac. For the 1.4 and 1.1 JDKs, you can create custom configurations of the External Compiler Service. The External Compiler has a property that lets you specify which executable will be used as the javac tool. Other properties let you configure parameters that need to be passed to the tool as arguments. As an example of creating and customizing your own service, this section will show how to create a new JDK 1.1 External Compilation Service and configure it to compile source code written for the JDK 1.1 compiler. This example assumes that you have the JDK 1.1 installed. You can download the JDK from http://java.sun.com/products/jdk/1.1.

Creating a new JDK 1.1 External Compilation Service

To create a new JDK 1.1 External Compilation Service, right-click on the Compiler Types node and select New → External Compilation. Enter a name for the new service and click the Finish button. For this example we will use the name JDK 1.1 External Compilation Service. The newly created service should appear in the list of compiler types.

Configuring the new JDK 1.1 External Compilation Service

Select the newly created service and a tabbed property sheet should appear in the right pane as shown in Figure 5-2. External Compilation Services are far more configurable than Internal Compilation Services. There are standard properties for arguments that are passed to the compiler when it is called by the IDE. These arguments are referred to as tags and can be configured in the property sheets. For example, the argument (or tag) for debug optimization is usually -g. However, if you are using a third-party compiler, this option may be something like -d or -optimized. Using the property sheets you can set the value of this argument (true or false) and you can also change the name of the tag from -g to whatever you want. Most of the options that are expected by compilers are represented in the property sheets; however, you may need to add extra parameters for the compiler you are using or to remove some of the parameters that are not used. The IDE gives you maximum control of the external compiler by letting you format the actual command used to invoke the compilation process. This step is detailed in the next section. Figure 5-2 and Table 5-3 show the properties of the External Compiler Service configuration and Table 5-4 shows the expert properties for these services.. To add environment variables, click the Expert tab on the property sheet for a compilation service, then click the value field for its Environment Variables property. A specialized property editor dialog will pop up, as shown in Figure 5-3.

Figure 5-2. JDK 1.1 External Compilation Service

Table 5-3. Configuration properties for the External Compilation Service

Property name	Description
Debug	When this property is set to true, the IDE will send the debug flag to the compiler, causing it to produce debugging information in the compiled code.
Deprecation	When this property is set to true, the IDE will send the deprecation flag to the compiler, causing it to treat deprecated methods as errors.
Enable JDK 1.4 source	When this property is set to true, the IDE will send the “-source 1.4” flag to the compiler, enabling it to recognize JDK 1.4 assertions.
Encoding	This property sets the character encoding for the source code.
Error Expression	This property sets the format of error message output from the compiler using regular expression. It allows the IDE to identify error messages from different compilers.
External Compiler	This property allows you to configure the external process that is used by the IDE as the compiler executable. This property will be discussed in the next section.
Identifying Name	This property sets the canonical name for the External Compiler Service.
Optimize	When this property is set to true, the IDE will send the optimize flag to the compiler, causing it to generate optimized code.
Target	This property sets the target filesystem where the generated code should be created. This value of this property is sent to the compiler with the Output Dir tag. You should change the name of this tag in the expert tab of the property sheet if your compiler uses a different tag name than the default. (See Table 5-4).

Table 5-4. Expert configuration properties for the External Compilation Service

Property name	Description
Boot Class Path	This property sets the boot classpath where the compiler will find Java sources and extensions.
Boot Class Path Tag Replace	This property sets the tag name to be used for the Boot Class Path property.
Class Path	This property sets the Classpath that will be passed to the external compiler. It will replace the system classpath environment variable.
Debug Tag Replace	This property sets the tag name to be used for the Debug property.
Deprecation Tag Replace	This property sets the tag name to be used for the Deprecation property.
Environment Variables	This property sets a list of environment variables that will be made available to the external compiler. The environment variables should be added as name value pairs. For example, ENV_NAME=ENV_VALUE would set the environment variable ENV_NAME to ENV_VALUE. Use the Environment Variable property editor shown in Figure 5-3.
Filesystem Path	This read-only property shows the filesystem classpath that will be prepended to the classpath parameter sent to the external compiler.
Optimize Tag Replace	This property sets the tag name to be used for the Optimize property.
Output Dir Replace	This property sets the tag name to be used to replace the Target property.

Figure 5-3. Environment variables property editor

Configuring the external process

External Compiler and Execution Services are called via an external process. The properties you set in the property sheets for configuring your service are passed to the external process as program arguments. For example, if you set the debug property to true in the property sheet for an External Compiler Service, the external process (in this case javac) will get an argument -d added to its argument list. Therefore the external process would look something like javac -d. It may be that the compiler you use has a different argument for the debug option than -d, let’s say -debug. In this case you can change the substitution tag in the expert tab of the service’s property sheet from -d to -debug. How does the IDE substitute the debug parameter, and what if there was no parameter (the debug property was set to false)? This is achieved by having a format of the execution command with substitution variables. The format is displayed as a string and stored as a property in the property sheet. For the External Compiler Service, it is the External Compiler property, and for External Execution Service, it is the External Executor property. These properties allow you to configure the external process by modifiying the format of the execution command. A simple execution command might look like:

{jdk.home}{/}bin{/}javac {files}

This command calls javac on the files to be compiled. There are two parts to this command. A process, and the process arguments. In this example the process is {jdk.home}{/}bin{/}javac, and the only process argument is {files}. {jdk.home}, {/} and {files} are all examples of substitution variables. The IDE substitutes these variables with their respective values when the command is executed (i.e., when a file is compiled or executed using this service). Figure 5-4 shows the External Process Configuration dialog. To use this dialog, click on the External Compiler’s (or, if you are configuring an External Execution Service, the External Executor’s) property value in the property sheet and then click on the ellipsis button that appears. (For the rest of this section we will focus on the External Compiler Service for JDK 1.1).

Figure 5-4. External Process configuration dialog

The configuration dialog separates the process from its arguments. You can use the default process, because it uses substitution variables to find the compiler, or you can substitute this property with an absolute path to your compiler. For portability, the IDE offers the {/} substitution variable. This has the same effect as the Java variable File.separator in that it sets the correct file separator for file paths on your platform. For example, {/}jdk1.1.8{/}bin{/}javac becomes jdk1.1.8injavac on Windows and /jdk1.1.8/bin/javac on Unix systems. In the bottom section of the dialog, all the substitution variables are explained. To further explain how substitution variables are used, examine the argument line shown in Figure 5-4. Using this line, if the debug property was set to true, the -d argument would be passed to the process as the value of the substitution variable {debuginfo}.

Because there is not a substitution variable for every possible process argument, what happens when we need to add more arguments to the process? In this case you can directly modify the process arguments line and insert constant arguments. For example, to add the -nowarn argument to the JDK 1.1 process, you can insert the -nowarn argument in the argument line. This is shown in Figure 5-5.

Tip

Be careful when placing constant arguments that they do not conflict with other arguments (for example, the nowarn argument must come before the {files} argument).

Figure 5-5. The JDK External Compiler with the nowarn argument

The IDE sets up one Internal Execution Service after install. This service is not very configurable and usually points to the current JVM pointed to by the JAVA_HOME environment variable. This service can be used to execute Java programs using the JVM with which the IDE was installed. To use different JVMs, you will need to configure an External Execution Service for each JVM you want to use.

External Execution Services allow you to configure a custom JVM to run your Java classes. Like External Compiler Services they are configurable via property sheets. A good case for creating a new service of this type would be for executing code that needs to run in an older JVM version, such as JDK 1.1.

To create a new External Execution Service, select Tools → Options from the menu; right-click on the Debugging and Executing Execution Types node and select New → External Execution from the context menu. Enter a canonical name for your new service and click OK. Your newly created service should appear in the list of Execution Types.

To configure your service, select its node from the list and you should see its property sheet appear. If you don’t see a property sheet, right-click on the node and select Properties from the context menu. The configuration properties for this type of service are described in Tables Table 5-5 and Table 5-6.

To set a service as the default for all Java files, open the Options window and select Editing → Java Sources. In the right pane you can select the default execution from the drop-downs in the property sheet.

You can choose Compilation and Execution Services for each of the files in your project. If you compile the files in bulk, the IDE selects the compiler for each file and executes it in turn. To set a file’s Compilation or Execution Service, right-click on the file and select Properties from the context menu. In the Properties dialog, select the Execution tab. Choose a Compilation Service from the Compiler drop-down, or choose an Execution Service from the Executor drop-down.

The build script that defines targets for Ant to execute is known as an Ant project. A project is simply a collection of targets. To create a new Ant project right-click on the folder in which you wish to add the build script and select New → Ant Build Script → Blank Project from the context menu. A new script should be added to the folder. The script is an XML file that can be edited by right-clicking on the script node and selecting Open from the context menu.

The IDE makes adding targets to the build script very easy by allowing you to add them from the Explorer workspace. To add a new target right-click on the script node and select Add target from the context menu. The new target will be added with the name “changeme.” To see the newly added target you will have to expand the script node. Figure 5-6 shows an expanded build script node with the changeme target. You can change a target’s name by right-clicking on it and selecting Rename from the context menu.

Figure 5-6. An Ant project build script

Finally you will want to add a task to the newly created target. To do this, right-click on the target’s node and select Add Task ... from the context menu. You should see a dialog box like the one shown in Figure 5-7. The dialog box allows you to select a task from a list of valid Ant tasks. Click on the Help button for detailed help on the particular task.

Figure 5-7. Adding a new Ant task

Figure 5-8 shows help for the javac task.

Figure 5-8. Ant Help page

You can add other elements to your build script from the Explorer. For each node, simply right-click and select Add from the context menu, and a list of valid tags should appear.

The Ant module is configurable via property sheets in the Options window, with global settings accessible at Building → Ant Settings. Table 5-7 explains the properties for the Ant settings node.

The module also creates two Compilation Services and an Execution Service—Ant Script Compilation, Indirect Ant Compilation, and Ant Script Execution. All Compilation Services implement Build, Clean, and Compile actions. The Ant Compilation Services have properties that can be configured to define the actions by executing targets in an Ant build script. For example, in the Options window see Building → Compiler Types → Ant Script Compilation. Notice the Build Target(s) property. Its default setting is clean, all. The targets are executed from left to right. If a source object uses Ant Script Compilation, selecting the Build action from the object’s context menu results in executing the clean target, followed by the all target in the Ant build script. See Table 5-8.

The Indirect Ant Compilation compiler service is useful when you want to call an Ant script while compiling another file. For example, it could be used to call the compile target in an Ant script when compiling a Java file. The Indirect Ant Compilation has the very same properties as the Ant Compiler with the addition of a property to specify the Ant script that defines the necessary targets to invoke.

The Ant Executor found in the Options window at Debugging and Executing → Execution Types → Ant Script Execution defines targets to run when an Ant script is executed. The default target of the Ant script is executed if no target is defined here.

By default, double-clicking an Ant build script should run the default target of that script. To run a specific target, you can right-click on the target’s node and select Execute from the context menu. The output from the Ant script should appear in the Output tab. There is usually no need to define compilation for Ant script because you can simply execute the compile target declared in the script. However, if you set the Compiler property to the Ant compiler service, you could select Build or Compile from the Build menu and the respective targets will be executed.

NetBeans already has compilation and execution services for all the object types that are supported for development. Why not just use the services that are provided? The short answer is If you’re happy without Ant, don’t use it. If you only build and execute single classes or small projects, you probably don’t need the flexibility that a build tool like Ant offers. But if you’re involved in a large project, especially a project that has complex needs and unique actions to be performed many times during the course of development, look to Ant for a powerful, easy-to-use, easy-to-configure tool.

For example, this book was developed by several authors working remotely with Linux, Solaris, and Windows computers with shared access to a CVS repository for storing the drafts of chapters, source examples, and related material. The text was written in DocBook XML, which the authors and editors needed to validate and transform into HTML or PDF frequently. We created an Ant build script to perform the tasks. As the project progressed and the variety of tasks expanded, the build script grew to accommodate the needs. A simple CVS update automatically brought the enhanced build script into each author’s environment. Without CVS and Ant, there would have been many more emails and phone calls asking how to do common tasks. With these tools, we have been able to keep our focus on the project goals.