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.

Perform the following steps to create a debug target for a free-form project.

  1. Set the free-form project as the main project by choosing Run > Set Main Project in the main menu and selecting the project.
  2. Choose Debug > Debug Main Project from the main menu.
  3. Click Generate in the Debug Project dialog box.

    When you click Generate a target named debug-nb is created in a file named 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.

After the target is created, you can perform the following steps to start debugging the project.

  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. Right-click the project's node again 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:

For example, if the IDE is able to guess the runtime classpath the debug-nb target that the IDE generates in ide-targets.xml might look similar to the following.

<?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/articles/freeform-config.html#debugj2se) -->
        <target name="debug-nb" depends="init,compile">
            <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 cannot determine the project's classpath or main class, the generated debug target includes "TODO" placeholders for you to fill in these values.

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.

Perform the following steps 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 the following document.

See Also
About Free-Form Projects
Mapping an Ant Target to an IDE Command
Storing IDE Targets in a Separate Ant Script

Legal Notices