インクルード

Apache Ant 1.8.0 以降

説明

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

注意 このタスクは、ProjectHelper の実装に大きく依存しており、実際には独自の作業は何も行いません。Ant がデフォルト以外の ProjectHelper を使用するように設定されている場合、このタスクは機能する場合と機能しない場合があります。

実行時、別の Ant ファイルを同じプロジェクトに読み込み、インクルードされたターゲットの name および depends リストを書き換えます。これは、Ant FAQ で説明されているエンティティインクルードとは異なります。ターゲット名には、インクルードされたプロジェクトの name または as 属性がプレフィックスとして付与され、ファイルがインクルードファイルに含まれているかのように表示されることはありません。

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

このタスクには、エンティティインクルードでは実現できない、さらに2つの機能的な側面があります。

• ターゲットの書き換え
• 特別なプロパティ

ターゲットの書き換え

インクルードされたファイルの任意のターゲットは、prefix.name に名前が変更されます。ここで、name は元のターゲットの名前であり、prefix は as 属性の値、またはインクルードされたファイルの project タグの name 属性のいずれかです。

すべてのインクルードされたターゲットの depends 属性は、すべてのターゲット名にもプレフィックスが付与されるように書き換えられます。これにより、インクルードされたファイルは自己完結型になります。

プレフィックスはネストすることに注意してください。したがって、ビルドファイルがプレフィックス q を持つファイルをインクルードし、インクルードされたファイルがプレフィックス b を持つ別のファイルをインクルードする場合、最後のビルドファイルのターゲットには a.b. がプレフィックスとして付与されます。

<import> もプレフィックスに寄与しますが、as 属性が指定されている場合に限ります。

特別なプロパティ

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

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

builddocs はファイル名ではなく、インクルードされた project タグに存在する name 属性であることに注意してください。

インクルードされたファイルに name 属性がない場合、ant.file.projectname プロパティは設定されません。

現在のビルドファイルのソースがファイルか URL かを知る必要がある場合は、プロパティ ant.file.type.projectname (上記の例と同じように ant.file.type.builddocs) を参照できます。このプロパティの値は file または url

インクルードされたファイルに対するファイルの解決

メインのビルドファイル including.xml が、ファイルシステムの任意の場所にあるビルドファイル included.xml をインクルードし、included.xml が included.properties からプロパティのセットを読み込むとします。

<!-- including.xml -->
<project name="including" basedir="." default="...">
  <include file="${path_to_included}/included.xml"/>
</project>

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

ただし、このスニペットは、included.properties を including.xml の basedir に対して解決します。included.xml の basedir は Ant によって無視されるためです。included.properties を正しく使用する方法は次のとおりです。

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

上記で説明したように、ant.file.included は、included というプロジェクトを定義するビルドスクリプトのパス (要するに、included.xml へのパス) を格納し、<dirname> はそのディレクトリを取得します。この手法により、included.xml をスタンドアロンファイルとして使用することもできます (他のプロジェクトにインクルードせずに)。

上記の説明は、ファイルからインクルードされたファイルにのみ機能し、URL からインクルードされたファイルには機能しません。URL からインクルードされたファイルの場合、インクルードされたファイルを基準としたリソースを使用するには、まずファイルではないリソースで動作できるタスクを使用する必要があります。相対リソースを作成するには、次のようなものを使用します。

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

パラメータ

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

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

指定されたリソースがインクルードされます。

例

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

親ディレクトリにある common-targets.xml ファイルからターゲットをインクルードします。

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

プロパティ deploy-platform で定義されたプロジェクトをインクルードします。

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

jar ファイル common.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 という名前のターゲットはありません。