| <!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> |