diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Tasks/include.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/Tasks/include.html | 344 |
1 files changed, 0 insertions, 344 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/include.html b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/include.html deleted file mode 100644 index e2109235..00000000 --- a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/include.html +++ /dev/null @@ -1,344 +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>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><em>since Apache Ant 1.8.0</em></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> insofar 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> - -<p>Note that prefixes nest, so if a build file includes a file with - prefix "a" and the included file includes another file with prefix - "b", then the targets of that last build file will be prefixed by - "a.b.".</p> - -<p><code><import></code> contribute to the prefix as well, but - only if their <code>as</code> attribute has been specified. - -<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> - -<p>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 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> - -<p>The above description only works for included files that actually - are included from files and not from URLs. For files included from - URLs using resources relative to the included 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.included}" - relativePath="included.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 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 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 - included 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> - <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 included.</p> - -<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> - -<pre> - <include> - <javaresource name="common/targets.xml"> - <classpath location="common.jar"/> - </javaresource> - </include> -</pre> - -<p>Includes targets from the targets.xml file that is inside the - directory common inside the jar file common.jar.</p> - -<h3>How is <a href="import.html"><import></a> different - from <include>?</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> |