mirror of
https://github.com/apache/ant.git
synced 2025-05-18 14:04:48 +00:00
132 lines
5.4 KiB
HTML
132 lines
5.4 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 Ant frontend: ProjectHelper</title>
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body>
|
||
|
|
<h1>The Ant frontend: ProjectHelper</h1>
|
||
|
|
|
||
|
|
<h2><a name="definition">What is a ProjectHelper?</a></h2>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The <code>ProjectHelper</code> in Ant is responsible to parse the build file
|
||
|
|
and create java instances representing the build workflow. It also declares which
|
||
|
|
kind of file it can parse, and which file name it expects as default input file.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
So in Ant there is a default <code>ProjectHelper</code>
|
||
|
|
(<code>org.apache.tools.ant.helper.ProjectHelper2</code>) which will parse the
|
||
|
|
usual build.xml files. And if no build file is specified on the command line, it
|
||
|
|
will expect to find a build.xml file.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The immediate benefit of a such abstraction it that it is possible to make Ant
|
||
|
|
understand other kind of descriptive language than XML. Some experiment have
|
||
|
|
been done around a pure java frontend, and a groovy one too (ask the dev mailing
|
||
|
|
list for further info about these).
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<h2><a name="repository">How is Ant is selecting the proper ProjectHelper</a></h2>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
Ant can now know about several implementations of <code>ProjectHelper</code>
|
||
|
|
and have to decide which to use for each build file.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>So Ant at startup will list the found implementations and will keep it
|
||
|
|
ordered as it finds them in an internal 'repository':
|
||
|
|
<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>
|
||
|
|
In case of error while trying to instanciate a <code>ProjectHelper</code>, Ant
|
||
|
|
will log an error but still won't stop. If you want further debugging
|
||
|
|
info about the <code>ProjectHelper</code> internal 'repository', use the system
|
||
|
|
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>
|
||
|
|
Then when Ant is expected to parse a file, it will ask the
|
||
|
|
<code>ProjectHelper</code> repository to found an implementation that will be
|
||
|
|
able to parse the input file. Actually it will just iterate on the ordered list
|
||
|
|
and the first implementation that returns <code>true</code> to
|
||
|
|
<code>supportsBuildFile(File buildFile)</code> will be selected.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
And when Ant is launching and there is no input file specified, it will search for
|
||
|
|
a default input file. It will iterate on the list of <code>ProjectHelper</code>
|
||
|
|
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>
|
||
|
|
Then there are some functions that will help you define what your helper is
|
||
|
|
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>
|
||
|
|
</ul>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
Now that you have your implementation ready, you have to declare it to Ant. Two
|
||
|
|
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>
|
||
|
|
</ul>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|