| ~~ Licensed to the Apache Software Foundation (ASF) under one |
| ~~ or more contributor license agreements. See the NOTICE file |
| ~~ distributed with this work for additional information |
| ~~ regarding copyright ownership. The ASF licenses this file |
| ~~ to you under the Apache License, Version 2.0 (the |
| ~~ "License"); you may not use this file except in compliance |
| ~~ with the License. You may obtain a copy of the License at |
| ~~ |
| ~~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~~ |
| ~~ Unless required by applicable law or agreed to in writing, |
| ~~ software distributed under the License is distributed on an |
| ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~~ KIND, either express or implied. See the License for the |
| ~~ specific language governing permissions and limitations |
| ~~ under the License. |
| |
| ------ |
| Maven 2 NBM Plugin |
| ------ |
| Milos Kleint |
| <mkleint@codehaus.org> |
| ------ |
| 2007-06-15 Sep 30, 2008 Jun 15, 2007 |
| |
| |
| HOW TO: Migrate from older version of the plugin |
| |
| |
| {{{Upgrading_to_3.9} Upgrading to 3.9}} |
| |
| {{{Upgrading_to_3.8} Upgrading to 3.8}} |
| |
| {{{Upgrading_from_2.6_version_to_3.0} Upgrading from 2.6 to 3.0}} |
| |
| {{{Upgrading_from_2.4_version_to_2.5} Upgrading from 2.4 to 2.5}} |
| |
| {Upgrading to 3.9} |
| |
| In 3.9, the <<<populate-repository>>> goal is moved to separate plugin. |
| |
| {Upgrading to 3.8} |
| |
| In 3.8 the <<<descriptor>>> parameter is deprecated and is replaced by equivalent plugin parameters. |
| The values from descriptor are still applied, warnings are printed. In future releases the parameter will be removed. |
| |
| {Upgrading from 2.6 version to 3.0} |
| |
| There are a few significant incompatible changes introduced in <<3.0's>> version of |
| NBM packaging lifecycle. The result should be easier to setup builds and better support for building |
| NetBeans platform based applications. |
| |
| * The lifecycle mappings have changed. There is no more <<<nbm:jar>>> goal and |
| it was replaced by <<<nbm:manifest>>> which is executed at different phase, namely <<<process-classes>>>, right after |
| the module's classes are compiled. |
| |
| <<Important>>: In order to have maven-jar-plugin to pick up the generated manifest, you need to add the following |
| configuration snippet to your projects with <<<nbm>>> packaging. |
| |
| +-----+ |
| <plugin> |
| <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> |
| +-----+ |
| |
| * The project's dependencies that shall end up on <<Class-Path>> of the module and |
| now processed transitively. In earlier versions, you had to either explicitly list |
| all such items in the pom as direct dependencies, or list them in the module descriptor. |
| Only transitive dependencies that descend from non-NetBeans module direct dependencies are |
| included, eg. if you depend on module that includes Apache's commons-httpclient, the library will not |
| be included (unless defined in your project directly). Possible trouble makers are transitive depedencies that are |
| defined both in a dependening module and a regular jar dependency. Based on Maven dependency tree resolution, |
| the binary could end up on the <<Class-Path>> or not. The resolution to the problem is to define |
| The troubled dependency directly and either define the scope as <<<provided>>> if you don't want it included in <<Class-Path>>, |
| or keep the default <<<compile>>> scope if you want. |
| |
| * NBM file is always generated for any NetBeans module project. You can skip the NBM file |
| generation by setting the parameter to nbm:nbm goal, but please be aware that having NBM files in local and |
| remote repositories is crucial for the new tools that create a NetBeans Platform based application |
| binaries. |
| |
| * In previous versions the ultimate final binary for the platform based application, |
| was a directory with the cluster(s) of modules. Now a new packaging is defined <<<nbm-application>>> that |
| allows for creating a final application zip file, webstartable jnlp files, and an update site. |
| All are constructed solely from the repository content (assuming all relevant modules have NBM files in repositories) |
| and the primary project for the binaries is the <<<nbm-application>>> packaging project, unlike in previous versions |
| where the root pom was the primary project and required all included modules to be built as part of the reactor |
| in the same build. |
| |
| * The <<<nbm:manifest>>> goal besides generating the manifest, will also check if the runtime dependencies |
| match the actual classes being used in the project and it's libraries on <<Class-Path>>. That's analogous to |
| the {{{http://maven.apache.org/plugins/maven-dependency-plugin/analyze-mojo.html}<<<dependency:analyze>>>}} |
| goal but takes the NetBeans module system constraints into account (non-transitivity of module dependencies, |
| public vs. private packages constraint etc) |
| |
| * The previous versions didn't define the <<<OpenIDE-Module-Public-Packages>>> entry in the manifest file. |
| The result was a deprecated state that made all classes publicly accessible from other modules |
| and printed a warning to the application's log file. In <<3.0>>, we introduced a new optional parameter <<<publicPackages>>> |
| that lists all public packages in the module. If not defined, no package is exported as public. See |
| {{{https://github.com/mojohaus/nbm-maven-plugin/issues/3}issue}} for details. If you have previously |
| placed the <<OpenIDE-Module-Public-Packages>> entry in the manifest file manually, it will not be overriden by the new parameter. |
| |
| ======================================================================= |
| |
| {Upgrading from 2.4 version to 2.5} |
| |
| There are significant changes in how NetBeans module system dependencies are mapped to maven's own |
| dependencies model. The <<2.4>> and older version all module system deps had to be explicitly defined in the module descriptor at <<<src/main/nbm/module.xml>>>. |
| That is no longer a requirement in <<2.5>> for most cases. The plugin will try to decide based on the declaration |
| in maven POM file. |
| |
| These are the rules: |
| |
| * for NetBeans module dependencies (jars that have the NetBeans specific entries in META-INF/MANIFEST.MF) |
| |
| * It's defined in existing (though optional) <<<module.xml>>> file in <<<dependencies>>> section. |
| |
| * It's a direct dependency (non-transitive) and is a NetBeans module. |
| |
| * When the dependency is of type <<<nbm>>>. Such dependencies don't include their transitive deps on compilation classpath. |
| |
| * 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 defined in existing (though optional) <<<module.xml>>> file in <<<libraries>>> section |
| |
| * It's a direct dependency (non-transitive) and is not of <<<provided>>> scope. |
| |
| So if you have used <<2.4>> and older before, you need to check your dependencies when upgrading to <<2.5>>. |
| |
| * The <<2.5>> plugin can pick up and declare more module dependencies than the previous version. Module dependencies are safe. |
| You either declared them in your <<<module.xml>>> file. Some additional ones can appear if you have them as direct dependencies in your pom. |
| Use the {{{http://maven.apache.org/plugins/maven-dependency-plugin/analyze-mojo.html}<<<dependency:analyze>>>}} goal to check for used/unused direct dependencies. |
| |
| * The <<2.5>> plugin can also pick up and declare more module libraries. That's something to watch out for! That happens again only when you declared the jars as direct dependencies. |
| You could end up with a single jar being added to multiple modules and get runtime classpath issues and of course your download size |
| will get higher than necessary. Again the {{{http://maven.apache.org/plugins/maven-dependency-plugin/analyze-mojo.html}<<<dependency:analyze>>>}} goal shall help. If you know the jar is required but is provided by a module you depend on, use the <<<provided>>> scope to prevent inclusion. |
| |