jMonkeyEngine/sdk/harness/README

INTRODUCTION
------------

This build harness permits modules outside of the netbeans.org CVS tree to be
built against a NetBeans-based application: the NB platform, the NB IDE, or any
derivative product. The semantics of configuration files is synchronized with
the NBM project type module, so that you can open any module in the NB IDE and
work with it naturally: build and test it using Ant, use Java code completion,
and so on.

Questions and comments should go to: [email protected]

BASIC FILE LAYOUT
-----------------

Within the netbeans.org CVS tree, modules are detected as projects of the "NBM"
(NetBeans module) type. The project directory may be top-level (e.g. "beans"),
second-level (e.g. "ant/project"), or third-level (e.g.
"objectbrowser/navigator/javanavigation"). The project.xml for the project must
specify

    <type>org.netbeans.modules.apisupport.project</type>

to indicate that it is an NBM project, and the configuration must be

    <data xmlns="http://www.netbeans.org/ns/nb-module-project/3">

Note that this schema is a change from the /2 schema used in NetBeans 5.0.
(/2 is still supported for compatibility.)
NetBeans 4.0 and 4.1 use schema /1 which is no longer supported.

Outside of the netbeans.org CVS tree, modules can take two forms. They may be
marked with

    <standalone/>

in which case they can build into a platform binary but not refer to any other
source modules. Or they may be marked with

    <suite-component/>

in which case they are contained within a module suite. The suite enumerates
modules it contains, and each module points back to the suite that contains it.

The meaning of the project.xml elements, as well as property names in
project.properties and other files, will be discussed later.

The project directory should contain "manifest.mf" (more on this later),
"build.xml" (more later), a directory "src" with the main package root of the
module's classes, optionally "test/unit/src" with unit tests, and perhaps some
other files.

If there is a subdirectory "javahelp" it is used to keep JavaHelp documentation,
which will be built automatically.

If there is a file "module-auto-deps.xml" it will automatically be used to
upgrade modules depending on you to new dependencies, as described in the
Modules API.

STANDALONE MODULES: CONFIGURATION FILES
---------------------------------------

Standalone modules may keep configuration in several properties files, in the
following order of loading:

${basedir}/nbproject/private/platform-private.properties
${basedir}/nbproject/platform.properties
${user.properties.file}
[definition of 'harness.dir' and 'netbeans.dest.dir' or 'cluster.path' based on value of ${nbplatform.active}]
${basedir}/nbproject/private/private.properties
${basedir}/nbproject/project.properties	

Projects generated by NB 6.5 and earlier:
-----------------------------------------
The properties 'harness.dir' and 'netbeans.dest.dir' must be defined by the
project. Usually this is accomplished by defining the property
'nbplatform.active' in platform.properties, and ${user.properties.file}
(normally build.properties in the user directory, usually defined in
platform-private.properties) can define properties like
'nbplatform.NAME.netbeans.dest.dir' (this would be used for 'netbeans.dest.dir'
in case ${nbplatform.active} had the value 'NAME').

Projects generated by NB 6.7 and later (for 6.7 platform):
----------------------------------------------------------
6.7 and newer projects may be distinguished by the presence of 'cluster.path' 
property in nbproject/platform.properties file or simply by the fact that an 
attempt to build a standalone module without it results in error: 

  'You must specify path to 'platform' cluster in ${cluster.path} property.'
 
In such case property 'cluster.path' must be defined by the project. It must 
contain classpath-like list of absolute or relative paths to individual clusters 
against which will be the module build. "Bare", i.e. not numbered cluster names 
can be used, which simplifies later transitions to newer version of the 
platform. Content of 'cluster.path' can also reference other properties defined 
in the project, properties file generated by the IDE e.g uses property 
'nbplatform.active.dir' pointing to root folder of specified active platform. 
'nbplatform.active' is used like before. Properties 'netbeans.dest.dir', 
'enabled.clusters' and 'disabled.clusters' *must not* be defined in the 
projects. They would be ignored anyway so there is a dedicated check that 
project is not trying to setup something that would not work anyway. 

For more info on uses of 'cluster.path' property and setting it in IDE, see
http://wiki.netbeans.org/DevFaqHowToReuseModules.

MODULE SUITES: CONFIGURATION FILES
----------------------------------

Modules in a suite have a slightly more complicated list of properties files in
which they may keep configuration:

${basedir}/nbproject/private/suite-private.properties
${basedir}/nbproject/suite.properties
${suite.dir}/nbproject/private/platform-private.properties
${suite.dir}/nbproject/platform.properties
${user.properties.file}
[definition of 'harness.dir' and 'netbeans.dest.dir' or 'cluster.path' based on value of ${nbplatform.active}]
${basedir}/nbproject/private/private.properties
${basedir}/nbproject/project.properties

'suite.dir' is normally defined in suite-private.properties (or suite.properties
in case it is a relative path). platform-private.properties and
platform.properties are then used to define the NB platform in the same way as
for standalone modules.

The suite itself (the project located in ${suite.dir}) can load properties from:

${basedir}/nbproject/private/platform-private.properties
${basedir}/nbproject/platform.properties
${user.properties.file}
[definition of 'harness.dir' and 'netbeans.dest.dir' or 'cluster.path' based on value of ${nbplatform.active}]
${basedir}/nbproject/private/private.properties
${basedir}/nbproject/project.properties

It must define a property 'modules' enumerating modules it contains (in path
format, with each entry being a module project directory). This is usually done
in project.properties, perhaps also with private.properties to help with
absolute paths.

USING A RELATIVE PATH FOR THE PLATFORM WITH A MODULE SUITE
----------------------------------------------------------

Though not directly supported by the GUI, it is possible to set up a module
suite in such a way that the path to the NetBeans platform is given as relative,
and sharable in VCS. This may be helpfully especially for multi-developer teams
who frequently develop against new NetBeans builds (or build NetBeans from CVS
sources). You need to:

1. Make sure that each module's suite.properties specifies 'suite.dir' as
relative to its base directory, not as a bare relative path, e.g.

    suite.dir=${basedir}/..

2. Edit the suite's platform.properties to give a fallback value for 'suite.dir'
(so the suite's own master build script can work), and define *both*
netbeans.dest.dir and harness.dir in terms of the suite directory, e.g.:

    suite.dir=${basedir}
	
	# for platform 6.7 and later, use:
	# 'platform.base' is only a helper property, it has no meaning in harness
	platform.base=${suite.dir}/../nb_sources/nbbuild/netbeans
	cluster.path=${platform.base}/platform:<other clusters you need>
	harness.dir=${platform.base}/harness
	
	# for platform 6.5 and earlier, use:
    netbeans.dest.dir=${suite.dir}/../nb_sources/nbbuild/netbeans
    harness.dir=${netbeans.dest.dir}/harness

platform.properties need not define 'nbplatform.active' in this case.

Relative-path source and Javadoc associations for the platform is not yet
supported in this scenario (#70876). Each developer with a checkout of the suite
may need to configure a platform (with an arbitrary name) in the NetBeans
Platform Manager dialog with a binary location matching the value you gave for
${netbeans.dest.dir}, and with source and/or Javadoc associations of their
choice. However, as a convenience, special associations may be predefined in the
IDE in the special case that the destination directory is the subsubdirectory
"nbbuild/netbeans" of a netbeans.org CVS checkout (i.e. if you build NetBeans
from sources and then build your suite against that).

"CHAINING" SUITES (INTER-SUITE DEPENDENCIES HOWTO)
--------------------------------------------------

As of platform version 6.7, suite-chaining as described here is superseded by
using 'cluster.path' property, see previous chapters and developer FAQ
http://wiki.netbeans.org/DevFaqHowToReuseModules. For platform versions 6.5
and older, read on.

Suppose you have one platform P1, say the bare NetBeans Platform. Then you have
a module suite S1 with modules M1a...M1z which uses P1. Now it may happen that
you want another suite S2 with modules M2a...M2z to depend on S1 as well as P1.
This is possible, though not yet trivial to set up. Basically, you will make a
new platform P2 by building S1 + P1. Here's what you need to do in brief:

1. Set up S1 with P1 in the normal way.

2. Edit S1/build.xml to include a target to make a platform P2. For example:

    <target name="create-platform" depends="build-zip">
        <mkdir dir="${p2}"/>
        <unzip src="${dist.dir}/${app.name}.zip" dest="${p2}"/>
    </target>

where S1/nbproject/project.properties or S1/nbproject/private/private.properties
defines:

    p2=...path.../myplatform

Note that the ZIP will currently contain S1's ${app.name} as its top-level dir,
so you can either move the unpacked files up one dir, or use the dir p2/s1name
as the actual platform location.

As of NetBeans 6.0, you may simply run the 'create-platform' target in your suite's
build.xml, which will create a platform in ${dist.dir}/${app.name}.

3. Now configure S2 to use P2 as its platform. If an absolute path, you can use
the Platform Manager, else for relative paths see the preceding section.

(Setting harness.dir to ${netbeans.dest.dir}/harness will only work if P2
includes a harness/ subdirectory, for example if S1 was configured to include
the harness cluster. Otherwise, try ${netbeans.home}/../harness, or any location
you prefer to keep a standard copy of the harness in.)

4. To associate sources with binaries for P2, you will need to use the Platform
Manager. You can select multiple source associations. In this case, use a
netbeans.org CVS checkout or source download for the P1 (NetBeans platform)
portion of P2, and use S1 (the suite directory) for the M1a...M1z modules in P2.

5. In an S2 module like M2a you should be able to depend on any module in P2,
including both NetBeans modules and modules from S1 like M1a. Code completion,
popup Javadoc, etc. should work if source associations have been correctly
configured in step #5.

6. In case S1 was an application module with configured branding, you might wish
to use S1's branding in S2 rather than making a new app for S2. Or, in place of
a suite S2 you might have a standalone module M2. In either case, you can use
S1's branding by configuring nbproject/project.properties in S2 (or standalone
module M2):

    branding.token=s1
    branding.dir=none

where 's1' was the branding token you chose for S1. This will permit Run,
Reload, etc. on S2 and its modules like M2a, or standalone module M2, to work
correctly.

netbeans.org MODULES: CONFIGURATION FILES
-----------------------------------------

Modules inside the netbeans.org CVS tree need not define a platform; it is
always "nbbuild/netbeans" in the CVS tree. They also do not have an explicit
harness; they use various files located in "nbbuild". Unlike external modules
which by default always use the cluster "devel", netbeans.org modules usually
specify a cluster in "nbbuild/cluster.properties" ("extra" by default).

PLATFORM DEFINITIONS
--------------------

The file build.properties in the user directory is used to store all information
about NetBeans platforms. Each platform has an ID string; the default platform's
ID is 'default'. The available properties for each platform are:

1. nbplatform.ID.netbeans.dest.dir (mandatory) - absolute path to the
destination directory (i.e. NetBeans platform installation).

2. nbplatform.ID.harness.dir (mandatory) - path to the build harness. Normally
will be "${nbplatform.ID.netbeans.dest.dir}/harness".

3. nbplatform.ID.sources (optional) - see next section.

4. nbplatform.ID.javadoc (optional) - see next section.

SOURCE AND JAVADOC ASSOCIATIONS
-------------------------------

Modules inside the netbeans.org CVS tree need not do anything special to
associate sources with binaries (the module JAR files under "nbbuild/netbeans");
it is automatic. Javadoc may be associated with an API-providing module just by
building its Javadoc (into "nbbuild/build/javadoc"), or by downloading the
NetBeans API Documentation module, which will cause 'nbplatform.default.javadoc'
to be defined in build.properties in the user directory (to the location of a
ZIP of Javadoc).

For external modules, sources and Javadoc may be associated with the active
platform by defining in build.properties in the user directory these properties:

1. nbplatform.ID.sources - an Ant-style path (e.g. ':' separated) containing
source roots you wish to associate with the binary modules in
${nbplatform.ID.netbeans.dest.dir}. Entries may be a checkout of the
netbeans.org CVS tree, or source roots of other module suites which are included
in the platform in binary form. Defining a source association permits you to
step through sources while debugging, use Go To Class, get popup Javadoc in code
completion, etc.

2. nbplatform.ID.javadoc - a path containing roots of Javadoc for API-providing
modules in the platform. Useful in case you wish to get Javadoc in View |
Documentation Indices; or in the code completion popup (if you do not have
sources). Each root may be a directory or a ZIP file. Within a root, the API for
org.netbeans.modules.foo is expected to be inside the subdir named
"org-netbeans-modules-foo".

For examples of complete and functioning "external" module suites, see
apisupport/project/test/unit/data/example-external-projects in netbeans.org
sources.

FORMAT OF YOUR project.xml's MAIN CONFIGURATION SECTION
-------------------------------------------------------

The format of project.xml is controlled by XML Schema. For the main section of
new modules, use:

  http://www.netbeans.org/ns/nb-module-project/3.xsd

If you wish to edit project.xml by hand rather than using the IDE's GUI, you
should validate all changes against this schema. If using the IDE's XML text
editor, just type Alt-Shift-F9 to validate the current document. (Make sure the
file is valid BEFORE saving it, as the IDE will refuse to load a malformed
project.xml.)

You must specify the "code name base" of your module. This is the value of
OpenIDE-Module in manifest.mf, *except* without any major release version (e.g.
"/1"). In the future OpenIDE-Module might be generated from this, but not yet.

    <code-name-base>org.netbeans.modules.foo</code-name-base>

For external modules, you must specify either <suite-component/> or
<standalone/>; for netbeans.org modules, you must not. See above discussion of
file layout.

Specify your dependencies on other modules:

    <module-dependencies>
        <dependency>
            <!-- The code name base, *not* with any major release version: -->
            <code-name-base>some.other.module</code-name-base>
            <!-- Usually, include this to say that it needs to be built -->
            <!-- *before* your module, if in the same suite: -->
            <build-prerequisite/>
            <!-- Usually also include this, to say that it needs to be in your module's classpath: -->
            <compile-dependency/>
            <!-- Always include this, to say that the module system should register a dependency: -->
            <run-dependency>
                <!-- Optional; use if and only if the other module uses e.g. /1 in its code name: -->
                <release-version>1</release-version>
                <!-- Optional; request a minimum version of another module: -->
                <specification-version>3.9</specification-version>
            </run-dependency>
        </dependency>
        <!-- and others as you need them... -->
        <!-- use org.openide for openide.jar -->
    </module-dependencies>

In a <run-dependency> you can also use just

    <implementation-version/>

in place of <specification-version>, meaning to declare an implementation
dependency on another module. The actual version is taken directly from that
module's current JAR so you do not need to keep track of it. *Important*: if you
either *export* or *import* any implementation dependencies, you should probably
use spec.version.base (see below).

Specify your test dependencies on other modules [since 5.0u2, requires /3
schema]. The tags in project.xml are 
described below:

    <test-dependencies>
        <! -- Dependencies for a source root with tests: -->
        <test-type>
            <!--
            Name of test type. Normally you will use 'unit'.
            netbeans.org modules also support 'qa-functional' test-type.
            -->
            <name>unit</name>
            <!-- A dependency on a module or its tests: -->
            <test-dependency>
                <!-- Identification of module our tests depend upon: -->
                <code-name-base>org.netbeans.modules.java.project</code-name-base>
                <!-- Include also transitive module dependencies of that module: -->
                <recursive/>
                <!-- Always available when running, but to include at compile time also: -->
                <compile-dependency/>
                <!-- To request the tests of that module as well: -->
                <test/>
            </test-dependency>
        </test-type>
    </test-dependencies>

Source root for a test type:
{project.dir}/test/${test-type.name}/src

{project.dir}/test/unit/src  - source root for unit test


For example you have three modules with code name bases A,B,C. A has runtime
dependency on B, B on C. You want to add test dependencies to unit test type
of module D:

Use case 1: Runtime dependency on module.

<test-type>
 <name>unit</name>
 <test-dependency>
    <code-name-base>A</code-name-base>
 </test-dependency> 
</testtype>

Runtime classpath is D + A. 
Compile classpath is D.

Use case 2: Runtime dependency on a module and its recursive runtime classpath.

<test-type>
 <name>unit</name>
 <test-dependency>
    <code-name-base>A</code-name-base>
    <recursive/>
 </test-dependency> 
</testtype>

Runtime classpath is A + B + C + D.
Compile classpath is D.

Use case 3: Compile and runtime dependency on a module its recursive runtime classpath.

<test-type>
 <name>unit</name>
 <test-dependency>
    <code-name-base>A</code-name-base>
    <compile-dependency/>
    <recursive/>
 </test-dependency> 
</testtype>

Runtime classpath is A + B + C + D.
Compile classpath is A + B + C + D.
Note one feature of recursive compile-time dependency: modules B and C are added
to compile classpath as well, even if A has only runtime dependency on B and B on C.

Use case 4: Compile and runtime dependency on a module, its recursive runtime classpath 
and tests.

<test-type>
 <name>unit</name>
 <test-dependency>
    <code-name-base>A</code-name-base>
    <compile-dependency/>
    <recursive/>
    <test/>
 </test-dependency> 
</testtype>

Runtime classpath is A + B + C + D + A/test/unit.
Compile classpath is A + B + C + D + A/test/unit.

Declare any public API/SPI packages you export:

    <public-packages>
        <package>org.netbeans.api.foo</package>
        <package>org.netbeans.spi.foo</package>
    </public-packages>

If you do not export any API, say so:

    <public-packages/>

If you export an API to selected modules only, you can use (NB 5.0+ only!):

    <friend-packages>
        <friend>org.netbeans.modules.brother</friend>
        <package>org.netbeans.modules.foo.spi</package>
    </friend-packages>

If you bundle a special library which you want to expose to modules depending on
you, you need not enumerate every package explicitly:

    <public-packages>
        <subpackages>javax.foo</subpackages>
    </public-packages>

Exported implementation "APIs" do not need to be declared; anyone depending on
your module with an implementation dependency gets access to *all* your
packages. Be careful and avoid this situation whenever possible.

If your module bundles one or more third-party libraries, declare them:

    <class-path-extension>
        <!-- Deployed path, relative to dir containing module: -->
        <runtime-relative-path>ext/foolib.jar</runtime-relative-path>
        <!-- Path of library in your own sources, relative to project basedir: -->
        <binary-origin>external/foolib.jar</binary-origin>
    </class-path-extension>

You still need to separately copy the JAR to the output directory (see below).
This just declares that Class-Path in your module's manifest should be defined,
and adds a compile-time classpath entry for your module and modules depending on
it.

If your bundled library is built from sources, just use

    <class-path-extension>
        <runtime-relative-path>ext/foolib.jar</runtime-relative-path>
    </class-path-extension>

Sometimes a module will produce some extra JARs (in modules/ext/ for Class-Path,
in ant/nblib/, etc.), or will just need to have some extra sources for
miscellaneous purposes (e.g. custom Ant tasks). You can declare them, somewhat
similarly to how freeform projects permit compilation units to be declared; you
will still need to explicitly compile and JAR them in your build.xml. For
example, for in-IDE automatic Ant tasks you might use:

    <extra-compilation-unit>
        <!-- Root of Java packages, relative to project basedir: -->
        <package-root>antsrc</package-root>
        <!-- Compile-time classpath: -->
        <classpath>${ant.home}/lib/ant.jar:${openide.dir}/core/openide.jar</classpath>
        <!-- Places where classes are deposited: -->
        <built-to>build/antclasses</built-to>
        <built-to>${cluster}/ant/nblib/${code.name.base.dashes}.jar</built-to>
    </extra-compilation-unit>

Or for a Class-Path extension built from sources, you might use:

    <extra-compilation-unit>
        <package-root>libsrc</package-root>
        <classpath/>
        <built-to>build/libclasses</built-to>
        <built-to>${cluster}/modules/ext/foolib.jar</built-to>
    </extra-compilation-unit>

A custom Ant task (or set of tasks) you use only during your own build might
look like:

    <extra-compilation-unit>
        <package-root>antsrc</package-root>
        <classpath>${ant.home}/lib/ant.jar</classpath>
        <built-to>build/antclasses</built-to>
        <built-to>build/tasks.jar</built-to>
    </extra-compilation-unit>

Note that <classpath> may contain Ant property references, so for a complex
classpath, define it once in project.properties and use that property in
<classpath> as well as in your Ant script.

In order for the IDE to recognize references to those classes defined in the 
<extra-compilation-unit>, you may also need add/modify your module's cp.extra
property to include the value specified in the <package-root> element.

AN IMPORTANT NOTE: CUSTOMIZATION OF BUILD SCRIPTS
-------------------------------------------------

Harness scripts allow a great degree of customization in your project's build
script and properties files (see sections on properties and Ant targets
below). Due to open nature of Ant scripts (everything is public) special
attention must be paid to migrating customized build scripts to newer version of
harness. In order to avoid unexpected use of newer version of  harness with new
IDE, make sure that your either define harness location explicitly via
harness.dir property or that you use harness supplied with NB platform you are
building against ('Harness supplied with Platform' option on Harness tab in
NetBeans Platform Manager).

Of course sometimes you want to upgrade to newer version of harness. To minimize
the chances that it will break your (customized) build, follow these
simple rules:

 * Use only properties listed in the following sections and avoid overriding
   those marked 'Do not override' or similarly.
 * Depend on/override only targets listed in sections 'Targets available for
   overriding...' below
 * When overriding targets, use only pre- or post-hooks (described below) for
   your code and call original target as a whole in 'depends' attribute of the
   target.

Note that even when sticking to these rules, there is always possibility that
migration to newer version of harness will break your build, especially when you
depend on some implementation details, like a property *not* being set in
particular internal target, concrete calling order of targets, etc.

PROPERTIES WHICH MAY BE DEFINED IN YOUR project.properties
----------------------------------------------------------

If needed, these properties may also be defined in private.properties (to make
them applicable to only your own checkout of sources). Only selected properties
are listed here; others may be interpreted, but see the Ant script for details.

Unless otherwise noted, properties listed here *are* available for use in
selected fields in project.xml, *are* available for use in your build.xml
(depend on some init target to make sure), and *are not* available for use when
defining other properties in project.properties (unless you defined them in
private.properties).

app.icon.icns [since 6.9] - "${harness.dir}/etc/applicationIcon.icns" by default,
path to application's icon in Mac (.icns) format; used for creating ".app" 
directory hierarchy in "build-mac" target.

basedir - you cannot define this; it is always the project directory of the
module (as in any Ant script). Available in all other properties files.

build.classes.dir - "build/classes", used to send compiled classes to.

build.compiler.debug - default "true" to include debugging info when compiling
(needed if you want to step through sources).

build.compiler.debuglevel - default "source,lines,vars" to include all debugging info.

build.compiler.deprecation - default "true" to display deprecation warnings when
compiling. If you want to disable deprecations, it is recommended you use
private.properties:

    build.compiler.deprecation=false

build.test.unit.classes.dir - "build/test/unit/classes", where unit tests are
compiled to.

buildnumber - generated timestamp for use in
OpenIDE-Module-Implementation-Version (or OpenIDE-Module-Build-Version if
OpenIDE-Module-Implementation-Version was explicitly defined in the manifest).

catalog.base.url [since 6.9] - distribution base for the suite modules NBMs
location for which the catalog is generated. Default is ".". 

cluster - cluster directory your module is to be built into. For netbeans.org
modules, this is a subdirectory of nbbuild/netbeans/; the subdirectory name is
defined automatically from nbbuild/cluster.properties, with a fallback to
"extra". For suite component modules, it defaults to
"${suite.dir}/build/cluster", though you could override it if you wanted (e.g.
in platform.properties); similarly, for standalone modules, it defaults to
"${basedir}/build/cluster". Available in project.properties for netbeans.org
modules only.

code.name.base - your code name base as org.netbeans.modules.foo

code.name.base.dashes - your code name base as org-netbeans-modules-foo

code.name.base.slashes - ditto, as org/netbeans/modules/foo

cp.extra - extra JARs you have to compile module sources against. Rarely needed
any more, but if you have defined extra source trees with <extra-compilation-unit>,
it may be necessary to add/modify this value to include the value specified in 
its <package-root> element.

extra.module.files - list of special files you build alongside your module JAR
which you want to register for update tracking and include in your NBM.
*Everything* you put into your cluster should be enumerated. Paths are relative
to the cluster directory. Ant-style patternsets (most simply a trailing slash)
are permitted if you can be sure no other modules' files would also match.
Example:

    extra.module.files=\
        ext/foolib.jar,\
        docs/FooAPI.zip,\
        SpecialThirdPartyTool1.0/

(You do *not* need to include: the module JAR itself; your JavaHelp JAR if you
build one; your module declaration file; any module-auto-deps.xml; an
ant/nblib/*.jar corresponding to your module; or any files in ${release.dir}.
These are all included by default.)

foo/bar.dir - absolute path of cluster directory to which the netbeans.org
module "foo/bar" is built. Only defined for netbeans.org modules, and only if
foo/bar was *already* built before yours (specify <build-dependency/>).
Available in project.properties.

harness.dir - location of the build harness (for external modules). Usually
"${netbeans.dest.dir}/harness".

is.autoload and is.eager - default false, but if true, make this module an
autoload or eager module.

javac.compilerargs [since 5.0u1] - default none; additional arguments to pass
to the Java compiler, e.g. "-Xlint:unchecked".

javac.source - default "1.4"; to use JDK 1.5 features like generics:

    javac.source=1.5

javac.target - default ${javac.source}; controls version of generated bytecode

javadoc.apichanges - optional location of an API changes list. Currently for
netbeans.org modules only.

javadoc.arch - optional location of an architecture XML description. Highly
recommended as it makes your module self-documenting.

    javadoc.arch=${basedir}/arch.xml

javadoc.overview - optional location of a Javadoc overview page. Discouraged
since it disables the default content which links to various generated documents
which you would need to manually add to your own overview.

javadoc.title - title for Javadoc build. Optional for external modules.
DEPRECATED since 5.0u1; taken from other module metadata.

javahelp.base - "${code.name.base.slashes}/docs" by default; directory
containing your help set, under "javahelp/".

javahelp.excludes - optionally, list of file name patterns to exclude from
JavaHelp search index construction.

javahelp.jar - "modules/docs/${code.name.base.dashes}.jar". Do not override.
Constructed from ${javahelp.jar.basename} and ${javahelp.jar.dir}.

javahelp.search - "JavaHelpSearch" by default; name of search database
directory, relative to your help set. Must match what your help set specifies.

jhall.jar - for external modules, if you wish to build JavaHelp, you must define
the location of jhall.jar from the JavaHelp distribution, as this is needed to
run the search indexer. DEPRECATED since 5.0u1; the 5.0u1 harness now includes
jsearch-*.jar so you do not need to specify this property any longer.

keystore - Key store for signing NBMs. A candidate for private.properties - you
do *not* want to share this file! Also ${nbm_alias} and ${storepass} are used in
the NBM signing process.

license.file - optional. Location of license text to use when creating an NBM.
(External modules only.)

manifest.mf - JAR manifest location. Avoid overriding.

module.auto.deps.xml - "module-auto-deps.xml" in your project directory by
default. Optional configuration file.

module.classpath - your main module source's compile-time classpath, according
to <module-dependencies>. Since 5.0u1 uses public-package-only JARs where
appropriate.

module.run.classpath [since 5.0u1] - your main module source's run-time
classpath, according to <module-dependencies>. Similar to ${module.classpath}
except does not use public-package-only JARs; includes run-time-only
dependencies; and processes dependencies transitively.

module.jar - location of module JAR relative to cluster directory. Do not
override directly; override ${module.jar.basename} (default
"${code.name.base.dashes}.jar") and/or ${module.jar.dir} (default "modules") if
necessary (not without a good reason!).

module.jar.verifylinkageignores [since 6.0] - regexp pattern for class names
that are excluded from linkage check

module.javadoc.packages - comma-separated list of packages to be included in
Javadoc. Defaulted according to <public-packages> or <friend-packages>, but if
you used <subpackages> (or if you have not specified any public or friend
packages at all) you will need to specify it explicitly.

nbm.distribution - optional URL to location where your NBM can be downloaded
from.

nbm.executable.files [since 6.8] - comma- or space- separated list of patterns of 
files relative to cluster directory for which executable permissions should be set 
on Unix system when building the module and on NBM installation/update in runtime.

nbm.homepage - optional URL to HTML homepage for background about the module.

nbm.is.global - set to "true" if NBM cannot be installed in user directory.

nbm.module.author - author info for an NBM.

nbm.needs.restart - set to "true" if NBM cannot be installed (even for the first
time) without restarting the IDE.

nbm.target.cluster [since 5.0u2] - allow to declare a target cluster where
install if NBM install globally.

autoupdate.catalog.url - if you want to use module's or suite's update target
during build, you need to specify the URL of your NBMs catalog.

nbplatform.active - optional name of a NB platform to build and run against. See
discussion above for details of how this is used.

netbeans.dest.dir - [up to 6.5.1] absolute pathname of NB platform (or IDE or 
whatever) that you are building your module against, and into which your module 
will be built. Available in project.properties (and in all properties files for 
netbeans.org modules). Specified folder must exist and must contain valid NB 
platform. Do not define in suite modules if suite's platform.properties defines 
"cluster.path" property. Also do not depend on this property to be defined, it 
will not be in projects created with NB 6.7 or later. 


netbeans.home - location of "platform*" cluster of the NetBeans IDE installation
you are running. *Only defined* when you run an Ant script *inside* the IDE.

nbjdk.active [since 5.0u1] - name of a Java platform (JDK) to use when building
and running. Will try to load (e.g. from ${userdir}/build.properties, where Java
Platform Manager stores its information) the properties

    nbjdk.home=${platforms.${nbjdk.active}.home}
      - JDK (not JRE!) home directory
    nbjdk.bootclasspath=${platforms.${nbjdk.active}.bootclasspath}
      - JRE JARs, e.g. rt.jar (default: ${nbjdk.home}/jre/lib/rt.jar)
    nbjdk.java=${platforms.${nbjdk.active}.java}
      - java executable (default: ${nbjdk.home}/bin/java)
    nbjdk.javac=${platforms.${nbjdk.active}.javac}
      - javac executable (default: ${nbjdk.home}/bin/javac)
    nbjdk.javadoc=${platforms.${nbjdk.active}.javadoc}
      - javadoc executable (default: ${nbjdk.home}/bin/javadoc)

if they are not already defined. Uses <presetdef> to make <java>, <javac>,
<javadoc>, <junit>, and <nbjpdastart> use this JDK. Optional; if unset (or set to
'default'), will use the current VM's Java platform instead. Define in
platform.properties (in a standalone module, or in the suite for a suite component
module, or in nbbuild/user.build.properties for a netbeans.org module). You may
also define just ${nbjdk.home} directly, without using ${nbjdk.active}, if you do
not need to use the Java Platform Manager to set up the JDK definition.

use.pack200 [since 6.9] - whether to Pack200 compress NBMs; default true.

pack200.excludes [since 6.9] - comma- or space- separated list of patterns of 
files relative to cluster directory for which pack200 compression should not be used 
while creating NBMs.

project.license [since 6.0] - license to use for newly created files in the project
(applies also to suites); default is 'cddl' for modules inside netbeans.org.

release.dir - "${basedir}/release"; location of a directory full of files to
copy unmodified to the output cluster. Since 6.0 beta2 also applies to module
suite projects. DO NOT ATTEMPT to create files in this directory during the
build; it is ONLY for static content (versioned files present in a clean source
project). Dynamically generated cluster content should be placed directly in
${cluster} as part of a netbeans-extra target, and be sure to mention such files
in ${extra.module.files}.

run.app.exe - "bin\netbeans.exe"; name of Windows launcher to start (inside
${netbeans.dest.dir}) if trying to run the application for interactive testing.
Only relevant if ${app.name} is unset.

run.app.sh - "bin/netbeans"; same but for Unix (and Mac OS X).

run.args.extra - empty; any added arguments to pass to the launcher.

run.jdkhome - location of JDK to run application with for interactive testing.
Defaults to JDK the Ant script was using, or that selected by ${nbjdk.active}.
DEPRECATED - for compatibility only. Use ${nbjdk.active} instead.

spec.version.base - this is a little subtle. If you export an implementation
dependency to other modules, *and/or* depend on one or more other modules using
implementation dependencies, you are advised to use this property *in place of*
writing OpenIDE-Module-Specification-Version explicitly in your manifest. It
should be a dotted number to serve as the base of a specification version; keep
the number of components *fixed* even if you branch the module, so e.g. in a
development version use

    spec.version.base=1.7.0

and if you need to increment this in a release branch use e.g.

    spec.version.base=1.7.1

The harness will automatically append integers to it as follows to create the
actual specification version:

1. Your OpenIDE-Module-Implementation-Version, if specified and an integer.

2. The OpenIDE-Module-Implementation-Version of modules you depend on using
implementation dependencies, if integers; ordered by alphabetizing the
dependencies.

(Example: if you have impl version 3, and you depend on org.netbeans.modules.foo
= 6 and org.netbeans.modules.bar = 7, your actual spec version would be
1.7.0.3.7.6.)

This is very handy for Auto Update: whenever you or anyone else makes a change
to an implementation API, just increment the
OpenIDE-Module-Implementation-Version of the providing module. That module and
any modules depending on its API will get a higher
OpenIDE-Module-Specification-Version automatically, so the whole set of
interdependent modules can be published to users at once on an update center.

src.dir - "src", module source directory. Avoid overriding.

test.timeout [since 6.1] - timeout (in msec) for unit tests, default 600000 (10
minutes). A test running longer than this will be halted.

test.run.args [since 6.5] - general VM arguments to pass when running tests.
Defaults to just "-ea".

test.config [since 6.5] - name of a test configuration to run, specifying a set
of unit and/or functional tests which should be run by the 'test' target.
Defaults to 'default'. ${test.config.NAME.includes} specifies the includes list
(format: classpath resources). The standard value of ${test.config.NAME.includes}
depends on NAME. In case of 'default', it includes every test ('**/*Test.class').
In case of any other NAME the includes list is empty.
${test.config.NAME.excludes} (default '') specifies an excludes list.

test.unit.cp.extra - any additional classpath you might need to compile your
unit tests. If left empty, you can compile against JUnit; the NB test extensions
in nbjunit.jar; your module; and anything your module compiled against (since
5.0u1, ${module.run.classpath}). As of 5.0u2 you can and should include other
modules in project.xml's <test-dependencies> but in earlier releases these must
be listed in this property.

    test.unit.cp.extra=\
        ${tools.jar}:\
        ${basedir}/lib/custom-junit-helpers.jar

test.unit.run.cp.extra - any additional classpath you might need to *run* your
unit tests with (beyond what they are already compiled with). As of 5.0u2 you
can and should include other modules in project.xml's <test-dependencies> but in
earlier releases these must be listed in this property.

test.unit.lib.cp - path to some basic libraries which can be used in unit tests:
junit.jar, nbjunit.jar, and insanelib.jar. Not needed for netbeans.org modules.
For external modules, may be needed if you do not have the junit and testtools
modules installed in the target platform *or* the developing IDE, and the target
platform is not inside a netbeans.org build tree (in nbbuild/netbeans).
DEPRECATED as of 6.5; even basic libraries should instead be declared as regular
test dependencies (they are now included in the harness cluster).

test.unit.src.dir - "test/unit/src"; avoid overriding.

test-unit-sys-prop.<NAME> - will set a system property <NAME> when running your
unit tests.

test.dist.dir - directory with test distribution. 

test.unit.folder - output directory for tests of module.

test.unit.out.folder - this property can be overriden when you want to change 
test.unit.folder property.

continue.after.failing.tests - controls behavior of running tests on all modules
in suite. Default value is "true", which causes suite.test target to continue 
with another module even if tests in previous module failed. Set to "false" 
in your suite's project.properties to force test target to stop after tests
in one module failed. In module project this controls whether test target
fails when tests fail (when set to "false" or unset) or succeeds even if 
test failed (when set to "true").

extra.test.libs.dir - directory with extra libraries needed for test run. 

tools.jar [since 5.0u1] - set to location of tools.jar in active JDK. Useful in
case your module needs to compile against JDK-only classes. Meaningless on Mac
OS X.

To support builds of JNLP-based applications additional properties may be used
or redefined in JNLP-related targets:

jnlp.servlet.jar - must point to jnlp-servlet.jar as provided by JDK 5 in
  the directory sample/jnlp/servlet/jnlp-servlet.jar if one wants to build 
  a packaged war file of JNLP version of your suite

jnlp.dest.dir - the location where to generate the JNLP files and signed 
  jars. By default it is your ${suite.dir}/build/jnlp

jnlp.master.dir - (category='private') location of a directory in which
  to generate pieces of master JNLP file to be included in the resources
  section.

jnlp.signjar.alias -
jnlp.signjar.keystore - 
jnlp.signjar.password - allow you to sign your app with your own private key, if
  unspecified then a default keystore is generated. Nice for trying things for
  the first time, but not for production, then you very likely want to generate
  your key and set these properties
jnlp.signjar.vendor - you can override this to be the default dname for the keystore

jnlp.platform.codebase - can point to a shared repository which can be generated
  by ant -f nbbuild/build.xml build-jnlp. Then your WAR file will contain only 
  modules of your suite and platform modules will be referenced by the value of
  this property. Sample values with prebuilt binaries (good for testing):
http://bits.netbeans.org/6.5/jnlp/
http://bits.netbeans.org/6.7/fcs/jnlp/
http://deadlock.netbeans.org/hudson/job/ide-jnlp/lastStableBuild/artifact/nbbuild/build/jnlp/

jnlp.indirect.jars [since 6.0] - optional pattern of JARs in the cluster to load
  in JNLP mode even though they are not listed as Class-Path extensions of the
  module JAR. The module ought not directly refer to classes in these JARs (it
  could not do so in non-JNLP mode) but it may load them reflectively using
  InstalledFileLocator using the same path in regular as in JNLP mode. Note that
  the physical path on disk to the resulting JAR will not necessarily contain
  the directory prefix that the JAR in the cluster uses, so do not expect that
  jar.getParentFile() is meaningful. The implementation creates an empty JAR
  entry META-INF/clusterpath/$path where $path is the ('/'-separated) path
  within the cluster where the JAR would be found in a normal installation.

jnlp.indirect.files [since 7.0M1] - optional pattern of files in the cluster to
  load in JNLP mode. The module may load these files using InstalledFileLocator
  using the same path in regular as in JNLP mode. Note that the physical path on
  disk to the resulting file will not necessarily contain the directory prefix
  that the file in the cluster uses, so do not expect that file.getParentFile()
  is meaningful. The implementation creates a JAR entry META-INF/files/$path
  where $path is the ('/'-separated) path within the cluster where the file
  would be found in a normal installation.

jnlp.verify.excludes - the default implementation of "jnlp" task in common.xml
  does verification and compares that all files from module NBM are really
  referenced from the JNLP file. Sometimes not all of them need to be, for
  them you can put their full names (relative to your cluster root) into this
  property and separate them by comma.

jnlp.permissions - allows altering of the fragment in the resulting .jnlp file
  that sets the permissions for individual modules. The default value is
  &lt;security&gt;&lt;all-permissions/&gt;&lt;/security&gt; when jnlp.sign.jars
  is true, &lt;security/&gt; when jnlp.sign.jars is false.
  If you want to change the default to something else please define the value
  of the property.

jnlp.sign.jars [since 6.0] - defaults to true. If set to false the jars 
  will not be signed, only the main (startup) jar. This should allow for 
  faster startup but might compromise JNLP security. Use with extreme care.

jnlp.generate.versions [since 6.7] - Defaults to false, which means versioning 
  info is not generated (see 
  http://java.sun.com/j2se/1.5.0/docs/guide/javaws/developersguide/downloadservletguide.html#resources).
  If set true, build-jnlp target creates versioning info in jnlp descriptors and version.xml files.
  This allows for incremental updates of Webstart applications, but requires download via
  JnlpDownloadServlet (thus run-jnlp and debug-jnlp does not create versioning info even with this
  property set to true).
  
[XXX some of the above should be listed in "Suite Properties"]


TARGETS AVAILABLE FOR OVERRIDING IN YOUR build.xml
--------------------------------------------------

Obscure or mostly internal targets are skipped here, but again examine the
actual harness script if in doubt. If you want to keep the original
implementation and just add a before hook, try e.g.

    <target name="-pre-javahelp">
        <!-- your stuff here -->
    </target>
    <target name="javahelp" depends="-pre-javahelp,harness.javahelp"/>

(some original targets are projectized-common.* rather than harness.*). If you
want to add an after hook, try e.g.

    <target name="javahelp" depends="harness.javahelp">
        <!-- your stuff here -->
    </target>

basic-init - define some properties such as file locations; enough to do a clean
at least.

build-init - define more properties needed for compiling and other build tasks.

clean - remove all build products: the "build" directory under your project
directory, and any files left in the build cluster (including
${extra.module.files}).

compile - compile Java sources for the module.

compile-single - compile selected Java sources (F9).

compile-test-single - compile selected unit test classes (F9).

debug - build module and then start target platform in debug mode. Use from
within the IDE (there is a context menu item for it) to debug the app.

debug-fix-nb - loads a hotfix for a module class while debugging. Run -> Apply
Code Changes from the IDE.

debug-fix-test-nb - same, for unit test classes.

debug-test-single-nb - run one single unit test in the debugger (e.g. to see why
it is failing). Available from the IDE's menus.

files-init - define list of files in the NBM fileset. Use ${extra.module.files}
rather than overriding this.

init - all normal initialization.

jar - build the module JAR.

jar-prep - prepare to build the module JAR; define ${buildnumber}.

javadoc - build module Javadoc.

jnlp - generetes the JNLP component file for this module and all necessary
  resources for it into ${jnlp.dest.dir} directory and also a fragment of
  the master JNLP into ${jnlp.master.dir}

javadoc-nb - same, and open it in a web browser (only from the IDE). Available
as Build -> Generate Javadoc.

javahelp - build JavaHelp.

nbm - build the NBM. You might override this to give a complex (multipart)
license text. Copy basic impl from common.xml and edit.

netbeans - build everything needed for the NBM. Do not override; use
netbeans-extra instead.

netbeans-extra - hook target: does nothing unless overridden, but called when
building a module. Override to insert any additional build tasks you need to do:
copying libraries to the cluster, etc.

profile - used from inside the IDE (if the NetBeans profiler is installed) to
profile the entire application.

profile-test-single-nb - run one unit test under the profiler. Available from the
IDE's menus if the NetBeans profiler is installed.

release - copies contents of ${release.dir} to ${cluster}.

reload - reloads the module in the target IDE/app to try out changes interactively.

reload-in-ide - reloads the module in the current IDE to try out changes
interactively. Only available when run from inside NetBeans. Use with care.

run - build module and then run application interactively. Only for external
modules. Either way, available from context menu in Projects tab.

test - run all unit tests for the module. Run -> Test... in the IDE.

test-generate-html [since 6.5 M2] - can be used after test target to generate
test reports in html.

test-build - build unit tests for the module.

test-init - define properties used for building and running unit tests.

test-preinit - I'm not sure, actually.

test-single - run a selected unit test only. Available in the IDE's menus.

testuserdir-delete - deletes just the testing user directory (if not currently in use).

verify-class-linkage [since 5.0u1] - checks for possible linkage errors in your module
and its Class-Path extensions.

SUITE PROPERTIES
----------------

Some properties are shared with module projects, such as ${cluster}.

app.name - filename of application launchers to create, suite name to create,
etc.

app.version - version of the application, used in building the MacOS application
bundle for example. (Since 6.0 beta2)

app.conf - location of an alternative configuration file. If not specified,
default one from harness/etc/app.conf is taken (Since 6.9)

branding.dir (default "${suite.dir}/branding") - directory containing branding
overrides.

branding.token - optional token defining an application branding.

enabled.clusters - comma-separated list of cluster names in the target platform
(e.g. "platform") which should be included in the application. Should be stored
in platform.properties, not project.properties. Available since 5.0u1. Since 6.5,
can elide version numbers from the end, e.g. just "platform" suffices.

disabled.clusters - comma-separated list of cluster names in the target platform
(e.g. "ide") which should be completely excluded from the application.
DEPRECATED since 5.0u1 in favor of ${enabled.clusters} and ignored if that is nonempty.

disabled.modules - comma-separated list of code name bases of modules in the
target platform (e.g. "org.netbeans.modules.autoupdate") which should be
excluded from the application. There is no need to specify modules already
excluded by ${disabled.clusters} (if used) or by modules from clusters not included
in ${enabled.clusters}. Since 5.0u1, should be stored in platform.properties,
not project.properties.

dist.dir - directory (if not 'dist') to place the final application in. Since 6.1.

modules - list of contained modules. Path format; entries resolved against the
suite directory as needed.

jnlp.codebase [since 5.0u1] - in case one wants to build a static repository not
packaged in a WAR file, one needs to pass in the full URL for it. By default it
is specified as "$$codebase" and replaced dynamically by the servlet packaged in
the WAR file.


TARGETS AVAILABLE FOR OVERRIDING IN YOUR SUITE build.xml
--------------------------------------------------

-init - set up properties. Most importantly, ${modules.sorted} contains a list
of absolute path names to the base directories of the modules in the suite,
topologically sorted by build order; suitable for use with <subant>, for
example. Some other basic properties like ${netbeans.dest.dir} will also be
defined.

branding - building branding JARs, if applicable. Example: if ${branding.token}
is "foo", then a file such as

    ${branding.dir}/modules/org-netbeans-modules-x.jar/org/netbeans/modules/x/resources/Bundle.properties

will be packed into

    ${cluster}/modules/locale/org-netbeans-modules-x_foo.jar!/org/netbeans/modules/x/resources/Bundle_foo.properties

build - build all suite modules.

build-jnlp - builds a JNLP WAR file from your application suitable for
publishing in a Java EE container.

build-mac [since 5.0u2] - creates a Mac OS X application.

build-zip - builds a ZIP file containing your application including launchers.

clean - clean everything.

debug - like run, but run in the JPDA debugger. (Only available from inside the
IDE.)

debug-jnlp - starts debuging of your JNLP application (works only from NetBeans IDE)

nbms [since 5.0u1] - creates NBMs for all modules in the suite, and generates
an XML descriptor listing them suitable for use from Auto Update.

profile - used from inside the NetBeans IDE to profile the entire suite

run - start application for testing.

run-jnlp - executes your JNLP application (currently from local files)

test - run all module unit tests. Since NetBeans 6.8 runs tests of all suite modules
by default, even if some of them fails and target succeeds regardless of test status.
When property 'continue.after.failing.tests' is set to 'false', this target fails
immediately after tests in some module fail and does not continue testing the rest
of the suite (this was the default up to version 6.7).

testuserdir-delete - deletes just the testing user directory (if not currently in use).

CONTENTS OF YOUR manifest.mf
----------------------------

This file is just a prototype of the module JAR manifest, as described in the
Modules API. It must contain the attribute OpenIDE-Module and is strongly
encouraged to contain also OpenIDE-Module-Localizing-Bundle; other attributes
are generally optional.

Several attributes in the main section should *not* be written into this file as
they are automatically generated during the build:

    Class-Path
    OpenIDE-Module-Build-Version
    OpenIDE-Module-Friends
    OpenIDE-Module-Implementation-Version (unless you are exporting an impl API)
    OpenIDE-Module-Module-Dependencies
    OpenIDE-Module-Public-Packages
    OpenIDE-Module-Specification-Version (unless you are *not* using spec.version.base)

Do not forget that manifest files must begin with the magic phrase

    Manifest-Version: 1.0

and to be safe should end in *two* newlines.

TEST COVERAGE SUPPORT SPI
-------------------------

There is a support for test coverage measurement for apisupport projects 
since 6.7. There is a general contract under which alternative 
implementations may by added (in case of multiple impls present, only 
one is used). NetBeans 6.7 and 6.8 use Cobertura implementation. 

A contract for test coverage implementation for module projects is to 
create Ant script testcoverage.xml in 'harness' cluster. Script 
must: 

  * reside directly in root folder of the cluster
  * set property testcoverage.present to true outside of any target
  * define target 'coverage-report' in the script
  * set property testcoverage.report.dir in 'coverage-report' target to dir
    with index.html file with results.
  * As of 6.8, unit and functional tests are supported.

A contract for test coverage implementation for suite projects is to 
create Ant script testcoverage-suite.xml in 'harness' cluster. Script 
must: 

  * reside directly in root folder of the cluster
  * set property testcoverage.suite.present to true outside of any target
  * define target 'coverage-report' in the script
  * set property testcoverage.report.dir in 'coverage-report' target to dir
    with index.html file with results.
  * As of 6.8, only unit tests are supported for suite projects.
	
Clients should make no other assumptions beyond these contracts. All 
other related files must be stored in 'testcoverage/<impl name>' 
subfolder. 


----------------
Hey Emacs!
Local Variables:
mode: text
fill-column: 80
End: