2009-09-27 10:59:48 +00:00
|
|
|
<!--
|
|
|
|
|
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 Ant frontend: ProjectHelper</title>
|
|
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
<h1>The Ant frontend: ProjectHelper</h1>
|
|
|
|
|
|
|
|
|
|
<h2><a name="definition">What is a ProjectHelper?</a></h2>
|
|
|
|
|
|
|
|
|
|
<p>
|
2009-09-28 15:16:49 +00:00
|
|
|
The <code>ProjectHelper</code> in Ant is responsible for parsing the build file
|
|
|
|
|
and creating java instances representing the build workflow. It also signals which
|
2009-09-27 10:59:48 +00:00
|
|
|
kind of file it can parse, and which file name it expects as default input file.
|
|
|
|
|
</p>
|
2009-09-28 15:16:49 +00:00
|
|
|
|
2009-09-27 10:59:48 +00:00
|
|
|
<p>
|
2009-09-28 15:16:49 +00:00
|
|
|
Ant' default <code>ProjectHelper</code>
|
|
|
|
|
(<code>org.apache.tools.ant.helper.ProjectHelper2</code>) parses the
|
2009-09-27 10:59:48 +00:00
|
|
|
usual build.xml files. And if no build file is specified on the command line, it
|
2009-09-28 15:16:49 +00:00
|
|
|
will expect to find a file named <code>build.xml</code>.
|
2009-09-27 10:59:48 +00:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
The immediate benefit of a such abstraction it that it is possible to make Ant
|
2009-09-28 15:16:49 +00:00
|
|
|
understand other kind of descriptive languages than XML. Some experiments have
|
2009-09-27 10:59:48 +00:00
|
|
|
been done around a pure java frontend, and a groovy one too (ask the dev mailing
|
|
|
|
|
list for further info about these).
|
|
|
|
|
</p>
|
|
|
|
|
|
2010-07-29 18:33:17 +00:00
|
|
|
<p>Since Ant 1.8.2, 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>
|
|
|
|
|
|
2009-09-27 10:59:48 +00:00
|
|
|
<h2><a name="repository">How is Ant is selecting the proper ProjectHelper</a></h2>
|
|
|
|
|
|
|
|
|
|
<p>
|
2009-09-28 15:16:49 +00:00
|
|
|
Ant knows about several implementations of <code>ProjectHelper</code>
|
|
|
|
|
and has to decide which to use for each build file.
|
2009-09-27 10:59:48 +00:00
|
|
|
</p>
|
|
|
|
|
|
2009-09-28 15:16:49 +00:00
|
|
|
<p>At startup Ant lists the all implementations found and keeps them
|
|
|
|
|
in the same order they've been found in an internal 'repository':
|
2009-09-27 10:59:48 +00:00
|
|
|
<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 META-INF: it searches in the classpath for a
|
|
|
|
|
file <code>META-INF/services/org.apache.tools.ant.ProjectHelper</code>.
|
|
|
|
|
This file will just contain the fully qualified name of the
|
|
|
|
|
implementation of <code>ProjectHelper</code> to instanciate;</li>
|
|
|
|
|
<li>it will also search with the system class loader for
|
|
|
|
|
<code>ProjectHelper</code> service declarations in the META-INF;</li>
|
|
|
|
|
<li>last but not least it will add its default <code>ProjectHelper</code>
|
|
|
|
|
that can parse classical build.xml files.</li>
|
|
|
|
|
</ul>
|
2009-09-28 15:16:49 +00:00
|
|
|
In case of an error while trying to instanciate 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 <b>system</b>
|
2009-09-27 10:59:48 +00:00
|
|
|
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>
|
2009-09-28 15:16:49 +00:00
|
|
|
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
|
2009-09-27 10:59:48 +00:00
|
|
|
and the first implementation that returns <code>true</code> to
|
|
|
|
|
<code>supportsBuildFile(File buildFile)</code> will be selected.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
2009-09-28 15:16:49 +00:00
|
|
|
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
|
2009-09-27 10:59:48 +00:00
|
|
|
and will select the first one that expects a default file that actually exist.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<h2><a name="writing">Writing your own ProjectHelper</a></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 instanciated by Ant, and it is expecting a default
|
|
|
|
|
constructor with no arguments.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
2009-09-28 15:16:49 +00:00
|
|
|
There are some functions that will help you define what your helper is
|
2009-09-27 10:59:48 +00:00
|
|
|
capable of and what is is expecting:
|
|
|
|
|
<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>
|
2009-09-28 15:19:42 +00:00
|
|
|
|
|
|
|
|
<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>
|
2009-09-27 10:59:48 +00:00
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
2010-07-29 18:33:17 +00:00
|
|
|
Now that you have your implementation ready, you have to declare it to Ant. Three
|
2009-09-27 10:59:48 +00:00
|
|
|
solutions here:
|
|
|
|
|
<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 META-INF: in the jar you will build with your
|
|
|
|
|
implementation, add a file
|
|
|
|
|
<code>META-INF/services/org.apache.tools.ant.ProjectHelper</code>.
|
|
|
|
|
And then in this file just put the fully qualified name of your
|
|
|
|
|
implementation</li>
|
2010-07-29 18:33:17 +00:00
|
|
|
<li>use the <a href="Tasks/projecthelper.html">projecthelper</a> task (since
|
|
|
|
|
Ant 1.8.2) which will install dynamically an 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>
|
2009-09-27 10:59:48 +00:00
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
|
|
|
|
|
