高级自由形式项目配置

在 Project Properties 对话框中映射 IDE 命令

Project Properties 对话框是在 IDE 中配置自由形式项目的主要工具。若要打开对话框，请在 Projects 窗口中右键单击自由形式项目节点（图标），并选择 Properties。在 Build and Run 页中，可以设置一些 Ant 目标，使之在使用以下命令时运行：

• Build Project
• Clean Project
• Generate Javadoc
• Run Project（自由形式 Java 项目）
• Deploy Project（自由形式 Web 项目）
• Test Project

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

在 Custom Menu Items 列表中，也可以将 Ant 脚本中任何目标的快捷键添加到项目节点的上下文菜单中。

在 project.xml 中映射 IDE 命令

每个 IDE 项目都有一个 project.xml 文件，包含了有关项目内容的重要元数据、项目 Ant 脚本的位置、为 IDE 命令运行的目标和其他信息。如果要在 IDE 中映射适用于当前所选文件的命令，或者要将命令映射到独立 Ant 脚本中的目标，则必须手动编辑 project.xml 文件。在 Files 窗口中，展开项目的根文件夹和 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 - 在调试会话期间运行 Apply Code Changes 命令以重新载入所选文件
• debug.stepinto - 在调试器中，执行一行项目主类，然后暂停 (F7)
• javadoc - 为项目生成 Javadoc

例如，下面将 Debug Project 映射到项目 Ant 脚本的 debug-nb 目标：

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

映射 NetBeans IDE 命令的 Ant 目标所在的 Ant 脚本不必与构建和运行项目时使用的 Ant 脚本相同。这对于不能修改其 Ant 脚本的用户是很有用的。下面将 Debug Project 映射到独立 Ant 脚本中的 debug-nb 目标：

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

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

也可以配置一个命令运行多个目标。这些目标按照它们在操作中出现的顺序运行。例如，Clean and Build Project 命令的映射如下所示：

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

将快捷方式添加到项目节点上下文菜单中

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

返回页首

使用 project.xml 文件中的 Properties

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

但是，请注意在默认情况下，project.xml 中的所有文件路径是项目文件夹的相对路径。如果 Ant 脚本不在项目文件夹中，则 classdir 属性（指向 build/classes/）不会指向 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 架构捆绑在一起，在每次进行编辑和保存时，IDE 都会自动验证自由形式 project.xml 文件。您可以在以下位置查看自由形式 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 会为您生成一个基本目标。然后可以查看该目标，并按照项目特定需要对目标进行自定义。

注意：在生成调试目标之前，最好首先确保已将目标映射到 Run Project 命令。IDE 生成调试目标时，会在已映射到 Run Project 命令的目标中到查找相关信息，以确定运行类路径和项目主类等。如果已将某个目标映射到 Run Project 命令，最好的选择是不需要进一步自定义就可以使用生成的调试目标。

创建自由形式项目的调试目标的步骤：

1. 在 Projects 窗口中，右键单击该项目节点，并选择 Set Main Project。
2. 选择 Run > Debug Main Project。
3. 在出现的 Debug Project 对话框中，单击 Generate。

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

   另外，还会在 project.xml 文件中创建该目标的映射，这样只要您选择 IDE 中的 Debug Project 命令，就会调用该目标。如果您从头编写目标，则您还需要自己创建该映射。请参见手动将目标映射到菜单项。

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

创建目标后，您就可以开始调试了。开始调试的步骤：

1. 在主类中设置一个断点。在要添加断点的行的左侧空白处单击来执行上述操作。具有断点的行以粉红色突出显示。
2. 再次右键单击项目节点并选择 Debug Project。

   会运行目标，并开始执行程序。运行目标的进度会显示在 Output 窗口中，编辑器的状态会显示在 Output 窗口底部的状态栏中。

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

生成的 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/articles/41/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="-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/articles/41/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="-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 命令的菜单项之间的映射。但是，如果您手动创建了目标，您还需要手动创建映射。

将 Debug Project 命令映射到外部 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 将 Debug Project 操作映射到项目 Ant 脚本中指定的目标。

使用调试目标

在可以使用调试目标前，您必须部署应用程序。因此，请启动服务器并运行应用程序部署命令。请注意，在每次会话中，首次运行应用程序时，Tomcat Web Server 会要求您输入用户名和密码。唯一可接受的用户名和密码是具有“管理员”角色用户所使用的用户名和密码。这在 Tomcat Web Server 基目录的 conf/tomcat-users.xml 文件中进行了定义。若要确定该目录的位置，在 Runtime 窗口中右键单击 Tomcat Web Server 实例节点，并选择 Properties。在 Properties 对话框中，请将 Base Directory 属性指向 Tomcat Web Server 的基目录。

部署应用程序后，请停止服务器并以调试模式重新启动服务器。完成上述操作的方式取决于服务器：

• 绑定的 Tomcat Web Server
  在 Runtime 窗口中，展开 Servers 节点，右键单击 Bundled Tomcat 节点，选择 Start/Stop Server，并单击 Start Server (Debug)。
• 外部 Tomcat Web Server
  运行下面命令：

    catalina jpda start 

在调试模式下启动服务器后，选择 Run > Debug Main Project (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 属性中查找当前所选文件。

将该引用存储在将构建目标 (run-selected-file) 映射到 IDE 操作所在的相同位置中。首先，我们来看一下如何实现上述操作，然后再进行详细讲解：

    <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>

• 将 Run File 命令和 F9 快捷键映射到 run-selected-file 目标。

      <context>
        <property>runclass</property>

• <context> 设置执行 Ant 目标的上下文。在这种情况下，它是要运行文件的名称。
• runclass 是保存上下文的属性的名称。可以为该属性选择任何唯一的名称。在运行目标前，该属性必须由 IDE 设置。

• <arity> 指定 runclass 仅能保存一个文件。如果希望属性可以保存一个以上的文件（如用于 Compile File 目标），则可以使用下面代码，其中逗号 (,) 是文件名之间的分隔符：

          
            ,
          
  

• <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 文件中的 Properties。
• <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 目标基本相同。不是将程序主类传递给 java，而是传递 IDE 为当前所选文件设置的 classname 属性。

然后，将 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 文件中的 Properties。

返回页首