2008-11-11 11:03:45 +00:00
|
|
|
<!--
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
http://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>
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="Content-Language" content="en-us">
|
|
|
|
|
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
|
|
|
|
<title>Include Task</title>
|
|
|
|
|
</head>
|
|
|
|
|
<body>
|
2018-01-22 23:52:21 +01:00
|
|
|
<h2 id="include">Include</h2>
|
2018-03-04 15:17:41 +01:00
|
|
|
<p><em>Since Apache Ant 1.8.0</em></p>
|
2008-11-11 11:03:45 +00:00
|
|
|
<h3>Description</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>Include another build file into the current project.</p>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<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
|
2018-03-08 07:43:53 +01:00
|
|
|
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
|
2018-02-28 07:58:59 +01:00
|
|
|
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>
|
2018-03-04 15:17:41 +01:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<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>
|
2018-03-04 15:17:41 +01:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<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.
|
|
|
|
|
|
2018-03-05 21:01:42 +01:00
|
|
|
<h4>Special properties</h4>
|
2018-02-28 07:58:59 +01:00
|
|
|
|
|
|
|
|
<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 -->
|
2008-11-11 11:03:45 +00:00
|
|
|
<project name="including" basedir="." default="...">
|
2018-02-08 22:56:19 +01:00
|
|
|
<include file="${path_to_included}/included.xml"/>
|
2008-11-11 11:03:45 +00:00
|
|
|
</project>
|
|
|
|
|
|
|
|
|
|
<!-- included.xml -->
|
|
|
|
|
<project name="included" basedir="." default="...">
|
2018-02-08 22:56:19 +01:00
|
|
|
<property file="included.properties"/>
|
2018-02-28 07:58:59 +01:00
|
|
|
</project></pre>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<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>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre>
|
2008-11-11 11:03:45 +00:00
|
|
|
<!-- included.xml -->
|
|
|
|
|
<project name="included" basedir="." default="...">
|
2018-02-08 22:56:19 +01:00
|
|
|
<dirname property="included.basedir" file="${ant.file.included}"/>
|
|
|
|
|
<property file="${included.basedir}/included.properties"/>
|
2018-02-28 07:58:59 +01:00
|
|
|
</project></pre>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<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>
|
2009-11-15 07:25:03 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<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>
|
2009-11-15 07:25:03 +00:00
|
|
|
|
2008-11-11 11:03:45 +00:00
|
|
|
<h3>Parameters</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2008-11-11 11:03:45 +00:00
|
|
|
<tbody>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<th>Attribute</th>
|
|
|
|
|
<th>Description</th>
|
|
|
|
|
<th>Required</th>
|
2008-11-11 11:03:45 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<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>
|
2008-11-11 11:03:45 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<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>
|
2008-11-11 11:03:45 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<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>
|
2008-11-11 11:03:45 +00:00
|
|
|
</tr>
|
2008-11-12 13:53:57 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<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>
|
2008-11-12 13:53:57 +00:00
|
|
|
</tr>
|
2008-11-11 11:03:45 +00:00
|
|
|
</tbody>
|
|
|
|
|
</table>
|
|
|
|
|
|
2009-11-15 07:25:03 +00:00
|
|
|
<h3>Parameters specified as nested elements</h3>
|
|
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<h4>any <a href="../Types/resources.html">resource</a> or resource collection</h4>
|
2009-11-15 07:25:03 +00:00
|
|
|
|
|
|
|
|
<p>The specified resources will be included.</p>
|
|
|
|
|
|
2008-11-11 11:03:45 +00:00
|
|
|
<h3>Examples</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre><include file="../common-targets.xml"/></pre>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>Includes targets from the <samp>common-targets.xml</samp> file that is in a parent directory.</p>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre><include file="${deploy-platform}.xml"/></pre>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
|
|
|
|
<p>Includes the project defined by the property deploy-platform</p>
|
|
|
|
|
|
2009-11-15 07:25:03 +00:00
|
|
|
<pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
<include>
|
|
|
|
|
<javaresource name="common/targets.xml">
|
|
|
|
|
<classpath location="common.jar"/>
|
|
|
|
|
</javaresource>
|
|
|
|
|
</include></pre>
|
2009-11-15 07:25:03 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<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>
|
2009-11-15 07:25:03 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<h3>How is <a href="import.html"><import></a> different from <include>?</h3>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>The short version: Use <code>import</code> if you intend to override a target, otherwise
|
|
|
|
|
use <code>include</code>.</p>
|
2008-11-12 12:17:59 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>When using <code>import</code> 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>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>When using <code>include</code> the included targets are only available in the prefixed form.</p>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>When using <code>import</code>, 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>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>When using <code>include</code>, 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>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<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>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2008-11-12 12:17:59 +00:00
|
|
|
<h4>Examples</h4>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><samp>nested.xml</samp> shall be:</p>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
|
|
|
|
<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>
|
2018-02-28 07:58:59 +01:00
|
|
|
</project></pre>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>When using <code>import</code> like in</p>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
|
|
|
|
<pre>
|
2008-11-12 12:17:59 +00:00
|
|
|
<project default="test">
|
2008-11-11 11:03:45 +00:00
|
|
|
<target name="setUp">
|
|
|
|
|
<property name="prop" value="in importing"/>
|
|
|
|
|
</target>
|
|
|
|
|
|
|
|
|
|
<import file="nested.xml" as="nested"/>
|
2008-11-12 12:17:59 +00:00
|
|
|
|
|
|
|
|
<target name="test" depends="nested.echo"/>
|
2018-02-28 07:58:59 +01:00
|
|
|
</project></pre>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>Running the build file will emit:</p>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
setUp:
|
|
|
|
|
|
|
|
|
|
nested.echo:
|
|
|
|
|
[echo] prop has the value in importing
|
2008-11-12 12:17:59 +00:00
|
|
|
|
|
|
|
|
test:
|
|
|
|
|
|
2008-11-11 11:03:45 +00:00
|
|
|
</pre>
|
|
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>When using <code>include</code> like in</p>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
|
|
|
|
<pre>
|
2008-11-12 12:17:59 +00:00
|
|
|
<project default="test">
|
2008-11-11 11:03:45 +00:00
|
|
|
<target name="setUp">
|
|
|
|
|
<property name="prop" value="in importing"/>
|
|
|
|
|
</target>
|
|
|
|
|
|
|
|
|
|
<include file="nested.xml" as="nested"/>
|
2008-11-12 12:17:59 +00:00
|
|
|
|
|
|
|
|
<target name="test" depends="nested.echo"/>
|
2018-02-28 07:58:59 +01:00
|
|
|
</project></pre>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>Running the target build file will emit:</p>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
nested.setUp:
|
|
|
|
|
|
|
|
|
|
nested.echo:
|
|
|
|
|
[echo] prop has the value in nested
|
2008-11-12 12:17:59 +00:00
|
|
|
|
|
|
|
|
test:
|
|
|
|
|
|
2008-11-11 11:03:45 +00:00
|
|
|
</pre>
|
|
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>and there won't be any target named <q>echo</q> on the including build file.</p>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
