nbm-maven-plugin/src/site/apt/upgrade.apt

~~ 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.