导入

描述

将另一个构建文件导入到当前项目中。

执行时，它将选择合适的 ProjectHelper 来解析导入的文件，使用与在 启动 时执行的相同算法。然后，选定的 ProjectHelper 实例将负责实际解析导入的文件。

注意 如上所示，此任务严重依赖于 ProjectHelper 实现，并且没有真正执行任何自身工作。如果您已将 Apache Ant 配置为使用除 Ant 默认值以外的 ProjectHelper，则此任务可能有效也可能无效。

在仅使用 Ant 默认项目帮助程序的常见用例中，它基本上与 Ant 常见问题解答中解释的实体包含 一样，就好像导入文件包含在导入文件中一样，减去顶部的 <project> 标签。

import 任务只能用作顶级任务。这意味着它不能在目标中使用。

还有两个与该任务相关的功能方面，而实体包含无法实现。

• 目标覆盖
• 特殊属性

目标覆盖

如果主文件中的目标也存在于至少一个导入文件中，则来自主文件中的目标优先。

因此，如果我导入例如包含名为 builddocs 的项目的 docsbuild.xml 文件，该项目包含一个 docs 目标，我可以在我的主构建文件中定义一个 docs 目标，并且该目标将被调用。这使得保持相同的目标名称变得容易，以便任何其他目标（无论是在主构建文件中还是在导入的构建文件中）都仍然可以调用覆盖目标，作为其依赖项，但具有不同的实现。来自 docsbuild.xml 的目标通过名称 builddocs.docs 提供。这使新实现能够调用旧目标，从而通过在它之前或之后调用的任务来增强它。

如果您使用任务的 as 属性，它的值将用于作为前缀添加到覆盖目标的名称，而不是 project 标签的 name 属性。

特殊属性

导入文件被视为它们存在于主构建文件中。这使得理解变得容易，但它使得它们无法引用相对于其路径的文件和资源。因此，对于每个导入文件，Ant 添加一个包含导入构建文件路径的属性。使用此路径，导入的构建文件可以保留资源并能够相对于其位置引用它们。

因此，如果我导入例如名为 builddocs 的 docsbuild.xml 文件，我可以将其路径作为 ant.file.builddocs 获取，类似于主构建文件的 ant.file 属性。

请注意，builddocs 不是文件名，而是导入的 project 标签中存在的 name 属性。

如果导入的文件没有 name 属性，则不会设置 ant.file.projectname 属性。

从 Ant 1.8.0 开始，该任务还可以从 URL 或类路径资源（实际上是 URL）导入资源。如果您需要知道当前构建文件的源代码是文件还是 URL，您可以查询属性 ant.file.type.projectname（使用与上述相同的示例 ant.file.type.builddocs），它要么具有值 file，要么具有值 url。

解析相对于导入文件的资源

假设您的主构建文件名为 importing.xml，它导入一个构建文件 imported.xml，该文件位于文件系统的任何位置，并且 imported.xml 从 imported.properties 中读取一组属性。

<!-- importing.xml -->
<project name="importing" basedir="." default="...">
  <import file="${path_to_imported}/imported.xml"/>
</project>

<!-- imported.xml -->
<project name="imported" basedir="." default="...">
  <property file="imported.properties"/>
</project>

但是，此代码段将解析相对于 importing.xml 的 basedir 的 imported.properties，因为 Ant 忽略了 imported.xml 的 basedir。使用 imported.properties 的正确方法是

<!-- imported.xml -->
<project name="imported" basedir="." default="...">
  <dirname property="imported.basedir" file="${ant.file.imported}"/>
  <property file="${imported.basedir}/imported.properties"/>
</project>

如上所述，ant.file.imported 存储定义名为 imported 的项目的构建脚本的路径（简而言之，它存储 imported.xml 的路径），并且 <dirname> 获取其目录。此技术还允许 imported.xml 作为独立文件使用（无需导入到其他项目中）。

以上描述仅适用于实际从文件而不是从 URL 导入的导入文件。对于从 URL 导入的文件，使用相对于导入文件的资源需要您首先使用可以处理非文件资源的任务。要创建相对资源，您可以使用类似以下内容：

<loadproperties>
  <url baseUrl="${ant.file.imported}"
       relativePath="imported.properties"/>
</loadproperties>

参数

作为嵌套元素指定的参数

任何 资源 或资源集合

从 Ant 1.8.0 开始

将导入指定的资源。

示例

<import file="../common-targets.xml"/>

从位于父目录中的 common-targets.xml 文件导入目标。

<import file="${deploy-platform}.xml"/>

导入由属性 deploy-platform 定义的项目。

<import>
  <javaresource name="common/targets.xml">
    <classpath location="common.jar"/>
  </javaresource>
</import>

从 common.jar 文件夹中的 common 文件夹中的 targets.xml 文件导入目标。

<import> 与 <include> 有什么区别？

简而言之：如果您打算覆盖目标，请使用 import，否则请使用 include。

当使用 import 时，导入的目标最多可以使用两个名称：没有前缀的“正常”名称，以及可能带有前缀的名称（as 属性的值或导入项目的 name 属性，如果有）。

当使用 include 时，包含的目标仅以带前缀的形式提供。

当使用 import 时，导入目标的 depends 属性保持不变，即它使用“正常”名称，并允许您覆盖依赖项列表中的目标。

当使用 include 时，包含的目标无法被覆盖，并且它们的 depends 属性被重写，以便使用带前缀的名称。这允许包含文件编写者控制作为依赖项的一部分调用的目标。

可以通过使用不同的前缀多次include 同一个文件；无法多次import 同一个文件。

示例

nested.xml 应为

<project>
  <target name="setUp">
    <property name="prop" value="in nested"/>
  </target>

  <target name="echo" depends="setUp">
    <echo>prop has the value ${prop}</echo>
  </target>
</project>

当像这样使用 import 时

<project default="test">
  <target name="setUp">
    <property name="prop" value="in importing"/>
  </target>

  <import file="nested.xml" as="nested"/>

  <target name="test" depends="nested.echo"/>
</project>

运行构建文件将发出

setUp:

nested.echo:
     [echo] prop has the value in importing

test:

当像这样使用 include 时

<project default="test">
  <target name="setUp">
    <property name="prop" value="in importing"/>
  </target>

  <include file="nested.xml" as="nested"/>

  <target name="test" depends="nested.echo"/>
</project>

运行目标构建文件将发出

nested.setUp:

nested.echo:
     [echo] prop has the value in nested

test:

并且包含的构建文件中将没有名为 echo 的目标。