Setting up the Debug Project Command for a General Java Application

To get debugging to work with a free-form project, you need to:

• Make sure that the target you use for compiling specifies debug="true" when calling the javac task.

• Create a mapping in the IDE between the project's sources and the project's outputs so that the debugger knows which sources to display when you are stepping through the running program.

• Add a target to your Ant script for the command, making sure that all necessary path elements for the command are defined, either in the build script or in a .properties file that is called by the script.

Mapping the Project's Sources to Its Outputs

In NetBeans IDE 5.0 free-form projects, the IDE does not automatically know which sources are associated with compiled classes that you run. Therefore, to get the IDE's debugging features to work, you need to create this mapping between the sources and the outputs.

To map a free-form project's sources to its outputs:

1. In the Projects window, right-click the project's node and choose Properties.

2. In the Project Properties dialog box, select the Output node.

3. In the right pane, click the Add JAR/Folder button and navigate to the folder or JAR file that contains the compiled classes corresponding to the source root selected in the Source Packages Folder field.

If you have multiple source roots, repeat this step for each source root listed in the Source Packages Folder field.

When you create your debug target, the outputs you specify here will need to be referenced as part of the classpath attribute of the jpdastart (or nbjpdaconnect) task.

Creating the Debug Target

You can have the IDE generate a debug target for you by running the Debug Main Project command (assuming you have set the free-form project as your main project) or Debug Project command and then clicking the Generate button in the dialog box that appears.

When you generate the target, it appears in a file called ide-file-targets.xml, which imports your main build script. This enables you to have IDE-only targets separate from other targets but still allow the IDE-specific targets to reference targets and properties in your main build script.

If you already have the Run Project command mapped, the generated Debug Project target should look something like the following:

   <target name="debug-nb">        <nbjpdastart addressproperty="jpda.address" name="ProjectName"            transport="dt_socket">           <classpath path="build"/>       </nbjpdastart>       <java classname="MainClass" classpath="build" fork="true">           <jvmarg value="-Xdebug"/>           <jvmarg value="-Xnoagent"/>           <jvmarg value="-Djava.compiler=none"/>           <jvmarg value="-Xrunjdwp:transport=dt_socket,               address=${jpda.address}"/>       </java>   </target>

In many cases, the generated target will work without modification. If the target does not work or does not work the way you want it to, you can modify it by hand. See Table 16-3 for further details and some things to look out for.

Table 16-3. Details of the Debug Target for a General Java Application

Target, Task, Attribute, or Property	Description
depends	An optional attribute of the target, where you specify other targets that need to be run before the current target is run. This attribute is not specified in the generated target, but you might want to add it.
netbeans.home	Ant property that is loaded by any instance of Ant that runs inside of the IDE. The if="netbeans.home" attribute ensures that the target is run only if it is called from within the IDE. This attribute is not included in the generated debug target, but might be useful in other targets that you include directly in your build script.
nbjpdastart	A special task bundled with the IDE to debug programs within the JPDA debugger.
addressproperty	An attribute of nbjpdastart that defines the property that holds the port that the debugger is listening on. (The IDE automatically assigns the port number to the property.) The value of the property that is defined there (in the case of the examples given on the previous page, jpda.address) is passed as the value for the address suboption of the -Xrunjdwp option.
transport	An attribute specifying the debugging transport protocol to use. You can use dt_socket on all platforms. On Windows machines, you can also use dt_schem.
classpath	An attribute of both the nbjpdastart and the java tasks that represents the classpath used for debugging the application. When generating the debug target, the IDE fills in the classpath provided by the Run Project target, if possible.
sourcepath	An optional attribute of nbjpdastart used to specify the explicit location of source files that correspond to JAR files in your classpath. If you have associated your sources with JAR files in the Output panel of the project's Project Properties dialog box or in the IDE's Library Manager, you should not need to set this attribute. This attribute is not included in the generated target.
fork	Attribute of the java task that determines whether the debugging process is launched in a separate virtual machine. For this target, the value must be TRue.
classname	Attribute of the java task. It points to the class that the debugger executes. For the Debug Project target, this attribute should be the fully qualified name of the main class of the project. When generating the debug target, the IDE fills in the classname provided by the Run Project target, if possible.
jvmarg	Parameter of the java element for providing arguments to the JVM. The arguments provided in the example are typical for debugging Java SE applications with the JPDA debugger.

If you have generated the debug target without having previously designated a run target in the project, the generated target will have some gaps that you need to fill in. Such a target might look something like the following:

<target name="debug-nb">     <path >         <!-- TODO configure the runtime classpath for your project here:         -->     </path> <nbjpdastart addressproperty="jpda.address" name="Notepad"        transport="dt_socket">     <classpath ref/> </nbjpdastart> <!-- TODO configure the main class for your project here: --> <java classname="some.main.Class" fork="true">     <classpath ref/>     <jvmarg value="-Xdebug"/>     <jvmarg value="-Xnoagent"/>     <jvmarg value="-Djava.compiler=none"/>     <jvmarg value="- Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>     </java> </target>

The TODO comments mark places where you need to fill in the runtime classpath and the project's main class. For the main class, enter the fully-qualified classname. For the classpath, you could place pathelement elements within the provided path element. For example, you could use the location attribute of pathelement to specify the location of folders relative to your project directory (usually the one that contains the build.xml file) as in the sample below:

<path >     <pathelement location="libs">     <pathelement location="classes"> </path>

If your project is more complex, you can nest path elements, where the path attribute of pathelement references a different path element, as in the following example:

<path >     <pathelement path="${javac.classpath}">     <pathelement path="${build.classes.dir}"> </path>