インポート

説明

別のビルドファイルを現在のプロジェクトにインポートします。

実行時、インポートされたファイルを解析するために適切なProjectHelperを、起動時に実行されるものと同じアルゴリズムを使用して選択します。選択されたProjectHelperインスタンスが、実際にインポートされたファイルを解析する責任を負います。

注 上記のように、このタスクはProjectHelperの実装に大きく依存しており、それ自体では実際には何も作業を実行しません。Apache AntをAntのデフォルト以外のProjectHelperを使用するように構成している場合、このタスクは機能するかもしれないし、機能しないかもしれません。

Antのデフォルトのプロジェクトヘルパーのみが使用される一般的なユースケースでは、基本的にはAnt FAQで説明されているエンティティインクルードのように動作します。インポートされたファイルが、トップレベルの<project>タグを除いて、インポート側のファイルに含まれているかのように動作します。

importタスクはトップレベルのタスクとしてのみ使用できます。つまり、ターゲット内で使用することはできません。

このタスクに関連する、エンティティインクルードでは不可能な、さらに2つの機能面があります。

ターゲットのオーバーライド

メインファイル内のターゲットが、少なくとも1つのインポートされたファイルにも存在する場合、メインファイルのターゲットが優先されます。

たとえば、docsbuild.xmlという、docsターゲットを含むbuilddocsというプロジェクトを含むファイルをインポートする場合、メインのビルドファイルにdocsターゲットを定義できます。これが呼び出されるターゲットになります。これにより、同じターゲット名を維持することが容易になります。そのため、オーバーライドされたターゲットは、依存関係であるメインまたはインポートされたビルドファイル内の他のターゲットから、異なる実装で呼び出されます。docsbuild.xmlのターゲットは、builddocs.docsという名前で利用できます。これにより、新しい実装は古いターゲットを呼び出すことができ、その前後にタスクを呼び出すことで機能強化できます。

タスクのas属性を使用すると、オーバーライドされたターゲットの名前に、projectタグのname属性の代わりに、その値がプレフィックスとして使用されます。

特別なプロパティ

インポートされたファイルは、メインのビルドファイルに存在するように扱われます。これにより理解しやすくなりますが、インポートされたファイルがそのパスを基準としたファイルやリソースを参照することが不可能になります。このため、インポートされたファイルごとに、Antはインポートされたビルドファイルへのパスを含むプロパティを追加します。このパスにより、インポートされたビルドファイルはリソースを保持し、その位置を基準にして参照できます。

たとえば、builddocsという名前のdocsbuild.xmlファイルをインポートする場合、そのパスはメインビルドファイルのant.fileプロパティと同様に、ant.file.builddocsとして取得できます。

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>

ただし、このスニペットは、imported.xmlのbasedirがAntによって無視されるため、imported.propertiesをimporting.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>

パラメーター

属性 説明 必須
file インポートするファイル。これが相対ファイル名の場合、ファイル名はインポートファイルに対する相対パスで解決されます。注意：これは、相対ファイルがbasedirに対する相対パスで解決される他のほとんどのAntファイル属性とは異なります。 はい、またはネストされたリソースコレクション
任意 trueの場合、ファイルが存在しなくてもビルドを停止しないでください。 いいえ。デフォルトはfalseです。
as ターゲット名の先頭に追加するプレフィックスを指定します。 いいえ。デフォルトは、インポートされたファイルのprojectタグのname属性です。
prefixSeparator プレフィックスとターゲット名の間に使用する区切り文字を指定します。 いいえ。デフォルトは.です。

ネストされた要素として指定されたパラメーター

任意のリソースまたはリソースコレクション

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というjarファイル内のcommonディレクトリ内にあるtargets.xmlファイルからターゲットをインポートします。

<import>は<include>とどう違うのですか？

短いバージョン：ターゲットをオーバーライドする場合はimportを使用し、それ以外の場合はincludeを使用します。

importを使用すると、インポートされたターゲットは、最大2つの名前で使用できます。プレフィックスなしの「通常」の名前と、プレフィックス付きの名前（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という名前のターゲットはありません。