readme

AIOTrade is a free, open source stock technical analysis platform built on pure java. Its pluggable

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: [e-mail]

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' based on value of ${nbplatform.active}]
${basedir}/nbproject/private/private.properties
${basedir}/nbproject/project.properties

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').

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' 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' 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}
    netbeans.dest.dir=${suite.dir}/../nb_sources/nbbuild/netbeans
    harness.dir=${netbeans.dest.dir}/harness

The platform.properties should *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)
--------------------------------------------------

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/${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.

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.

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 launchers 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 launchers by making sure that the 'bin/' and 'etc/' directories get copied
into the P2 platform (i.e. do not specifically exclude them in step #2); and
configure nbproject/project.properties in S2 (or standalone module M2):

    run.app.exe=bin\\s1.exe
    run.app.sh=bin/s1

where 's1' was the branding name 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
-------------------------------------------------------

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>