为项目源代码指定类路径

在自由格式项目中，你告诉 IDE 哪些类需要进行代码完成和重构，并为这些项目源指定类路径。在“项目属性”对话框的“Java 源类路径”设置中指定类路径。这样做是因为缺省情况下，不管何时运行 Ant，IDE 都将忽略环境中的 CLASSPATH 变量。

在“项目属性”对话框中设置的类路径变量不会影响 Ant 脚本中指定的项目实际类路径。在“项目属性”对话框中声明类路径不会改变源文件夹的实际编译或运行时类路径。然而，项目类路径变量必须匹配 Ant 脚本所用的类路径，以便为代码编译、错误突出显示和重构命令提供正确信息。你必须在生成脚本中设置显式类路径，因为不管何时运行 Ant，IDE 都将忽略环境中的 CLASSPATH 变量。如果你更改其中一个类路径，就必须更改另一个类路径。

为定制任务指定类路径

在自由格式项目中，可以在生成脚本中调用并运行定制 Ant 任务。为使生成脚本能够使用定制任务，必须将这些任务添加到 IDE 中的 Ant 类路径中。例如，你可能要将一项任务添加到生成脚本以便用 Jalopy 格式化你的代码。然而，为此你必须将 Jalopy JAR 文件添加到 Ant 的类路径。

按下列方法之一，将定制任务添加到 IDE 内的 Ant 类路径：

• 在生成脚本中提供到任务的显式类路径。这是推荐的方法，因为它指定了包含 Ant 脚本要使用的定制任务的 JAR 文件的位置，从而确保了生成脚本是完全可移植的。你可以在生成文件中编写自己的任务以及添加指令，以进行编译和产生 JAR 文件。在使用这些任务时，需要加入一个长 taskdef 标记，并在其中包含类路径。这是此类任务的一个简单示例：

<project name="test" default="all" basedir=".">
    <target name="init">
        <javac srcdir="tasksource" destdir="build/taskclasses"/>
        <jar jarfile="mytasks.jar">
            <fileset dir="build/taskclasses"/>
        </jar>
        <taskdef name="customtask" classname="com.mycom.MyCustomTask">
            <classpath>
                 <pathelement location="mytasks.jar"/>
            </classpath>
        </taskdef>
    </target>
</project>
            

这种方法的优点在于不需要特殊准备即可开始使用脚本。该脚本完全是自包含并可移植的。此方法还使你在 IDE 中开发任务变得更容易，因为脚本会自动为您编译这些任务。

要使您的生成脚本更加稳定，请使用属性来代替固定编码位置，用以指定任务的类路径。你可以将该属性保存在生成脚本或单独的 ant.properties 文件中。然后，只更改指定属性的值就可以使整个脚本的类路径设置得到更改。

• 配置“选项”窗口中的“Ant 类路径”属性。如果无法在生成脚本中声明类路径，或使用无法更改的第三方生成脚本，则可以在“选项”窗口中，将任务添加到 IDE 中的 Ant 类路径。

注意：如果在“选项”窗口中修改了 Ant 类路径，则当在 IDE 中运行 Ant 时，对于所有的项目，任务都在 Ant 的类路径上。

在“项目属性”对话框中映射 IDE 命令

“项目属性”对话框是用来在 IDE 中配置自由格式项目的主要工具。要打开该对话框，在“项目”窗口中，右键单击 自由格式项目节点（图标），然后选择“属性”。在“生成和运行”页中，可为下列命令设置要运行的 Ant 目标：

• 生成项目
• 清理项目
• 生成 Javadoc
• 运行项目（自由格式 Java 项目）
• 部署项目（自由格式 Web 项目）
• 测试项目

注意：如果 Ant 脚本使用 import 语句从另一个 Ant 脚本导入目标， 这些目标不会显示在“项目属性”对话框中的下拉列表。要将命令映射到这些目标，就必须 将目标的名称键入到下拉列表。

还可以在“定制菜单项”列表中，为 Ant 脚本中的任何目标向项目节点的上下文菜单添加快捷键。

在 project.xml 中映射 IDE 命令

每个 IDE 项目都有一个 project.xml 文件，其中包含有关项目的重要元数据、项目 Ant 脚本的位置、为 IDE 命令运行哪些目标，以及其他信息。如果要映射 IDE 中工作于当前选定文件上的命令，或者要将命令映射到单独的 Ant 脚本中的目标，就必须动手编辑 project.xml 文件。在“文件”窗口中，依次展开项目的根文件夹和 nbproject 文件夹，然后双击 project.xml。

ide-actions 元素持有 IDE 命令的映射。输入带任何标准 IDE 操作名称的 action 元素，并定义要将命令映射到的脚本和目标。

可使用下列标准 IDE 操作：

• build - 生成项目（F11）
• rebuild - 清理并生成项目（Shift-F11）
• compile.single - 编译选定文件（F9）
• clean - 清理项目
• run - 运行项目（F6）
• run.single - 运行选定文件（Shift-F6）
• redeploy - 用于 Web 应用程序项目：生成项目、从服务器取消部署项目，和将项目部署到服务器
• test - 为项目运行 JUnit 测试（Alt-F6）
• test.single - 为选定文件运行 JUnit 测试（Ctrl-F6）
• debug.test.single - 为选定文件调试 JUnit 测试（Ctrl-Shift-F6）
• debug - 在调试器中运行项目（F5）
• debug.single - 调试选定文件（Ctrl-Shift-F5）
• debug.fix - 运行“应用代码更改”命令以在调试会话过程中重新装入选定文件
• debug.stepinto - 在调试器中执行项目主类中的一行并暂停（F7）
• javadoc - 为项目生成 Javadoc

例如，下面将“调试项目”映射到项目 Ant 脚本的 debug-nb 目标：

<action name="debug">
    <target>debug-nb</target>
</action>
            

NetBeans IDE 命令的 Ant 脚本不须位于用来生成和运行项目的同一个 Ant 脚本中。这对不想修改 Ant 脚本的用户有用。下面将“调试项目”映射到一个单独的 Ant 脚本中的 debug-nb 目标：

<action name="debug">
    <script>path/to/my/nbtargets.xml</script>
    <target>debug-nb</target>
</action>

注意：<script> 必须在 <target> 之前。

还可以配置一个命令来运行多个目标。这些目标按它们出现在操作中的顺序运行。例如，映射“清理并生成项目”的命令看起来像这样：

<action name="rebuild">
    <target>clean</target>
    <target>compile</target>
</action>

将快捷键添加到项目节点的上下文菜单

project.xml 还有一个 context-menu 元素，它控制项目节点上下文菜单的内容。如果手动添加一个运行在项目上的操作，需确保也将操作名称注册到 <context-menu> 中。如果使用“项目属性”对话框来配置标准项目命令，IDE 会自动将命令添加到项目的上下文菜单。

在 project.xml 文件中使用属性

可以在 project.xml 文件自身内部定义属性，也可以将属性存储在单独的 .properties 文件中。将 project.xml 文件与 Ant 脚本中的信息保持同步的一种方法是：将 Ant 脚本所用的 .properties 文件中的属性导入到 project.xml 中。

然而要注意，project.xml 中的所有文件路径都缺省相对于项目文件夹。如果 Ant 脚本不在项目文件夹中，指向 build/classes/ 的 classdir 属性就不会为 Ant 脚本和 project.xml 文件指向相同的目录。（项目文件夹是指包含 nbproject 文件夹的文件夹，而不是 nbproject 文件夹本身。缺省情况下，新建自由格式项目向导使 Ant 脚本的副文件夹成为项目文件夹。）

可通过为重要路径（像 project.dir）定义属性并让这些属性更准确来解决此问题（例如，classdir=${project.dir}/build/classes）。

要在 project.xml 中创建和导入属性，需要在 name 元素和 folders 元素之间输入以下内容：

<properties>
    <property name="name">value</property>
    <property-file>my-properties-file.properties</property-file>
    <property-file>another-properties-file.properties</property-file>
</properties> 

注意语法和 Ant 脚本中使用的语法不同。还要注意尽管可以按任意顺序添加属性，但这些属性只能引用此前已在 project.xml 中定义的其他属性。属性文件路径本身也可以使用属性替换。

验证 project.xml 文件

IDE 与自由格式 project.xml 文件的 XML 架构捆绑在一起，在每次编辑和保存自由格式的 project.xml 文件时，IDE 都会自动对其进行验证。您可以在以下位置查看自由格式 project.xml 文件的 XML 架构：

• http://www.netbeans.org/ns/freeform-project/1.xsd。控制自由格式 project.xml 的主体部分（<general-data>）。
• http://www.netbeans.org/ns/freeform-project-java/1.xsd。控制 <java-data> 部分。
• http://www.netbeans.org/ns/freeform-project-web/1.xsd。控制 <web-data> 部分（如果有该部分的话）。

创建调试目标

如果没有为项目编写 debug 目标，则在第一次尝试调试项目时，IDE 将为你生成一个基本目标。然后你可以检查该目标，并对该目标进行定制以满足项目的特定需求。

注意：在生成调试目标前，最好先确保有映射到“运行项目”命令的目标。当 IDE 生成调试目标时，它在已映射到“运行项目”命令的目标中查找相关信息以确定运行类路径和项目的主类等。如果已将某个目标映射到“运行项目”命令，则很可能不需要进一步定制就可以使用生成的调试目标。

为自由格式项目创建调试目标：

1. 在“项目”窗口中，右键单击项目节点，然后选择“设置为主项目”。
2. 选择“调试”>“调试主项目”。
3. 在出现的“调试项目”对话框中，单击“生成”。

   将在名为 ide-targets.xml 的文件中创建一个名为 debug-nb 的目标。生成的 ide-targets.xml 文件是一个用于导入主 build.xml 文件的生成脚本，因此，调试目标可以利用主生成脚本设置或引用的目标和属性。

   此外，还会在 project.xml 文件中创建该目标的映射，以便在 IDE 中选择“调试项目”命令时调用该目标。如果从头开始编写目标，还需要自行创建该映射。参见手动将目标映射到菜单项。

4. 验证生成的 debug-nb 目标是否适当地兼顾了项目的所有元素。特别是，如果目标未在运行类路径中包含所有项，则可能需要在目标中修改 <classpath> 参数。

在创建目标后，便可以开始调试了。开始调试：

1. 在主类中设置一个断点。单击要设置断点的行的左侧空白处，可以完成此操作。具有断点的行将以粉红色突出显示。
2. 重新右键单击项目的节点，然后选择“调试项目”。

   将运行目标并开始执行程序。目标的运行进度将显示在“输出”窗口中，而调试器的状态则显示在“输出”窗口底部的状态栏中。

典型的自由格式项目调试目标

生成的 Ant 目标将执行以下操作：

• 使用 nbjpdastart 任务启动调试器。
• 在 jpda.address 属性（addressproperty="jpda.address"）中存储调试器侦听应用程序时所在的地址。不必在 Ant 脚本或属性文件中定义 jpda.address 属性。该属性是由 IDE 定义的。
• 建立运行时类路径。如果 IDE 无法确定运行时类路径，则会在脚本中放置一些占位符，你需要亲自填充这些值。
• 在调试模式下运行应用程序，设置 fork="true" 可确保进程在单独的虚拟机中启动。

注意：还可在 java 中附加任何 JVM 参数或程序参数。

生成的调试目标（IDE 能够猜测出运行时类路径）会按以下方式显示，其中，斜体项表示特定于具体项目的值：

<?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/archive/index.html) -->
    <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="-Xnoagent"/>
    <jvmarg value="-Djava.compiler=none"/>
    <jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>
    </java>
    </target>
</project>
            

如果尚未映射运行目标，或者 IDE 无法确定项目的类路径或主类，则生成的调试目标会包括“TODO”占位符，你可以按以下示例填充这些值。

<?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/archive/index.html) -->
    <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="-Xnoagent"/>
    <jvmarg value="-Djava.compiler=none"/>
    <jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>
    </java>
    </target>
</project>
            

要指定运行时类路径，需要在 path 元素中插入 pathelement 元素，并将它们指向包含类路径项的目录。例如，可以使用 pathelement 的 location 属性来指定类路径项相对于项目目录的位置。项目目录通常是包含项目的 build.xml 文件的目录。下面是一个示例：

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

手动将目标映射到菜单项

在 IDE 为您生成某个目标时，IDE 会自动提供该目标与 IDE 命令的菜单项之间的映射。但是，如果手动创建目标，则还需要手动创建映射。

将“调试项目”命令映射到外部 Ant 脚本中的目标：

1. 打开项目的 project.xml 文件，并将以下代码添加到 <ide-actions> 中：

       <action name="debug">
           <script>path_to_Ant_script</script>
           <target>target_name</target>
       </action>
                       

2. 通过将下面一行添加到 <context-menu> 目标中，可以将命令添加到项目节点的上下文菜单中：

       <ide-action name="debug"/>
                       

   IDE 会将“调试项目”操作映射到项目 Ant 脚本中的指定目标。

使用调试目标

在能够使用调试目标前，需要部署应用程序。因此，启动服务器并运行部署应用程序。注意首次逐会话运行应用程序时，Tomcat Web 服务器会向你询问用户名和口令。唯一可接受得用户名和口令是具有“manager”角色的用户。这在 Tomcat Web 服务器主目录中的 conf/tomcat-users.xml 文件中定义。要确定该目录的位置，在“服务”窗口中右键单击 Tomcat Web 服务器实例，然后选择“属性”。在“属性”对话框中，“主目录”属性指向 Tomcat Web 服务器的主目录。

一旦应用程序已被部署，停止服务器并以调试模式启动。完成的方式和服务器有关：

• 捆绑的 Tomcat Web 服务器

  在“服务”窗口展开“服务器”节点，右键单击“捆绑的 Tomcat”节点，选择“启动/停止服务器”，然后单击“启动服务器（调试）”。

• 外部 Tomcat Web 服务器

  运行以下命令：

      catalina jpda start
              

一旦服务器以调试模式启动，就选择“运行”>“调试主项目”（F5）。应用程序将被部署然后附着到调试器。调试器在第一个断点停止，然后就可以“步入”（F7）或“越过”（F8）代码。

调试目标疑难解答

虽然 IDE 尽可能为你生成完整的调试目标，并带有最适合你的特定环境的属性，你也始终应当分析和微调调试过程。如果在使用 NetBeans IDE 生成的 Ant 调试目标时遇到问题，可通读下列问题：

回到页首

运行选定的文件

我们演示一下运行一个类时是如何工作的。一个用来运行项目的典型目标看起来像下面这样：

    <target name="run2" depends="...">
        <java fork="true" classname="MyMainClass" classpath="MyRunClasspath" />
    </target>
            

目标根据 classname 运行指定的文件。要在 IDE 中运行当前选定的文件，你需要将上面的目标修改为下面的样子：

    <target name="run-selected-file" depends="compile" description="Run Single File">
        <fail unless="runclass">Must set property 'classname'</fail>
        <java classname="${runclass}">
            <classpath refid="run.classpath"/>
        </java>
    </target>
            

在 IDE 中获取当前选定文件的引用

一旦有了运行选定文件的 Ant 目标，就必须在 IDE 中获取到那个文件的引用，并存储到一个属性中。例如，上面的 run-selected-file 目标在 runclass 属性中寻找当前选中的文件。

将此引用存储到和将生成目标映射到 IDE 操作（run-selected-file）相同的位置。我们先看看如何做，然后下详细解释：

    <action name="run.single">
        <target>run-single</target>
        <context>
            <property>runclass</property>
            <folder>${src.dir}</folder>
            <pattern>\.java$</pattern>
            <format>java-name</format>
            <arity>
                <one-file-only/>
            </arity>
        </context>
    </action>
            

runclass 属性是新定义的，它持有要运行的文件，并被 java 任务引用。

现在看看下面几行来了解工作方式。

    <action name="run.single">
        <target>run-selected-file</target>
        <context>
    <property>runclass</property>
            

• <action name="run.single"> 映射“运行文件”命令，F9 快捷键映射 run-selected-file 目标。
• <context> 设置 Ant 目标运行在其上的上下文。本例中为要运行的文件的名称。
• runclass 是持有上下文的属性名称。可为该属性选择任何唯一的名称。该属性必须在目标运行前由 IDE 设置。
• <arity> 指定 runclass 只能持有一个文件。 如果想要该属性能够持有一个以上的文件（例如对“编译文件”目标），可使用下列代码，逗号（,）是文件名称的分隔符：

      <arity>
          <separated-files>,</separated-files>
      </arity>
                      

• <format>java-name</format> 指定 IDE 应当将相对文件名称传递给目标， 但由点号（.）分界，并不带扩展名。其他格式化选项如下所示：
  • relative-path - 指定IDE 应当将相对文件名称传递给目标
  • relative-path-noext - 同 relative-path，但删除了文件扩展名
  • absolute-path - 绝对文件名
  • absolute-path-noext - 同 absolute-path，但删除了文件扩展名
• <folder>${src.dir}</folder> 指定文件名必须相对于 src.dir 目录，且该操作只对 src.dir 目录启用。

  注意：IDE 不会为你定义 ${src.dir} 属性。必须定义该属性，或导入 Ant 在 project.xml 中使用的 .properties 文件。参见在 project.xml 文件中使用属性。

• <pattern>\.java$</pattern> 是文件名称必须通过的正则表达式。使用 <pattern> 来限制哪些文件可以传给 Ant 目标。本例中，你将要让目标只能用 .java 结尾的文件来运行。

调试选定的文件

过程基本上和编写目标以调试和运行单个文件相同。debug-selected-files 目标看起来像这样：

    <target name="debug-selected-files" depends="compile" if="netbeans.home" description="Debug a Single File">
        <fail unless="classname">Must set property 'classname'</fail>
        <nbjpdastart name="${classname}" addressproperty="jpda.address" transport="dt_socket">
            <classpath refid="run.classpath"/>
            <!-- Optional - If source roots are properly declared in project, should
            work without setting source path.
            <sourcepath refid="debug.sourcepath"/> -->
        </nbjpdastart>
        <java classname="${classname}" fork="true">
            <jvmarg value="-Xdebug"/>
              <jvmarg value="-Xnoagent"/>
              <jvmarg value="-Djava.compiler=none"/>
              <jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>
              <classpath refid="run.classpath"/>
        </java>
    </target>
            

• 这基本和 debug 目标相同。不将主类，而是将 classname 属性传递给 java，它被 IDE 设置为当前选定的文件。

然后将 debug-selected-files 目标映射到 debug.single操作：

    <action name="debug.single">
        <target>debug-selected-files</target>
        <context>
            <property>classname</property>
            <folder>${src.dir}</folder>
            <pattern>\.java$</pattern>
            <format>java-name</format>
            <arity>
                <one-file-only/>
            </arity>
        </context>
    </action>
            

• <property> 现在在 classname 属性中存储上下文。
• 既然 java 只能处理单个文件，就将 <arity> 设置为 <one-file-only>。
• 将 <format> 设置为 java-name，使它相对于 src.dir 可为当前选定的文件创建全限定类名。

  注意：IDE 不会为你定义 ${src.dir} 属性。必须定义该属性，或导入 Ant 在 project.xml 中使用的 .properties 文件。参见在 project.xml 文件中使用属性。

回到页首