Creating A Debug Target for a Free-Form Java Project

See Also 

To run a project in the IDE's debugger, you have to have a special target in your project's build script. That target needs to be mapped to the IDE's Debug Project command.

If you do not have a debug target written for your project, the IDE will offer to generate a basic target for you when you first try to debug the project. You can then inspect the target and customize it for the project's specific requirements.

To create a debug target for a free-form project:

  1. In the Projects window, right-click the project's node and choose Set Main Project.
  2. Choose Debug > Debug Main Project.
  3. In the Debug Project dialog box that appears, click Generate.

    A target called debug-nb is created in a file called ide-targets.xml. The generated ide-targets.xml file is a build script that imports your main build.xml file, so your debug target can take advantage of targets and properties set by or referenced by your main build script.

    In addition, a mapping for this target is created in the project.xml file so that the target is called whenever you choose the Debug Project command in the IDE. If you write the target from scratch, you need to also create this mapping yourself. See Manually Mapping a Target to a Menu Item.

  4. Verify that the generated debug-nb target properly takes into account all of the elements of your project. In particular, you might need to modify the <classpath> argument in the target if it does not include all of the items in your run classpath.

Once the target is created, you can start debugging. To start debugging:

  1. Set a breakpoint in your main class. You can do so by clicking in the left margin of the line where you want to set the breakpoint. The line with the breakpoint is highlighted in pink.
  2. Once again, right-click the project's node and choose Debug Project.

    The target should run and start execution of the program. Progress of the running target is shown in the Output window and the status of the debugger is shown in the status bar at the bottom of the Output window.

A Typical Free-Form Project Debug Target

The generated Ant target does the following:

A generated debug target where the IDE is able to guess the runtime classpath looks something like the following (where italicized items would have values specific to your project):

<?xml version="1.0" encoding="UTF-8"?>
    <project basedir=".." name="YourProjectName">
    <import file="../build.xml"/>
    <!-- TODO: edit the following target according to your needs -->
    <!-- (more info: http://www.netbeans.org/kb/55/freeform-config.html#debugj2se) -->
    <target name="debug-nb">
    <nbjpdastart addressproperty="jpda.address" name="NameOfProject" transport="dt_socket">
    <classpath path="ClasspathSpecifiedInYourRunTarget"/>
    </nbjpdastart>
    <java classname="MainClassSpecifiedInRunTarget" classpath="ClasspathSpecifiedInYourRunTarget" fork="true">
    <jvmarg value="-Xdebug"/>
    <jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>
    </java>
    </target>
    </project>

If you do not have a run target mapped or the IDE otherwise can not determine the project's classpath or main class, the generated debug target includes "TODO" placeholders for you to fill in these values as in the example below.

<?xml version="1.0" encoding="UTF-8"?>
    <project basedir=".." name="YourProjectName">
    <!-- TODO: edit the following target according to your needs -->
    <!-- (more info: http://www.netbeans.org/kb/55/freeform-config.html#debugj2se) -->
    <target name="debug-nb">
    <path id="cp">
    <!-- TODO configure the runtime classpath for your project here: -->
    </path>
    <nbjpdastart addressproperty="jpda.address" name="NameOfProject" transport="dt_socket">
    <classpath refid="cp"/>
    </nbjpdastart>
    <!-- TODO configure the main class for your project here: -->
    <java classname="some.main.Class" fork="true">
    <classpath refid="cp"/>
    <jvmarg value="-Xdebug"/>
    <jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>
    </java>
    </target>
    </project>

To specify the runtime classpath, insert pathelement elements within the path element and point them to the directories that contain the items in your classpath. For example, you can use the location attribute of pathelement to specify the location of the classpath items relative to your project directory. The project directory is usually the one that contains the project's build.xml file. Below is an example:

<path id="cp">
    <pathelement location="libs">  
    <pathelement location="build">
</path>

Manually Mapping a Target to a Menu Item

When you have the IDE generate a target, the IDE automatically provides the mapping between the target and the IDE command's menu item. However, if you have created the target manually, you need to also create the mapping manually.

To map the Debug Project command to a target in an external Ant script:

  1. Open the project's project.xml file and add the following to <ide-actions>:
      <action name="debug">
            <script>path_to_Ant_script</script>
            <target>target_name</target>
            </action> 
  2. Add the command to the project node's contextual menu, by adding the following line to the <context-menu> target:

      <ide-action name="debug"/>

    The IDE maps the Debug Project action to the specified target in the project's Ant script.

Troubleshooting

If you have successfully created a debug target and started the debugger, but the debugger does not stop at breakpoints, you the IDE is probably lacking debugging information or knowledge of where your sources are. See About Debugging Free-Form Projects for more information.

For a full guide to configuring free-form projects, see:

See Also
About Free-Form Projects
Creating A Debug Target for a Free-Form Web Project
Mapping an Ant Target to an IDE Command
Storing IDE Targets in a Separate Ant Script

Legal Notices