NBM Maven Plugin - Maven 2 NBM Plugin

Netbeans Module plugin

This m2 plugin is able to create Netbeans module(plugin) artifacts. It registers a new packaging type "nbm". Any project with this packaging will be automatically turned into a netbeans module project. Additionally it allows to create clusters of modules, generate an autoupdate site content or build and assemble an application on top of NetBeans platform.

The plugin is also capable of populating the local maven repository with module jars and NBM files from a given NetBeans installation. Useful for module development, modules with public APIs are separated from those without a public API. See the nbm:populate-repository goal and the HOWTO document for details.

To get access to a repository with NetBeans.org module artifacts and metadata, add http://bits.netbeans.org/maven2/ repository to your project POM or the repository manager you are using. The repository hosts binaries of NetBeans 6.5 and later and is only valid for 3.0+ version of nbm-maven-plugin and can produce unexpected results or failed builds for older versions. Please note that the older repository - http://deadlock.netbeans.org/maven2/ is still operational, but hosts only content for older versions of NetBeans and is to be used by 2.x version of nbm-maven-plugin only. If you need NetBeans 6.5 binaries with older version of nbm-maven-plugin or oder versions of NetBeans with new 3.0 nbm-maven-plugin generated metadata, you are encouraged to generate the repository content yourself for use with your company. See instructions for details. For explanation why it's like this, see this blog entry.

Sample pom.xml excerpts for creation of a NetBeans module:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <artifactId>example-netbeans-module</artifactId>
  <groupId>org.mycompany.yproject</groupId>
  <!--here is the packaging and lifecycle defined>
  <packaging>nbm</packaging>

....
  <build>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>nbm-maven-plugin</artifactId>
                <version>3.0</version>
                <extensions>true</extensions>
            </plugin>
            <plugin> <!-- required since nbm-plugin 3.0-->
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>2.2</version>
                <configuration>
                    <useDefaultManifestFile>true</useDefaultManifestFile>
                </configuration>
            </plugin>
        </plugins>
  </build>

 ....
    <!-- this section is important only to access the binaries of netbeans that you use as dependencies -->
    <repositories>
        <repository>
            <id>netbeans</id>
            <name>repository hosting netbeans.org api artifacts</name>
            <url>http://bits.netbeans.org/maven2/</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>

To build the project then, just type

mvn install

Maven Dependency vs NetBeans runtime dependency

There are important differences between Maven's dependency mechanism and NetBeans runtime dependencies. Maven's dependencies are transitive, so at compile time you get not only direct dependencies you declared, but also dependencies of dependencies etc. In Netbeans, the module dependencies are non-transitive by nature, you have to explicitly declare all at runtime. Additionally next to module dependencies there are also library jars attached and shipped with the module's main artifact. In the Netbeans terminology there is a special sort of modules called "Library Wrappers". These library wrappers add the libraries on the module's classpath and allow other modules to depend on the libraries within the IDE's runtime.

The ways in which the nbm-maven-plugin tries to adress these issues has changed over time.

In nbm-maven-plugin 3.0+, we use walk the dependency tree to detect and identify module dependencies and classpath libraries.

A maven dependency is turned into a netbeans runtime dependency when:

for netbeans module dependencies (dependency jars that have the netbeans specific entries in META-INF/MANIFEST.MF)
- It's a direct dependency (non-transitive) and is a netbeans module itself. Preferred way of declaring module dependencies.
- It's defined in existing (though optional) module.xml file in dependencies section. Try to avoid this in 3.0+, but still useful if one wants to put an explicit dependency value on the module, or use implementation dependency.
- When the dependency is of type "nbm". Deprecated in 3.0.x, only helpful in older versions. Such dependencies don't include their transitive deps on compilation classpath. That should allow one to simulate the rumtime dependencies at compilation time in maven, however there's one major drawback. Not only are the nbm's module dependencies hidden, but the libraries associated with the given nbm module are also hidden. So you can end up with less stuff on classpath as opposed to more stuff with "jar typed dependencies.
for module libraries (jars that are packed together with the module and appear on it's classpath directly, not by a dependency relationship.)
- It's a direct dependency and is not of "provided" scope.
- It's a transitive dependency, pulled in by a direct dependency (only non-module one - see first bullet) This is new in 3.0+
- It's defined in existing (though optional) module.xml file in libraries section. Consider this deprecated in 3.0+.

The complete nbm descriptor format documentation, and example descriptors are also available.

Additionally in 3.0+ we perform dependency analysis in order to warn the user when runtime dependencies are wrong. So project's own classes and it's classpath libraries' classes are checked against the module dependencies (with appropriate filtering for public packages/private packages). If the classes depend on declared module dependency's private classes or on transitive module dependency's classes, the build fails. That should prevent ClassNotFoundExceptions later at runtime, when the NetBeans module system constructs the classpath for the module based on our metadata generated.

In nbm-maven-plugin version 2.4 and older, you have to declare the dependencies in maven for compilation and then use the special module descriptor file to define the runtime dependencies and libraries.

In nbm-maven-plugin version 2.5 and 2.6.x, we tried to simplify setting the dependencies and remove redundancies. A few rules had to be introduced in terms of declaring maven dependencies though.

Multi module setup

If you have a set of NetBeans modules, or are building on top of NetBeans platform, you will make use of the additional goals provided by the plugin.

Since 3.0, if you are building a platform based application, you shall use a project with "nbm-application" packaging to perform the final application assembly. This packaging type (defined in nbm-maven-plugin), shall have your module projects and all dependencies of the target netbeans platform included as dependencies.

For the netbeans platform/IDE modules, there are artifacts that aggregate modules in clusters. These are put in the org.netbeans.clusters groupId (on bits.netbeans.org or in your own repository) The following snippet will include the basic netbeans platform cluster and your own module in the application. You can use standard dependency exclusion lists to cut out module from platform that you don't need.

    <artifactId>application</artifactId>
    <packaging>nbm-application</packaging>
    <version>1.0-SNAPSHOT</version>
    <dependencies>
        <dependency>
            <groupId>org.netbeans.cluster</groupId>
            <artifactId>platform8</artifactId>
            <version>${netbeans.version}</version>
            <type>pom</type>
        </dependency>
        <dependency>
            <groupId>com.mycompany</groupId>
            <artifactId>module1</artifactId>
            <version>1.0-SNAPSHOT</version>
        </dependency>
    </dependencies>
    ....

The nbm-aplication project/packaging defines a build lifecycle that creates a final application from the nbm files in local/remote repotories and bundles them in a zip file (also uploadable to the repository) In addition to that you can configure the project to generate an autoupdate site and/or a webstartable binaries of the applications.

            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>nbm-maven-plugin</artifactId>
                <executions>
                    <execution>
                        <id>extra</id>
                        <phase>package</phase>
                        <goals>
                            <goal>autoupdate</goal>
                            <goal>webstart-app</goal>
                        </goals>
                        <configuration>
                            <!--distBase>central::default::http://repo1.maven.org/maven2</distBase-->
                            <codebase>${project.build.directory}/webstart/milos</codebase>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

See the autoupdate and webstart-app goals for more details.

mvn nbm:cluster

This goal aggregates output of multiple netbeans module projects and creates one or more clusters in the current project. So usually one runs this goal on parent pom project, and aggregates the content of all it's modules. The resulting cluster structure can later be used for running the application, creating an installer or similar. A variant of this goal is already included in the nbm-application project build lifecycle in 3.0+ versions.

mvn nbm:branding

Branding is to used when one builds an application based on NetBenans platform (as opposed to creating set of modules for the IDE) Branding contains all the resources that are to be changed in the platform binaries (resource bundles, images, html files etc) to give the application it's unique touch.

This goal can be attached to one of the nbm module projects that will be part of the NetBeans platform based application.

For more detailed tutorial, check the Screencast: Maven and the NetBeans Platform video recorded by Fabrizio Giudici. It describes to Fabrizio's open source project ForceTen which can be used as reference setup for Maven NetBeans Platform based apps.

Please note that in 3.x version, the branding shall be included as part of a regular nbm subproject and cannot be attached to a "pom" packaged root project.

mvn nbm:run-ide nbm:run-platform

These two goals do almost the same, they allow you to execute your projects content within the IDE or NetBeans platform.

In version 3.0.x, the nbm:run-platform makes only sense to execute on projects with nbm-application packaging.

For more information on plugin configuration and customization, see goal documentation.

Archetypes anyone?

There are 2 basic archetypes:

The first once creates a single project preconfigured to be a NetBeans module. Use this one if you are developing a NetBeans IDE module or a module for NetBeans platform based application module.

mvn -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=nbm-archetype -DarchetypeVersion=1.1 -DarchetypeRepository=http://repo1.maven.org/maven2 -DgroupId=org.kleint -DartifactId=milos -Dversion=1.0 archetype:generate

The second one creates a parent pom project containing configuration and application branding for your NetBeans platform based application. Additionally it contains a sample empty module.

mvn -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=netbeans-platform-app-archetype -DarchetypeVersion=1.1 -DarchetypeRepository=http://repo1.maven.org/maven2 -DgroupId=org.kleint -DartifactId=milos -Dversion=1.0 archetype:generate

Note: If you are looking for archetypes for older versions of the nbm-plugin (2.6.x), grab the 1.0.x versions of the archetypes.

IDE support

Since NetBeans IDE 6.0, Maven support available on the default update center. Among other features, it contains additional support for working with Netbeans module projects. The support includes file templates, important nodes in projects view, running module(s) in IDE or platform. Please note that support for projects with nbm-application packaging might be limited in current (NetBeans 6.5) released version.

Sample real life application

Check the Screencast: Maven and the NetBeans Platform video recorded by Fabrizio Giudici. It describes to Fabrizio's open source project ForceTen which can be used as reference setup for Maven NetBeans Platform based apps.

Overview