mirror of
https://github.com/apache/ant.git
synced 2025-05-17 21:45:12 +00:00
3a4980e3c4
find . -type f -exec sed -i "s/http:\/\/www.apache.org\/licenses\/LICENSE-2.0/https:\/\/www.apache.org\/licenses\/LICENSE-2.0/" {} \;
289 lines
11 KiB
HTML
289 lines
11 KiB
HTML
<!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>Import Task</title>
|
|
</head>
|
|
<body>
|
|
<h2 id="import">Import</h2>
|
|
<h3>Description</h3>
|
|
<p>Imports another build file into the current project.</p>
|
|
|
|
<p>On execution it will select the proper ProjectHelper to parse the imported file, using the same
|
|
algorithm as the one executed at <a href="../projecthelper.html">startup</a>. The selected
|
|
ProjectHelper instance will then be responsible to actually parse the imported file.</p>
|
|
|
|
<p><strong>Note</strong> as seen above, this task heavily relies on the ProjectHelper
|
|
implementation and doesn't really perform any work of its own. If you have configured Apache
|
|
Ant to use a ProjectHelper other than Ant's default, this task may or may not work.</p>
|
|
|
|
<p>In the common use case where only Ant's default project helper is used, it basically works like
|
|
the <a href="https://ant.apache.org/faq.html#xml-entity-include" target="_top">Entity Includes
|
|
as explained in the Ant FAQ</a>, as if the imported file was contained in the importing file,
|
|
minus the top <code><project></code> tag.</p>
|
|
|
|
<p>The <code>import</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 overriding</li>
|
|
<li>special properties</li>
|
|
</ul>
|
|
<h4>Target overriding</h4>
|
|
|
|
<p>If a target in the main file is also present in at least one of the imported files, the one
|
|
from the main file takes precedence.</p>
|
|
|
|
<p>So if I import for example a <samp>docsbuild.xml</samp> file containing a project
|
|
named <q>builddocs</q> that contains a <q>docs</q> target, I can define a <q>docs</q> target in
|
|
my main buildfile and that is the one that will be called. This makes it easy to keep the same
|
|
target name, so that the overriding target is still called by any other targets—in either
|
|
the main or imported buildfile(s)—for which it is a dependency, with a different
|
|
implementation. The target from <samp>docsbuild.xml</samp> is made available by the
|
|
name <q>builddocs.docs</q>. This enables the new implementation to call the old target,
|
|
thus <em>enhancing</em> it with tasks called before or after it.</p>
|
|
|
|
<p>If you use the <var>as</var> attribute of the task, its value will be used to prefix the
|
|
overridden target's name instead of the <var>name</var> attribute of the <code>project</code>
|
|
tag.</p>
|
|
|
|
<h4>Special properties</h4>
|
|
|
|
<p>Imported 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 imported file, Ant adds a property that contains the
|
|
path to the imported buildfile. With this path, the imported buildfile can keep resources and be
|
|
able to reference them relative to its position.</p>
|
|
|
|
<p>So if I import 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 imported <code>project</code> tag.</p>
|
|
|
|
<p>If the imported file does not have a <var>name</var> attribute,
|
|
the <code>ant.file.<i>projectname</i></code> property will not be set.</p>
|
|
|
|
<p><em>Since Ant 1.8.0</em>, the task can also import resources from URLs or classpath resources
|
|
(which are URLs, really). 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 imported file</h4>
|
|
|
|
<p>Suppose your main build file called <samp>importing.xml</samp> imports a build
|
|
file <samp>imported.xml</samp>, located anywhere on the file system,
|
|
and <samp>imported.xml</samp> reads a set of properties
|
|
from <samp>imported.properties</samp>:</p>
|
|
|
|
<pre>
|
|
<!-- 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></pre>
|
|
|
|
<p>This snippet however will resolve <samp>imported.properties</samp> against
|
|
the <var>basedir</var> of <samp>importing.xml</samp>, because the <var>basedir</var>
|
|
of <samp>imported.xml</samp> is ignored by Ant. The right way to
|
|
use <samp>imported.properties</samp> is:</p>
|
|
|
|
<pre>
|
|
<!-- imported.xml -->
|
|
<project name="imported" basedir="." default="...">
|
|
<dirname property="imported.basedir" file="${ant.file.imported}"/>
|
|
<property file="${imported.basedir}/imported.properties"/>
|
|
</project></pre>
|
|
|
|
<p>As explained above <code>ant.file.imported</code> stores the path of the build script, that
|
|
defines the project called <q>imported</q>, (in short it stores the path
|
|
to <samp>imported.xml</samp>) and <a href="dirname.html"><code><dirname></code></a> takes
|
|
its directory. This technique also allows <samp>imported.xml</samp> to be used as a standalone
|
|
file (without being imported in other project).</p>
|
|
|
|
<p>The above description only works for imported files that actually are imported from files and
|
|
not from URLs. For files imported from URLs using resources relative to the imported 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.imported}"
|
|
relativePath="imported.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 import. If this is a relative file name, the file name will be resolved
|
|
relative to the <em>importing</em> file. <strong>Note</strong>: this is unlike most other
|
|
Ant file attributes, where relative files are resolved relative to <var>basedir</var>.</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>No; defaults to <var>name</var> attribute of the <code>project</code> tag of the imported
|
|
file</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><em>Since Ant 1.8.0</em></p>
|
|
<p>The specified resources will be imported.</p>
|
|
|
|
<h3>Examples</h3>
|
|
<pre><import file="../common-targets.xml"/></pre>
|
|
|
|
<p>Imports targets from the <samp>common-targets.xml</samp> file that is in a parent directory.</p>
|
|
|
|
<pre><import file="${deploy-platform}.xml"/></pre>
|
|
|
|
<p>Imports the project defined by the property <code>deploy-platform</code></p>
|
|
|
|
<pre>
|
|
<import>
|
|
<javaresource name="common/targets.xml">
|
|
<classpath location="common.jar"/>
|
|
</javaresource>
|
|
</import></pre>
|
|
|
|
<p>Imports 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 <import> different from <a href="include.html"><include></a>?</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>
|