diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Tasks/import.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/Tasks/import.html | 349 |
1 files changed, 0 insertions, 349 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/import.html b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/import.html deleted file mode 100644 index 4cf8de08..00000000 --- a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/import.html +++ /dev/null @@ -1,349 +0,0 @@ -<!-- - 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>Import Task</title> -</head> -<body> - <h2><a name="import">Import</a></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> - <b>Note</b> 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="http://ant.apache.org/faq.html#xml-entity-include">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 import 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 overriding</li> - <li>special properties</li> -</ul> - </p> -<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 <i>docsbuild.xml</i> file named <b>builddocs</b>, -that contains a "<b>docs</b>" target, I can redefine it 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 <i>docsbuild.xml</i> is -made available by the name "<b>builddocs</b><b>.docs</b>". -This enables the new implementation to call the old target, thus -<i>enhancing</i> it with tasks called before or after it.</p> - -<p>If you use the <i>as</i> attribute of the task, its value will be - used to prefix the overridden target's name instead of the name - attribute of the project 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 <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 imported project tag.</p> - <p> - If the imported file does not have a name attribute, the ant.file.projectname - property will not be set. - </p> - -<p>Since Ant 1.8.0 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 <b>ant.file.type.<em>projectname</em></b> (using the same - example as above <b>ant.file.type.builddocs</b>) which either have - the value "file" or "url".</p> - -<h4>Resolving files against the imported file</h4> - -<p>Suppose your main build file called <code>importing.xml</code> -imports a build file <code>imported.xml</code>, located anywhere on -the file system, and <code>imported.xml</code> reads a set of -properties from <code>imported.properties</code>:</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 <code>imported.properties</code> -against the basedir of <code>importing.xml</code>, because the basedir -of <code>imported.xml</code> is ignored by Ant. The right way to use -<code>imported.properties</code> 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 -<code>imported</code>, (in short it stores the path to -<code>imported.xml</code>) and <a -href="dirname.html"><code><dirname></code></a> takes its -directory. This technique also allows <code>imported.xml</code> 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 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 import. If this is a relative file name, the file name will be resolved - relative to the <i>importing</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 or a nested resource collection</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 - omitted, the name attribute of the project tag of the - imported file will be used. - </td> - <td valign="top" align="center">No</td> - </tr> - <tr> - <td valign="top"> - prefixSeparator - </td> - <td valign="top"> - Specifies the separator to be used between the prefix and the - target name. Defaults to ".". - </td> - <td valign="top" align="center">No</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>The specified resources will be imported. <em>Since Ant - 1.8.0</em></p> - -<h3>Examples</h3> -<pre> <import file="../common-targets.xml"/> -</pre> - -<p>Imports targets from the common-targets.xml file that is in a parent -directory.</p> - -<pre> <import file="${deploy-platform}.xml"/> -</pre> - -<p>Imports the project defined by the property deploy-platform</p> - -<pre> - <import> - <javaresource name="common/targets.xml"> - <classpath location="common.jar"/> - </javaresource> - </import> -</pre> - -<p>Imports targets from the targets.xml file that is inside the - directory common inside the jar file common.jar.</p> - -<h3>How is <import> different - from <a href="include.html"><include></a>?</h3> - -<p>The short version: Use import if you intend to override a target, - otherwise use include.</p> - -<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> - -<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> - -<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> - -<h4>Examples</h4> - -<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> -<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: - -<pre> -setUp: - -nested.echo: - [echo] prop has the value in importing - -test: - -</pre> - -<p>When using include 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: - -<pre> -nested.setUp: - -nested.echo: - [echo] prop has the value in nested - -test: - -</pre> - -<p>and there won't be any target named "echo" on the including build file.</p> - -</body> -</html> |