A typical project based on Ant follows a standard pattern of having a project folder containing:
build.xml
A top-level editable build script.
src
Development files.
build
Build products. Not sharable in a VCS.
nbproject/build-impl.xml
Main logic for the build; regenerated from nbproject/project.xml
but sharable.
nbproject/project.xml
General project metadata, including a declaration of the type of project, its name, some structural parameters relating to the build, a list of subprojects, etc.
nbproject/project.properties
Sharable build configuration for the project.
nbproject/private/private.xml
Per-user (or per-checkout) project metadata, if any.
nbproject/private/private.properties
Per-user build configuration for the project.
nbproject/private/cache
Cache directory containing disposable files that might speed up various operations.
Note that since Ant is not aware of the NetBeans Filesystems API, all these files must be physically present on disk, not e.g. in an archive or remote filesystem.
There may also be a file named build.properties
located in the
NetBeans user directory which can supply additional definitions needed for a
build: e.g. the locations of Java platforms and libraries. A typical
build-impl.xml
loads property definitions from this global
properties file as well as the project's
nbproject/project.properties
and
nbproject/private/private.properties
.
The basic operations commonly performed on an Ant-based project are:
Creation from wizard, including build.xml
.
Loading metadata from disk.
Modifying metadata and build properties in memory, and subsequently saving to disk.
Regenerating nbproject/build-impl.xml
, typically based on
transforming nbproject/project.xml
with an XSLT stylesheet.
Running a build target of a well-known name in build.xml
using Ant.
Enumerating important build outputs ("artifacts").
Adding dependencies on "subprojects" by getting information about their artifacts and storing references to them.
Interpreting values of Ant properties found on disk, to be used in providing information to the IDE about various development files (e.g. when implementing queries).
A new category of Ant-based project can be registered in the system by adding an implementation of {@link org.netbeans.spi.project.support.ant.AntBasedProjectType} to the default lookup. This will get an instance of {@link org.netbeans.spi.project.support.ant.AntProjectHelper} for every project it creates; the helper does a lot of the work required to interact with the file structure outlined above.
To run Ant targets, use
ActionUtils
.
{@link org.netbeans.spi.project.support.ant.ReferenceHelper}s can also be created by an Ant-based project and used to manage references to subprojects and their artifacts in a high-level manner.
{@link org.netbeans.spi.project.support.ant.ProjectGenerator} provides the easiest way to create a new Ant-based project on disk. Use {@link org.netbeans.spi.project.support.ant.GeneratedFilesHelper} to make build scripts and {@link org.netbeans.spi.project.support.ant.ProjectXmlSavedHook} to be told when to recreate them.
To allow third-party extensions to build scripts, use {@link org.netbeans.spi.project.ant.AntBuildExtenderImplementation} and {@link org.netbeans.spi.project.support.ant.AntBuildExtenderFactory}.
{@link org.netbeans.spi.project.support.ant.EditableProperties} is a VCS-friendly alternative to {@link java.util.Properties}. {@link org.netbeans.spi.project.support.ant.PropertyUtils} also provides various methods for working with Ant concepts such as relative file paths, property substitution, etc.