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.
|
|
|
|
|
-->
|
|
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
|
<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>
|
|
|
|
|
<h2><a name="include">Include</a></h2>
|
|
|
|
|
<h3>Description</h3>
|
|
|
|
|
<p>
|
|
|
|
|
Include another build file into the current project.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
<b>Note</b> 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 names and depends lists. This is
|
|
|
|
|
different
|
|
|
|
|
from <a href="http://ant.apache.org/faq.html#xml-entity-include">Entity
|
|
|
|
|
Includes as explained in the Ant FAQ</a> in so far as the target
|
|
|
|
|
names get prefixed by the included project's name or the as
|
|
|
|
|
attribute and do not appear as if the file was contained in the
|
|
|
|
|
including file.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The include 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:
|
|
|
|
|
<ul>
|
|
|
|
|
<li>target rewriting</li>
|
|
|
|
|
<li>special properties</li>
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
<h4>Target rewriting</h4>
|
|
|
|
|
|
|
|
|
|
<p>Any target in the included file will be renamed
|
|
|
|
|
to <i>prefix.name</i> where <i>name</i> is the original target's
|
|
|
|
|
name and <i>prefix</i> is either the value of the <i>as</i>
|
|
|
|
|
attribute or the <i>name</i> attribute of the <i>project</i> tag of
|
|
|
|
|
the included file.</p>
|
|
|
|
|
|
|
|
|
|
<p>The depends attribute of all included targets is rewritten so that
|
|
|
|
|
all target names are prefixed as well. This makes the included file
|
|
|
|
|
self-contained.</p>
|
|
|
|
|
|
|
|
|
|
<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 <i>docsbuild.xml</i> file named <b>builddocs</b>,
|
|
|
|
|
I can get its path as <b>ant.file.builddocs</b>, similarly to the <b>ant.file</b>
|
|
|
|
|
property of the main buildfile.</p>
|
|
|
|
|
|
|
|
|
|
<p>Note that "builddocs" is not the filename, but the name attribute
|
|
|
|
|
present in the included project tag.</p>
|
|
|
|
|
<p>
|
|
|
|
|
If the included file does not have a name attribute, the ant.file.projectname
|
|
|
|
|
property will not be set.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<h4>Resolving files against the included file</h4>
|
|
|
|
|
|
|
|
|
|
<p>Suppose your main build file called <code>including.xml</code>
|
|
|
|
|
includes a build file <code>included.xml</code>, located anywhere on
|
|
|
|
|
the file system, and <code>included.xml</code> reads a set of
|
|
|
|
|
properties from <code>included.properties</code>:</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 <code>included.properties</code>
|
|
|
|
|
against the basedir of <code>including.xml</code>, because the basedir
|
|
|
|
|
of <code>included.xml</code> is ignored by Ant. The right way to use
|
|
|
|
|
<code>included.properties</code> 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
|
|
|
|
|
<code>included</code>, (in short it stores the path to
|
|
|
|
|
<code>included.xml</code>) and <a
|
|
|
|
|
href="dirname.html"><code><dirname></code></a> takes its
|
|
|
|
|
directory. This technique also allows <code>included.xml</code> to be
|
|
|
|
|
used as a standalone file (without being included in other
|
|
|
|
|
project).</p>
|
|
|
|
|
|
|
|
|
|
<h3>Parameters</h3>
|
|
|
|
|
<table border="1" cellpadding="2" cellspacing="0">
|
|
|
|
|
<tbody>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top"><b>Attribute</b></td>
|
|
|
|
|
<td valign="top"><b>Description</b></td>
|
|
|
|
|
<td align="center" valign="top"><b>Required</b></td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">
|
|
|
|
|
file
|
|
|
|
|
</td>
|
|
|
|
|
<td valign="top">
|
|
|
|
|
The file to include. If this is a relative file name, the file name will be resolved
|
|
|
|
|
relative to the <i>including</i> file. <b>Note</b>, this is unlike most other
|
|
|
|
|
ant file attributes, where relative files are resolved relative to ${basedir}.
|
|
|
|
|
</td>
|
|
|
|
|
<td valign="top" align="center">Yes</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">
|
|
|
|
|
optional
|
|
|
|
|
</td>
|
|
|
|
|
<td valign="top">
|
|
|
|
|
If true, do not stop the build if the file does not exist,
|
|
|
|
|
default is false.
|
|
|
|
|
</td>
|
|
|
|
|
<td valign="top" align="center">No</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">
|
|
|
|
|
as
|
|
|
|
|
</td>
|
|
|
|
|
<td valign="top">
|
|
|
|
|
Specifies the prefix prepended to the target names. If
|
|
|
|
|
ommitted, the name attribute of the project tag of the
|
|
|
|
|
imported file will be used.
|
|
|
|
|
</td>
|
|
|
|
|
<td valign="top" align="center">Yes, if the included file's
|
|
|
|
|
project tag doesn't specify a name attribute.</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</tbody>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<h3>Examples</h3>
|
|
|
|
|
<pre> <include file="../common-targets.xml"/>
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
<p>Includes targets from the common-targets.xml 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>
|
|
|
|
|
|
|
|
|
|
<h3>How is <a href="import.html"><import></a> different
|
|
|
|
|
from <include>?</h3>
|
|
|
|
|
|
2008-11-12 12:17:59 +00:00
|
|
|
<p>The short version: Use import if you intend to override a target,
|
|
|
|
|
otherwise use include.</p>
|
|
|
|
|
|
2008-11-11 11:03:45 +00:00
|
|
|
<p>When using import 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 as attribute or the imported
|
|
|
|
|
project's name attribute, if any).</p>
|
|
|
|
|
|
|
|
|
|
<p>When using include the included targets are only available in the
|
|
|
|
|
prefixed form.</p>
|
|
|
|
|
|
|
|
|
|
<p>When using import, the imported target's depends attribute
|
|
|
|
|
remains unchanged, i.e. it uses "normal" names and allows you to
|
|
|
|
|
override targets in the dependency list.</p>
|
|
|
|
|
|
2008-11-12 12:17:59 +00:00
|
|
|
<p>When using include, the included targets cannot be overridden and
|
|
|
|
|
their depends 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
|
|
|
|
|
|
|
|
<p>It is possible to include the same file more than once by using
|
|
|
|
|
different prefixes, it is not possible to import the same file more
|
|
|
|
|
than once.</p>
|
|
|
|
|
|
2008-11-12 12:17:59 +00:00
|
|
|
<h4>Examples</h4>
|
2008-11-11 11:03:45 +00:00
|
|
|
|
|
|
|
|
<p><i>nested.xml</i> 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 import like in</p>
|
|
|
|
|
|
|
|
|
|
<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"/>
|
2008-11-11 11:03:45 +00:00
|
|
|
</project>
|
|
|
|
|
</pre>
|
|
|
|
|
|
2008-11-12 12:17:59 +00:00
|
|
|
<p>Running the build file will emit:
|
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>
|
|
|
|
|
|
|
|
|
|
<p>When using include like in</p>
|
|
|
|
|
|
|
|
|
|
<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"/>
|
2008-11-11 11:03:45 +00:00
|
|
|
</project>
|
|
|
|
|
</pre>
|
|
|
|
|
|
2008-11-12 12:17:59 +00:00
|
|
|
<p>Running the target build file will emit:
|
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>
|
|
|
|
|
|
|
|
|
|
<p>and there won't be any target named "echo" on the including build file.</p>
|
|
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
