| <!DOCTYPE html> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| https://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <html lang="en"> |
| <head> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>Include Task</title> |
| </head> |
| <body> |
| <h2 id="include">Include</h2> |
| <p><em>Since Apache Ant 1.8.0</em></p> |
| <h3>Description</h3> |
| <p>Include another build file into the current project.</p> |
| |
| <p><strong>Note</strong> this task heavily relies on the ProjectHelper implementation and doesn't |
| really perform any work of its own. If you have configured Ant to use a ProjectHelper other |
| than Ant's default, this task may or may not work.</p> |
| |
| <p>On execution it will read another Ant file into the same project rewriting the included |
| target <var>name</var>s and <var>depends</var> lists. This is different |
| from <a href="https://ant.apache.org/faq.html#xml-entity-include" target="_top">Entity Includes |
| as explained in the Ant FAQ</a> insofar as the target names get prefixed by the included |
| project's <var>name</var> or <var>as</var> attribute and do not appear as if the file was |
| contained in the including file.</p> |
| |
| <p>The <code>include</code> task may only be used as a top-level task. This means that |
| it may not be used in a target.</p> |
| |
| <p>There are two further functional aspects that pertain to this task and that are not possible |
| with entity includes:</p> |
| <ul> |
| <li>target rewriting</li> |
| <li>special properties</li> |
| </ul> |
| <h4>Target rewriting</h4> |
| |
| <p>Any target in the included file will be renamed to <q>prefix.name</q> where <q>name</q> is the |
| original target's name and <q>prefix</q> is either the value of the <var>as</var> attribute or |
| the <var>name</var> attribute of the <code>project</code> tag of the included file.</p> |
| |
| <p>The <var>depends</var> attribute of all included targets is rewritten so that all target names |
| are prefixed as well. This makes the included file self-contained.</p> |
| |
| <p>Note that prefixes nest, so if a build file includes a file with prefix <q>q</q> and the |
| included file includes another file with prefix <q>b</q>, then the targets of that last build |
| file will be prefixed by <q>a.b.</q>.</p> |
| |
| <p><code><import></code> contribute to the prefix as well, but only if their <var>as</var> |
| attribute has been specified. |
| |
| <h4>Special properties</h4> |
| |
| <p>Included files are treated as they are present in the main buildfile. This makes it easy to |
| understand, but it makes it impossible for them to reference files and resources relative to |
| their path. Because of this, for every included file, Ant adds a property that contains the |
| path to the included buildfile. With this path, the included buildfile can keep resources and be |
| able to reference them relative to its position.</p> |
| |
| <p>So if I include for example a <samp>docsbuild.xml</samp> file named <q>builddocs</q>, I can get |
| its path as <code>ant.file.builddocs</code>, similarly to the <code>ant.file</code> property of |
| the main buildfile.</p> |
| |
| <p>Note that <q>builddocs</q> is not the filename, but the <var>name</var> attribute present in |
| the included <code>project</code> tag.</p> |
| <p>If the included file does not have a <var>name</var> attribute, |
| the <code>ant.file.<i>projectname</i></code> property will not be set.</p> |
| |
| <p>If you need to know whether the current build file's source has been a file or an URL you can |
| consult the property <code>ant.file.type.<i>projectname</i></code> (using the same example as |
| above <code>ant.file.type.builddocs</code>) which either have the value <q>file</q> |
| or <q>url</q>.</p> |
| |
| <h4>Resolving files against the included file</h4> |
| |
| <p>Suppose your main build file called <samp>including.xml</samp> includes a build |
| file <samp>included.xml</samp>, located anywhere on the file system, |
| and <samp>included.xml</samp> reads a set of properties |
| from <samp>included.properties</samp>:</p> |
| |
| <pre> |
| <!-- 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></pre> |
| |
| <p>This snippet however will resolve <samp>included.properties</samp> against |
| the <var>basedir</var> of <samp>including.xml</samp>, because the <var>basedir</var> |
| of <samp>included.xml</samp> is ignored by Ant. The right way to |
| use <samp>included.properties</samp> is:</p> |
| |
| <pre> |
| <!-- included.xml --> |
| <project name="included" basedir="." default="..."> |
| <dirname property="included.basedir" file="${ant.file.included}"/> |
| <property file="${included.basedir}/included.properties"/> |
| </project></pre> |
| |
| <p>As explained above <code>ant.file.included</code> stores the path of the build script, that |
| defines the project called <q>included</q>, (in short it stores the path |
| to <samp>included.xml</samp>) and <a href="dirname.html"><code><dirname></code></a> takes |
| its directory. This technique also allows <samp>included.xml</samp> to be used as a standalone |
| file (without being included in other project).</p> |
| |
| <p>The above description only works for included files that actually are included from files and |
| not from URLs. For files included from URLs using resources relative to the included file |
| requires you to use tasks that can work on non-file resources in the first place. To create a |
| relative resource you'd use something like:</p> |
| |
| <pre> |
| <loadproperties> |
| <url baseUrl="${ant.file.included}" |
| relativePath="included.properties"/> |
| </loadproperties></pre> |
| |
| <h3>Parameters</h3> |
| <table class="attr"> |
| <tbody> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>file</td> |
| <td>The file to include. If this is a relative file name, the file name will be resolved |
| relative to the <em>including</em> file. <strong>Note</strong>, this is unlike most other |
| ant file attributes, where relative files are resolved relative to ${basedir}.</td> |
| <td>Yes or a nested resource collection</td> |
| </tr> |
| <tr> |
| <td>optional</td> |
| <td>If <q>true</q>, do not stop the build if the file does not exist.</td> |
| <td>No; default is <q>false</q></td> |
| </tr> |
| <tr> |
| <td>as</td> |
| <td>Specifies the prefix prepended to the target names.</td> |
| <td>Yes, if the included file's <code>project</code> tag doesn't specify a <var>name</var> |
| attribute (which is otherwise taken as default)</td> |
| </tr> |
| <tr> |
| <td>prefixSeparator</td> |
| <td>Specifies the separator to be used between the prefix and the target name.</td> |
| <td>No; defaults to <q>.</q></td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <h3>Parameters specified as nested elements</h3> |
| |
| <h4>any <a href="../Types/resources.html">resource</a> or resource collection</h4> |
| |
| <p>The specified resources will be included.</p> |
| |
| <h3>Examples</h3> |
| <pre><include file="../common-targets.xml"/></pre> |
| |
| <p>Includes targets from the <samp>common-targets.xml</samp> file that is in a parent directory.</p> |
| |
| <pre><include file="${deploy-platform}.xml"/></pre> |
| |
| <p>Includes the project defined by the property deploy-platform</p> |
| |
| <pre> |
| <include> |
| <javaresource name="common/targets.xml"> |
| <classpath location="common.jar"/> |
| </javaresource> |
| </include></pre> |
| |
| <p>Includes targets from the <samp>targets.xml</samp> file that is inside the |
| directory <samp>common</samp> inside the jar file <samp>common.jar</samp>.</p> |
| |
| <h3>How is <a href="import.html"><import></a> different from <include>?</h3> |
| |
| <p>The short version: Use <code>import</code> if you intend to override a target, otherwise |
| use <code>include</code>.</p> |
| |
| <p>When <code>import</code> is used, the imported targets are available by up to two names: their |
| "normal" name without any prefix and potentially with a prefixed name (the value of |
| the <var>as</var> attribute or the imported project's <var>name</var> attribute, if any).</p> |
| |
| <p>When <code>include</code> is used, the included targets are only available in the prefixed form.</p> |
| |
| <p>When <code>import</code> is used, the imported target's <var>depends</var> attribute remains |
| unchanged, i.e. it uses "normal" names and allows you to override targets in the dependency |
| list.</p> |
| |
| <p>When <code>include</code> is used, the included targets cannot be overridden and |
| their <var>depends</var> attributes are rewritten so that prefixed names are used. This allows |
| writers of the included file to control which target is invoked as part of the dependencies.</p> |
| |
| <p>It is possible to <code>include</code> the same file more than once by using different prefixes; |
| it is not possible to <code>import</code> the same file more than once.</p> |
| |
| <h4>Examples</h4> |
| |
| <p><samp>nested.xml</samp> shall be:</p> |
| |
| <pre> |
| <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></pre> |
| |
| <p>When using <code>import</code> like in</p> |
| |
| <pre> |
| <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></pre> |
| |
| <p>Running the build file will emit:</p> |
| |
| <pre class="output"> |
| setUp: |
| |
| nested.echo: |
| [echo] prop has the value in importing |
| |
| test: |
| |
| </pre> |
| |
| <p>When using <code>include</code> like in</p> |
| |
| <pre> |
| <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></pre> |
| |
| <p>Running the target build file will emit:</p> |
| |
| <pre class="output"> |
| nested.setUp: |
| |
| nested.echo: |
| [echo] prop has the value in nested |
| |
| test: |
| |
| </pre> |
| |
| <p>and there won't be any target named <q>echo</q> on the including build file.</p> |
| |
| </body> |
| </html> |