← Back to branch summary

~ubuntu-branches/ubuntu/trusty/netbeans/trusty

« back to all changes in this revision

Viewing changes to ant/project/src/org/netbeans/spi/project/support/ant/package.html

  • Committer: Bazaar Package Importer
  • Author(s): Marek Slama
  • Date: 2008-01-29 14:11:22 UTC
  • Revision ID: james.westby@ubuntu.com-20080129141122-fnzjbo11ntghxfu7
Tags: upstream-6.0.1
Import upstream version 6.0.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
ant/project/src/org/netbeans/spi/project/support/ant/package.html
 
1
<!--
 
2
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 
3
 
 
4
Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
 
5
 
 
6
 
 
7
The contents of this file are subject to the terms of either the GNU
 
8
General Public License Version 2 only ("GPL") or the Common
 
9
Development and Distribution License("CDDL") (collectively, the
 
10
"License"). You may not use this file except in compliance with the
 
11
License. You can obtain a copy of the License at
 
12
http://www.netbeans.org/cddl-gplv2.html
 
13
or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
 
14
specific language governing permissions and limitations under the
 
15
License.  When distributing the software, include this License Header
 
16
Notice in each file and include the License file at
 
17
nbbuild/licenses/CDDL-GPL-2-CP.  Sun designates this
 
18
particular file as subject to the "Classpath" exception as provided
 
19
by Sun in the GPL Version 2 section of the License file that
 
20
accompanied this code. If applicable, add the following below the
 
21
License Header, with the fields enclosed by brackets [] replaced by
 
22
your own identifying information:
 
23
"Portions Copyrighted [year] [name of copyright owner]"
 
24
 
 
25
Contributor(s):
 
26
 
 
27
The Original Software is NetBeans. The Initial Developer of the Original
 
28
Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
 
29
Microsystems, Inc. All Rights Reserved.
 
30
 
 
31
If you wish your version of this file to be governed by only the CDDL
 
32
or only the GPL Version 2, indicate your decision by adding
 
33
"[Contributor] elects to include this software in this distribution
 
34
under the [CDDL or GPL Version 2] license." If you do not indicate a
 
35
single choice of license, a recipient has the option to distribute
 
36
your version of this file under either the CDDL, the GPL Version 2 or
 
37
to extend the choice of license to its licensees as provided above.
 
38
However, if you add GPL Version 2 code and therefore, elected the GPL
 
39
Version 2 license, then the option applies only if the new code is
 
40
made subject to such option by the copyright holder.
 
41
-->
 
42
<html>
 
43
<body>
 
44
 
 
45
Principal package for implementing typical Ant-based projects.
 
46
 
 
47
<p>A typical project based on Ant follows a standard pattern of having a project
 
48
folder containing:</p>
 
49
 
 
50
<dl>
 
51
 
 
52
<dt><code>build.xml</code></dt>
 
53
 
 
54
<dd><p>A top-level editable build script.</p></dd>
 
55
 
 
56
<dt>various folders such as <code>src</code></dt>
 
57
 
 
58
<dd><p>Development files.</p></dd>
 
59
 
 
60
<dt>various folders such as <code>build</code></dt>
 
61
 
 
62
<dd><p>Build products. Not sharable in a VCS.</p></dd>
 
63
 
 
64
<dt><code>nbproject/build-impl.xml</code></dt>
 
65
 
 
66
<dd><p>Main logic for the build; regenerated from <code>nbproject/project.xml</code>
 
67
but sharable.</p></dd>
 
68
 
 
69
<dt><code>nbproject/project.xml</code></dt>
 
70
 
 
71
<dd><p>General project metadata, including a declaration of the type of project,
 
72
its name, some structural parameters relating to the build, a list of
 
73
subprojects, etc.</p></dd>
 
74
 
 
75
<dt><code>nbproject/project.properties</code></dt>
 
76
 
 
77
<dd><p>Sharable build configuration for the project.</p></dd>
 
78
 
 
79
<dt><code>nbproject/private/private.xml</code></dt>
 
80
 
 
81
<dd><p>Per-user (or per-checkout) project metadata, if any.</p></dd>
 
82
 
 
83
<dt><code>nbproject/private/private.properties</code></dt>
 
84
 
 
85
<dd><p>Per-user build configuration for the project.</p></dd>
 
86
 
 
87
<dt><code>nbproject/private/cache</code></dt>
 
88
 
 
89
<dd><p>Cache directory containing disposable files that might speed up various
 
90
operations.</p></dd>
 
91
 
 
92
</dl>
 
93
 
 
94
<p>Note that since Ant is not aware of the NetBeans Filesystems API, all these
 
95
files must be physically present on disk, not e.g. in an archive or remote
 
96
filesystem.</p>
 
97
 
 
98
<p>There may also be a file named <code>build.properties</code> located in the
 
99
NetBeans user directory which can supply additional definitions needed for a
 
100
build: e.g. the locations of Java platforms and libraries. A typical
 
101
<code>build-impl.xml</code> loads property definitions from this global
 
102
properties file as well as the project's
 
103
<code>nbproject/project.properties</code> and
 
104
<code>nbproject/private/private.properties</code>.</p>
 
105
 
 
106
<p>The basic operations commonly performed on an Ant-based project are:</p>
 
107
 
 
108
<ul>
 
109
 
 
110
<li><p>Creation from wizard, including <code>build.xml</code>.</p></li>
 
111
 
 
112
<li><p>Loading metadata from disk.</p></li>
 
113
 
 
114
<li><p>Modifying metadata and build properties in memory, and subsequently saving
 
115
to disk.</p></li>
 
116
 
 
117
<li><p>Regenerating <code>nbproject/build-impl.xml</code>, typically based on
 
118
transforming <code>nbproject/project.xml</code> with an XSLT stylesheet.</p></li>
 
119
 
 
120
<li><p>Running a build target of a well-known name in <code>build.xml</code>
 
121
using Ant.</p></li>
 
122
 
 
123
<li><p>Enumerating important build outputs ("artifacts").</p></li>
 
124
 
 
125
<li><p>Adding dependencies on "subprojects" by getting information about their artifacts
 
126
and storing references to them.</p></li>
 
127
 
 
128
<li><p>Interpreting values of Ant properties found on disk, to be used in
 
129
providing information to the IDE about various development files (e.g. when
 
130
implementing queries).</p></li>
 
131
 
 
132
</ul>
 
133
 
 
134
<p>A new category of Ant-based project can be registered in the system by
 
135
adding an implementation of
 
136
{@link org.netbeans.spi.project.support.ant.AntBasedProjectType} to the default
 
137
lookup. This will get an instance of
 
138
{@link org.netbeans.spi.project.support.ant.AntProjectHelper} for every project
 
139
it creates; the helper does a lot of the work required to interact with the file
 
140
structure outlined above.</p>
 
141
 
 
142
<p>To run Ant targets, use
 
143
<a href="@org-apache-tools-ant-module@/org/apache/tools/ant/module/api/support/ActionUtils.html"><code>ActionUtils</code></a>.</p>
 
144
 
 
145
<p>{@link org.netbeans.spi.project.support.ant.ReferenceHelper}s can also be
 
146
created by an Ant-based project and used to manage references to subprojects and
 
147
their artifacts in a high-level manner.</p>
 
148
 
 
149
<p>{@link org.netbeans.spi.project.support.ant.ProjectGenerator} provides the
 
150
easiest way to create a new Ant-based project on disk. Use
 
151
{@link org.netbeans.spi.project.support.ant.GeneratedFilesHelper} to make
 
152
build scripts and
 
153
{@link org.netbeans.spi.project.support.ant.ProjectXmlSavedHook} to be told when
 
154
to recreate them.</p>
 
155
 
 
156
<p>To allow third-party extensions to build scripts, use {@link org.netbeans.spi.project.ant.AntBuildExtenderImplementation} and
 
157
{@link org.netbeans.spi.project.support.ant.AntBuildExtenderFactory}.
 
158
</p>
 
159
 
 
160
<p>{@link org.netbeans.spi.project.support.ant.EditableProperties} is a
 
161
VCS-friendly alternative to {@link java.util.Properties}.
 
162
{@link org.netbeans.spi.project.support.ant.PropertyUtils} also provides various
 
163
methods for working with Ant concepts such as relative file paths, property
 
164
substitution, etc.</p>
 
165
  
 
166
</body>
 
167
</html>