| <!DOCTYPE html> |
| |
| <html class="no-js" lang="en" dir="ltr"> |
| <head> |
| <meta charset="utf-8"> |
| <meta http-equiv="x-ua-compatible" content="ie=edge"> |
| <title>Apache NetBeans Maven Utilities - NBM Maven Plugin – Maven 2 NBM Plugin</title> |
| <link rel="stylesheet" href="./css/netbeans.css" /> |
| <link href="https://fonts.googleapis.com/css?family=Lato:400,700" rel="stylesheet"> |
| </head> |
| <body> |
| <div class="top-bar" id="responsive-menu"> |
| <div class='top-bar-left'> |
| <a class='title' href="http://netbeans.apache.org"><img src='/images/apache-netbeans.svg' style='padding: 8px; height: 48px;'>Apache NetBeans (incubating)</a> |
| </div> |
| <div class="top-bar-right"> |
| <ul class="vertical medium-horizontal menu" style="right: 90px;" data-responsive-menu="drilldown medium-dropdown"> |
| <li> <a href="../nb-repository/index.html">NB Repository Plugin</a> </li> |
| <li> <strong style='line-height: 1;margin-bottom: 0;padding: 0.7rem 1rem;display: block;' >NBM Plugin</strong> </li> |
| <li> <a href="../shared/index.html">Shared</a> </li> |
| <li> <a href="../parent/index.html">Parent</a> </li> |
| </ul> |
| </div> |
| </div> |
| <div class='grid-container main-content'> |
| <div id="toc" class="toc"> |
| <div id="toctitle">Overview</div> |
| <ul class="sectlevel1"> |
| <li><a href="index.html">Usage</a></li> |
| <li><a href="plugin-info.html">Plugin Goals</a></li> |
| </ul> |
| <div id="toctitle">HOWTOs</div> |
| <ul class="sectlevel1"> |
| <li><a href="buildinstexample.html">Customize installers</a></li> |
| <li><a href="upgrade.html">Upgrade from older versions</a></li> |
| </ul> |
| <div id="toctitle">Deprecated</div> |
| <ul class="sectlevel1"> |
| <li><a href="nbm.html">Descriptor Format</a></li> |
| <li><a href="descriptor.html">Example Descriptor</a></li> |
| </ul> |
| </div> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="section"> |
| <h2><a name="NetBeans_Module_plugin"></a>NetBeans Module plugin</h2> |
| <p>This m2 plugin is able to create NetBeans module(plugin) artifacts. It registers a new packaging type <tt>nbm</tt>. 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.</p> |
| <p>Note: The <tt>nbm:populate-repository</tt> goal has been moved to it's own plugin <a href="../nb-repository-plugin/index.html">nb-repository-plugin</a>.</p> |
| <p>To get access to a repository with NetBeans.org module artifacts and metadata, add <a class="externalLink" href="http://bits.netbeans.org/maven2/">http://bits.netbeans.org/maven2/</a> repository to your project POM or the repository manager you are using. The repository hosts binaries of NetBeans 6.5 and later.</p> |
| <p>Also see: <a class="externalLink" href="http://wiki.netbeans.org/NetBeansDeveloperFAQ#Mavenized_Builds">Maven NBM development FAQs</a></p> |
| <p>Sample <tt>pom.xml</tt> excerpts for creation of a NetBeans module:</p> |
| <div class="source"> |
| <pre><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/xsd/maven-4.0.0.xsd"> |
| <modelVersion>4.0.0</modelVersion> |
| <artifactId>example-netbeans-module</artifactId> |
| <groupId>org.mycompany.myproject</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>4.2-SNAPSHOT</version> |
| <extensions>true</extensions> |
| </plugin> |
| <plugin> <!-- required since nbm-plugin 3.0--> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-jar-plugin</artifactId> |
| <version>3.0.2</version> |
| <configuration> |
| <archive> |
| <manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile> |
| </archive> |
| </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></pre></div> |
| <p>To build the project then, just type</p> |
| <div class="source"> |
| <pre>mvn install</pre></div></div> |
| <div class="section"> |
| <h2><a name="Maven_Dependency_vs._NetBeans_runtime_dependency"></a>Maven Dependency vs. NetBeans runtime dependency</h2> |
| <p>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.</p> |
| <p>The ways in which the nbm-maven-plugin tries to adress these issues has changed over time.</p> |
| <p>The plugin walks the dependency tree to detect and identify module dependencies and classpath libraries.</p> |
| <p>A maven dependency is turned into a NetBeans runtime dependency when:</p> |
| <ul> |
| <li>for NetBeans module dependencies (dependency jars that have the NetBeans specific entries in META-INF/MANIFEST.MF) |
| <ul> |
| <li>It's a direct dependency (non-transitive) and is a NetBeans module itself. Preferred way of declaring module dependencies. </li> |
| <li>It's defined in existing (though optional) module.xml file in <tt>dependencies</tt> section. Try to avoid this, but still useful if one wants to put an explicit dependency value on the module, or use implementation dependency.</li> |
| <li>When the dependency is of type <tt>nbm</tt>. 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 <tt>jar typed dependencies</tt>.</li></ul></li> |
| <li>for module libraries (jars that are packed together with the module and appear on it's classpath directly, not by a dependency relationship.) |
| <ul> |
| <li>It's a direct dependency and is not of <tt>provided</tt> scope.</li> |
| <li>It's a transitive dependency, pulled in by a direct dependency (only non-module one - see first bullet) This is new in <b>3.0+</b></li> |
| <li>It's defined in existing (though optional) module.xml file in <i>libraries</i> section. Consider this deprecated in <b>3.0+</b>.</li></ul></li></ul> |
| <p>The complete <a href="./nbm.html">nbm descriptor format</a> documentation, and <a href="./descriptor.html">example descriptors</a> are also available. Please note that since 3.8 version, the descriptor is deprecated and replaced by plugin configuration parameters.</p> |
| <p>Additionally 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 ClassNotFoundException's later at runtime, when the NetBeans module system constructs the classpath for the module based on our metadata generated.</p></div> |
| <div class="section"> |
| <h2><a name="Using_OSGi_bundles_in_NetBeans_platform_based_applications"></a>Using OSGi bundles in NetBeans platform based applications</h2> |
| <p>Starting with version <b>3.2</b>, it's possible for the NetBeans modules to depend on OSGi bundles. A proper module dependency section will be generated. To include the bundle in the application, add dependency on the bundle from nbm-application. There are a few prerequisites.</p> |
| <ul> |
| <li>It works only in NetBeans 6.9 and later which support the embedding of bundles at runtime</li> |
| <li>Add <tt><useOSGiDependencies>true</useOSGiDependencies></tt> configuration entry to all the modules depending on OSGi bundles. Existing applications/modules need to check modules wrapping external libraries for library jars that are also OSGi bundles. Such modules will no longer include the OSGi bundles as part of the module NBM but will include a modular dependency reference on the bundle only. Modules depending on these old wrapper modules shall depend directly on the bundle, eventually rendering the old library wrapper module obsolete.</li> |
| <li>in the distribution, all bundles will be included in the default cluster (<tt>extra</tt> if not configured otherwise), in <b>3.10 and later</b> the plugin will attempt to guess the cluster based on modules depending on it.</li> |
| <li>Before version <b>3.10</b> all bundles will be autoload, thus requiring at least one depending regular module to enable them. In <b>3.10 and later</b>, developers of the OSGi bundles can influence the autoload vs regular behaviour by adding <b>Nbm-Maven-Plugin-Autoload</b> attribute to the bundle's manifest with "true" or "false" values. False means the module will be enabled on start, even without any other modules depending on it.</li></ul></div> |
| <div class="section"> |
| <h2><a name="Multi_module_setup"></a>Multi module setup</h2> |
| <p>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.</p> |
| <p>If you are building a Platform-based application, use a project with <tt>nbm-application</tt> packaging to perform the final application assembly. This packaging type (defined in nbm-maven-plugin) should have your module projects and all dependencies of the target NetBeans Platform included as dependencies.</p> |
| <p>For the NetBeans Platform/IDE modules, there are artifacts that aggregate modules in clusters. These are put in the <tt>org.netbeans.clusters</tt> groupId (on <tt>bits.netbeans.org</tt> 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 modules from the Platform that you don't need.</p> |
| <div class="source"> |
| <pre> <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> |
| ....</pre></div> |
| <p>The nbm-application 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 webstartable binaries of the applications (typically in a deployment profile):</p> |
| <div class="source"> |
| <pre> <plugin> |
| <groupId>org.codehaus.mojo</groupId> |
| <artifactId>nbm-maven-plugin</artifactId> |
| <executions> |
| <execution> |
| <id>extra</id> |
| <goals> |
| <goal>autoupdate</goal> |
| <goal>webstart-app</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin></pre></div> |
| <p>See the <a href="./autoupdate-mojo.html">autoupdate</a> and <a href="./webstart-app-mojo.html">webstart-app</a> goals for more details.</p> |
| <div class="source"> |
| <pre>mvn nbm:cluster</pre></div> |
| <p>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 the parent POM project, which aggregates the content of all its modules. The resulting cluster structure can later be used for running the application, creating an installer or similar. A variant of this goal is also included in the nbm-application project's default lifecycle.</p> |
| <div class="source"> |
| <pre>mvn nbm:branding</pre></div> |
| <p>Branding is to used when one builds an application based on NetBeans 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 its unique look.</p> |
| <p>This goal can be attached to one of the nbm module projects that will be part of the NetBeans Platform-based application.</p> |
| <p>For more detailed tutorial, check the <a class="externalLink" href="http://netbeans.dzone.com/videos/screencast-maven-and-netbeans">Screencast: Maven and the NetBeans Platform</a> video recorded by Fabrizio Giudici. It describes to Fabrizio's open source project <a class="externalLink" href="http://kenai.com/projects/forceten">ForceTen</a> which can be used as reference setup for Maven NetBeans Platform based apps.</p> |
| <p>The branding is included as part of a regular nbm subproject and cannot be attached to a <tt>pom</tt> packaged root project.</p> |
| <div class="source"> |
| <pre>mvn nbm:run-ide nbm:run-platform</pre></div> |
| <p>These two goals do almost the same, they allow you to execute your projects content within the IDE or NetBeans platform.</p> |
| <p><tt>nbm:run-platform</tt> only makes sense to execute on projects with <tt>nbm-application</tt> packaging.</p> |
| <p>For more information on plugin configuration and customization, see <a href="./plugin-info.html">goal documentation</a>.</p></div> |
| <div class="section"> |
| <h2><a name="Public_packages_declaration"></a>Public packages declaration</h2> |
| <p>By default all your module's packages (and classes) and private to the given module. If you want to expose any API to other modules, you will need to declare those public packages in your <tt>pom.xml</tt>. This includes not only your own classes but also any other 3rd party library classes that are packaged with your module and are to be exposed for reuse by other modules.</p> |
| <p>For example:</p> |
| <div class="source"> |
| <pre> <plugin> |
| <groupId>org.codehaus.mojo</groupId> |
| <artifactId>nbm-maven-plugin</artifactId> |
| <version>4.2-SNAPSHOT</version> |
| <extensions>true</extensions> |
| <configuration> |
| <publicPackages> |
| <publicPackage>org.foo.api</publicPackage> |
| <publicPackage>org.apache.commons.*</publicPackage> |
| </publicPackages> |
| </configuration> |
| </plugin></pre></div> |
| <p>there is a package <tt>org.foo.api</tt> made public (but not <tt>org.foo.api.impl</tt> package) and any package starting with <tt>org.apache.commons</tt>, so both <tt>org.apache.commons.io</tt> and <tt>org.apache.commons.exec</tt> packages are exposed to the outside</p></div> |
| <div class="section"> |
| <h2><a name="Archetypes_anyone.3F"></a>Archetypes anyone?</h2> |
| <p>There are two basic archetypes:</p> |
| <p>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 a NetBeans Platform-based application.</p> |
| <div class="source"> |
| <pre>mvn -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=nbm-archetype -DarchetypeVersion=... \ |
| -DgroupId=org.kleint -DartifactId=milos -Dversion=1.0 archetype:generate</pre></div> |
| <p>The second one creates a parent POM project containing configuration and application branding for your NetBeans Platform-based application.</p> |
| <div class="source"> |
| <pre>mvn -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=netbeans-platform-app-archetype \ |
| -DarchetypeVersion=... -DgroupId=org.kleint -DartifactId=milos -Dversion=1.0 archetype:generate</pre></div></div> |
| <div class="section"> |
| <h2><a name="IDE_support"></a>IDE support</h2> |
| <p>The NetBeans IDE has Maven support. 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 the IDE or Platform.</p></div> |
| <div class="section"> |
| <h2><a name="Sample_real_life_application"></a>Sample real life application</h2> |
| <p>Check the <a class="externalLink" href="http://netbeans.dzone.com/videos/screencast-maven-and-netbeans">Screencast: Maven and the NetBeans Platform</a> video recorded by Fabrizio Giudici. It describes to Fabrizio's open source project <a class="externalLink" href="http://kenai.com/projects/forceten">ForceTen</a> which can be used as reference setup for Maven NetBeans Platform based apps.</p></div> |
| </div> |
| </div> |
| </div> |
| <div class='grid-container incubator-area' style='margin-top: 64px'> |
| <div class='grid-x grid-padding-x'> |
| <div class='large-auto cell text-center'> |
| <a href="https://www.apache.org/"> |
| <img style="width: 320px" title="Apache Software Foundation" src="/images/asf_logo_wide.svg" /> |
| </a> |
| </div> |
| <div class='large-auto cell text-center'> |
| <a href="https://www.apache.org/events/current-event.html"> |
| <img style="width:234px; height: 60px;" title="Apache Software Foundation current event" src="https://www.apache.org/events/current-event-234x60.png"/> |
| </a> |
| </div> |
| </div> |
| </div> |
| <div class='footer-disclaimer'> |
| <div class="footer-disclaimer-content"> |
| <p>Copyright © 2017-2018 <a href="https://www.apache.org">The Apache Software Foundation</a>.</p> |
| <p>Licensed under the Apache <a href="https://www.apache.org/licenses/">license</a>, version 2.0</p> |
| <p><a href="https://incubator.apache.org/" alt="Apache Incubator"><img src='/images/incubator_feather_egg_logo_bw_crop.png' title='Apache Incubator'></img></a></p> |
| <div style='max-width: 40em; margin: 0 auto'> |
| <p>Apache NetBeans is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.</p> |
| <p>Apache Incubator, Apache, the Apache feather logo, the Apache NetBeans logo, and the Apache Incubator project logo are trademarks of <a href="https://www.apache.org">The Apache Software Foundation</a>.</p> |
| <p>Oracle and Java are registered trademarks of Oracle and/or its affiliates.</p> |
| </div> |
| |
| </div> |
| </div> |
| <a href="https://github.com/apache/incubator-netbeans-mavenutils"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_green_007200.png" alt="Fork me on GitHub"></a> |
| |
| |
| |
| <script src="/js/vendor/jquery-3.2.1.min.js"></script> |
| <script src="/js/vendor/what-input.js"></script> |
| <script src="/js/vendor/jquery.colorbox-min.js"></script> |
| <script src="/js/vendor/foundation.min.js"></script> |
| <script src="/js/netbeans.js"></script> |
| <script> |
| |
| $(function(){ $(document).foundation(); }); |
| </script> |
| </body> |
