Creating Modules with Ant

Rather than creating modules using the JAR Packager and testing them that way, you may prefer to use the Ant build system. (Consult the IDE's general documentation for more on how to use Ant from within the IDE, and also the bundled Ant manual.) Generally, using the JAR Packager will be quickest and most convenient for small or structurally simple modules, while using Ant requires more setup work but is potentially more powerful and scriptable.

To start out, you may wish to create a new build script for the module. Select Templates | NetBeans Extensions | Modules API | Ant Script for Module to begin. The template is set up to assume you have sources for the module mounted in the same filesystem as the build script, but of course you can adjust various paths to accommodate different setups.

Explanation of Targets

compile Target

This target builds your Java classes from source. The classpath will need to contain at least lib/openide.jar from the IDE installation for Open-API-based sources to compile; the script template uses ${netbeans.class.path} to make sure all NetBeans startup JARs are included in the classpath when compiling from inside the IDE, but to make the script portable you should replace this with a specific path to the required libraries (or a variable with the path) when you get a chance.

jars Target

Simply builds a JAR file from sources, excluding source-only files such as *.java. The JAR must be created with a manifest, so use the template Module Manifest. The manifest file can be edited with live syntax checking and so on for your convenience; see Browsing Modules for more details.

test Target

This is the fun part - reloading your module into the IDE dynamically. First we create a module JAR for testing purposes. You can just use the jars target and use that same JAR, but there are some advantages to having a separate testing JAR vs. the production JAR: keeping junk files out of the production directory; and ability to reload JavaHelp and extensions.

So the JAR creation step looks similar to that used for a production JAR. However if your module has any JavaHelp, you should include it in the test JAR; this lets you reload the module and check out changes to documentation. Also, if you use some Class-Path extension libraries as documented in the Modules API, these must be available to the test JAR in the indicated relative position. If these are fixed JARs you do not develop, you could just place them alongside the test JAR (with the correct relative file names). But if you develop the extensions yourself, you can reload them too: just include their contents directly in the module JAR for testing purposes. The production JAR should of course not do this.

Finally, use the <nbinstaller> task to reload the module. This task is only defined when running inside the IDE. You must pass it an action, where currently only reinstall is permitted; and a module (path to JAR file). It should install the JAR (if it was not loaded before) or reinstall (if it was).

It works to test changes to a module that you already have installed normally; just make the test JAR elsewhere (in your sources, say) and use the installer task: the IDE will load the test JAR and will remember this even after restarts.

If you have more than one module to test, you can include multiple calls to the installer task. Note that if module A depends on B, both are enabled, and you reinstall B, then actually both modules will be reinstalled in the natural nesting order.

nbm Target

Sample Ant code to create an NBM file suitable for use with the Auto Update feature. Refer to the NetBeans website for more details on building NBM files with Ant.

clean Target

Cleans out all files created by the build script which are not part of source.