<!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>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-updates
>
by-pkgid
>
8fad0817607a09309c3e5b12a09dac58
>
files
>
70
