mirror of
https://github.com/apache/ant.git
synced 2025-05-19 06:24:47 +00:00
151 lines
6.3 KiB
HTML
151 lines
6.3 KiB
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
|
|
|
|
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.
|
|
-->
|
|
<html>
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Language" content="en-us">
|
|
<link rel="stylesheet" type="text/css" href="stylesheets/style.css">
|
|
<title>The Apache Ant frontend: ProjectHelper</title>
|
|
</head>
|
|
|
|
<body>
|
|
<h1>The Apache Ant frontend: ProjectHelper</h1>
|
|
|
|
<h2 id="definition">What is a ProjectHelper?</h2>
|
|
|
|
<p>
|
|
The <code>ProjectHelper</code> in Apache Ant is responsible for parsing the build file
|
|
and creating Java instances representing the build workflow. It also signals which
|
|
kind of file it can parse, and which file name it expects as default input file.
|
|
</p>
|
|
|
|
<p>
|
|
Ant's default <code>ProjectHelper</code>
|
|
(<code>org.apache.tools.ant.helper.ProjectHelper2</code>) parses the
|
|
usual <code>build.xml</code> files. And if no build file is specified on the command
|
|
line, it will expect to find a file named <code>build.xml</code>.
|
|
</p>
|
|
|
|
<p>
|
|
The immediate benefit of a such abstraction it that it is possible to make Ant
|
|
understand other kind of descriptive languages than XML. Some experiments have been
|
|
done around a pure Java frontend, and a Groovy one too (ask the dev mailing list for
|
|
further info about these).
|
|
</p>
|
|
|
|
<p>
|
|
<em>Since Ant 1.8.2</em>, the <a href="Tasks/import.html">import</a> task will also
|
|
try to use the proper helper to parse the imported file. So it is possible to write
|
|
different build files in different languages and have them import each other.
|
|
</p>
|
|
|
|
<h2 id="repository">How is Ant is selecting the proper ProjectHelper</h2>
|
|
|
|
<p>
|
|
Ant knows about several implementations of <code>ProjectHelper</code> and has to
|
|
decide which to use for each build file.
|
|
</p>
|
|
|
|
<p>
|
|
At startup Ant lists the all implementations found and keeps them in the same order
|
|
they've been found in an internal 'repository':
|
|
</p>
|
|
<ul>
|
|
<li>the first to be searched for is the one declared by the system property
|
|
<code>org.apache.tools.ant.ProjectHelper</code> (see
|
|
<a href="running.html#sysprops">Java System Properties</a>);</li>
|
|
<li>then it searches with its class loader for a <code>ProjectHelper</code>
|
|
service declarations in the <samp>META-INF</samp>: it searches in the classpath for a
|
|
file <samp>META-INF/services/org.apache.tools.ant.ProjectHelper</samp>.
|
|
This file will just contain the fully qualified name of the
|
|
implementation of <code>ProjectHelper</code> to instantiate;</li>
|
|
<li>it will also search with the system class loader for
|
|
<code>ProjectHelper</code> service declarations in the <samp>META-INF</samp>;</li>
|
|
<li>last but not least it will add its default <code>ProjectHelper</code>
|
|
that can parse classical <samp>build.xml</samp> files.</li>
|
|
</ul>
|
|
<p>
|
|
In case of an error while trying to instantiate a <code>ProjectHelper</code>, Ant will
|
|
log an error but won't stop. If you want further debugging info about
|
|
the <code>ProjectHelper</code> internal 'repository', use the <strong>system</strong>
|
|
property <code>ant.project-helper-repo.debug</code> and set it to <code>true</code>;
|
|
the full stack trace will then also be printed.
|
|
</p>
|
|
|
|
<p>
|
|
When Ant is expected to parse a file, it will ask the <code>ProjectHelper</code>
|
|
repository to find an implementation that will be able to parse the input
|
|
file. Actually it will just iterate over the ordered list and the first implementation
|
|
that returns <code>true</code> to <code>supportsBuildFile(File buildFile)</code> will
|
|
be selected.
|
|
</p>
|
|
|
|
<p>
|
|
When Ant is started and no input file has been specified, it will search for a default
|
|
input file. It will iterate over list of <code>ProjectHelper</code>s and will select
|
|
the first one that expects a default file that actually exist.
|
|
</p>
|
|
|
|
<h2 id="writing">Writing your own ProjectHelper</h2>
|
|
|
|
<p>
|
|
The class <code>org.apache.tools.ant.ProjectHelper</code> is the API expected to be
|
|
implemented. So write your own <code>ProjectHelper</code> by extending that abstract
|
|
class. You are then expected to implement at least the function <code>parse(Project
|
|
project, Object source)</code>. Note also that your implementation will be
|
|
instantiated by Ant, and it is expecting a default constructor with no arguments.
|
|
</p>
|
|
|
|
<p>
|
|
There are some functions that will help you define what your helper is capable of and
|
|
what is is expecting:
|
|
</p>
|
|
<ul>
|
|
<li><code>getDefaultBuildFile()</code>: defines which file name is expected if
|
|
none provided</li>
|
|
<li><code>supportsBuildFile(File buildFile)</code>: defines if your parser
|
|
can parse the input file</li>
|
|
<li><code>canParseAntlibDescriptor(URL url)</code>: whether your
|
|
implementation is capable of parsing a given Antlib
|
|
descriptor. The base class returns <code>false</code></li>
|
|
<li><code>parseAntlibDescriptor(Project containingProject, URL
|
|
source)</code>: invoked to actually parse the Antlib
|
|
descriptor if your implementation returned <code>true</code>
|
|
for the previous method.</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Now that you have your implementation ready, you have to declare it to Ant. Three
|
|
solutions here:
|
|
</p>
|
|
<ul>
|
|
<li>use the system property <code>org.apache.tools.ant.ProjectHelper</code>
|
|
(see also the <a href="running.html#sysprops">Java System Properties</a>);</li>
|
|
<li>use the service file in <samp>META-INF</samp>: in the jar you will build with your
|
|
implementation, add a file
|
|
<samp>META-INF/services/org.apache.tools.ant.ProjectHelper</samp>.
|
|
And then in this file just put the fully qualified name of your
|
|
implementation</li>
|
|
<li>use the <a href="Tasks/projecthelper.html">projecthelper</a> task (<em>since
|
|
Ant 1.8.2</em>) which will install dynamically a helper in the internal helper
|
|
'repository'. Then your helper can be used on the next call to the
|
|
<a href="Tasks/import.html">import</a> task.</li>
|
|
</ul>
|
|
|
|
</body>
|
|
</html>
|