| INTRODUCTION |
| ------------ |
| |
| This build harness permits modules outside of the netbeans.org source 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: dev@openide.netbeans.org |
| |
| BASIC FILE LAYOUT |
| ----------------- |
| |
| Within the netbeans.org source 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 source 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 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 |
| 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* |
| the platform and harness locations 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 source checkout (i.e. if you build NetBeans |
| from sources and then build your suite against that). |
| |
| As of 7.1, you can use bootstrap.url and autoupdate.catalog.url to download the |
| harness and platform rather than storing them in VCS. |
| |
| "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 source 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 source tree need not define a platform; it is |
| always "nbbuild/netbeans" in the source 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 source 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 source 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.dir - "build", location of all module build products not placed into |
| ${suite.build.dir}. May be overridden on a suitewide basis if placed in |
| platform.properties, e.g.: build.dir=${suite.build.dir}/${ant.project.name} |
| [since 7.0] |
| |
| 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"; similarly, for standalone modules, it defaults to |
| "${basedir}/build/cluster". Value available for substitution 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. |
| |
| module.startlevel [since 7.1] - modules which are OSGi bundles can specify its |
| start level (a positive integer) via this property. Default is empty, meaning |
| no start level specified for the bundle (according to OSGi spec defaults to 1). |
| |
| 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 |
| |
| javac.fork - default "false"; one can request the complication to be done |
| in a separate process. Useful for large code bases. |
| |
| 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.processor.classpath [since 7.0.1] - your main module source's processor |
| classpath, according to <module-dependencies>. Similar to |
| ${module.run.classpath} except run-time-only dependencies are not considered. |
| |
| 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. Since 7.1, this |
| may be used (in conjunction with bootstrap.url) to download the harness and |
| platform from an update site. |
| |
| 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. |
| |
| test.includes - is needed when all or a single test is run. In the latter case |
| a TestNG suite xml file could alternatively be provided. |
| |
| test.class - is needed when a single method is run/debugged or when a single |
| test is debugged. In the latter case a TestNG suite xml file could |
| alternatively be provided. |
| |
| 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/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 6.7 M1] - 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 |
| <security><all-permissions/></security> when jnlp.sign.jars |
| is true, <security/> 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). |
| |
| PROPERTIES WHICH MAY BE DEFINED IN YOUR SUITE platform.properties |
| ----------------------------------------------------------------- |
| |
| (Most of the module properties above may also be set in platform.properties in the |
| suite, so as to be available to all modules in the suite. Be careful about relative |
| paths: use ${suite.dir} to absolutize as needed. platform-private.properties overrides.) |
| |
| nbplatform.active - optional name of a NB platform to build and run against. See |
| discussion above for details of how this is used. ${nbplatform.active.dir} may |
| then be used in cluster.path. |
| |
| bootstrap.url - remote location of harness/tasks.jar to download. Then you also |
| need to define autoupdate.catalog.url to be the location of an update site |
| (usually called updates.xml) from which specified clusters and modules can be |
| downloaded. With these two properties, you can create a reproducible build with |
| no NetBeans binaries in VCS. For example: |
| -nbplatform.active=default |
| +suite.dir=${basedir} |
| +nbplatform.active.dir=${suite.dir}/nb |
| +harness.dir=${nbplatform.active.dir}/harness |
| +bootstrap.url=http://deadlock.netbeans.org/job/nbms-and-javadoc/lastStableBuild/artifact/nbbuild/netbeans/harness/tasks.jar |
| +autoupdate.catalog.url=http://updates.netbeans.org/netbeans/updates/7.0.1/uc/final/distribution/catalog.xml.gz |
| |
| cluster.path [since 6.7] - list of clusters to build your modules against and |
| include in your application. |
| |
| 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. DEPRECATED |
| since 6.7 in favor of ${cluster.path}. |
| |
| 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 not included |
| in the cluster path. |
| |
| |
| PROPERTIES WHICH MAY BE DEFINED IN YOUR SUITE project.properties |
| ---------------------------------------------------------------- |
| |
| Some properties are shared with module projects, such as ${cluster}. |
| private.properties overrides. |
| |
| 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. |
| |
| suite.build.dir - "build", location of suitewide build products including the |
| cluster. If overridden, should be placed in platform.properties, e.g.: |
| suite.build.dir=${suite.dir}/../build [since 7.0] |
| |
| 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 build.xml |
| -------------------------------------------------- |
| |
| Obscure or mostly internal targets are skipped here, but again examine the |
| actual harness script if in doubt. |
| |
| Since Apache NetBeans 11 some of the default targets make the use of Ant "Extension-Points" |
| to add "before" and "after" hooks. See Ant manual for more about "Extension-Points" |
| https://ant.apache.org/manual/targets.html#extension-points |
| |
| <target name="yourStuffName" extensionOf="-pre-jar"> |
| <!-- your stuff here --> |
| </target> |
| |
| compile - compile Java sources for the module. |
| |
| jar - build the module JAR. |
| |
| nbm - build the NBM. You might override this to give a complex (multipart) |
| license text. Copy basic impl from common.xml and edit. |
| |
| release - copies contents of ${release.dir} to ${cluster}. |
| |
| The Call-Graph of these targets is |
| |
| "OTHERTARGETS" -> "-pre-TARGET" -> "YOUR-preEXTENSIONS" -> "-do-TARGET" |
| -> "-post-TARGET" -> "YOUR-postEXTENSIONS" -> "TARGET" |
| |
| The "TARGET" itself does nothing. If your existing build.xml has some customization |
| discussed later you may want to update your targets to match the new call-graph. |
| You are encurraged to use the extension mechanism. |
| |
| If you want to keep the original implementation of the other 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-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-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. |
| |
| 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. |
| |
| 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. |
| |
| |
| 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). |
| |
| test-generate-html - similar to the module-level target of the same name, only |
| this executes and reports on all unit and functional tests for all suite |
| modules. [since 7.0] |
| |
| test-view-html - tests all modules in the suite, then opens the browser to |
| display the report generated from the results of those tests. [since 7.0] |
| |
| 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. |
| (This implementation is only available on the update center for NetBeans 7.0.) |
| |
| 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: |