X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fdeveloper-guide%2Fodl-parent-developer-guide.rst;h=b265136fbc03cafbb201f66f52595a94fcc44a84;hb=d7b9834ced1002df0ac1ec8d67b394cc6ec7e499;hp=66b6e8c8183b8c001930d2ee7f16a98a429f0853;hpb=7263d800d129ea81a1a4fdccdfe40c7b6a4b3fbf;p=docs.git

diff --git a/docs/developer-guide/odl-parent-developer-guide.rst b/docs/developer-guide/odl-parent-developer-guide.rst
index 66b6e8c81..b265136fb 100644
--- a/docs/developer-guide/odl-parent-developer-guide.rst
+++ b/docs/developer-guide/odl-parent-developer-guide.rst
@@ -1,3 +1,5 @@
+.. _odl-parent-developer-guide:
+
 ODL Parent Developer Guide
 ==========================
 
@@ -13,7 +15,7 @@ OpenDaylight ecosystem. Technically, the aim of projects in OpenDaylight
 is to produce Karaf features, and these parent projects provide common
 support for the different types of projects involved.
 
-| These parent projects are:
+These parent projects are:
 
 -  ``odlparent-lite`` — the basic parent POM for Maven modules which
    don’t produce artifacts (*e.g.* aggregator POMs)
@@ -24,15 +26,32 @@ support for the different types of projects involved.
 -  ``bundle-parent`` — the parent POM for Maven modules producing OSGi
    bundles
 
--  ``features-parent`` — the parent POM for Maven modules producing
-   Karaf features
+The following parent projects are deprecated, but still used in Carbon:
+
+-  ``feature-parent`` — the parent POM for Maven modules producing
+   Karaf 3 feature repositories
+
+-  ``karaf-parent`` — the parent POM for Maven modules producing Karaf 3
+   distributions
+
+The following parent projects are new in Carbon, for Karaf 4 support (which
+won’t be complete until Nitrogen):
+
+-  ``single-feature-parent`` — the parent POM for Maven modules producing
+   a single Karaf 4 feature
+
+-  ``feature-repo-parent`` — the parent POM for Maven modules producing
+   Karaf 4 feature repositories
+
+-  ``karaf4-parent`` — the parent POM for Maven modules producing Karaf 4
+   distributions
 
 odlparent-lite
 ~~~~~~~~~~~~~~
 
-| This is the base parent for all OpenDaylight Maven projects and
-  modules. It provides the following, notably to allow publishing
-  artifacts to Maven Central:
+This is the base parent for all OpenDaylight Maven projects and
+modules. It provides the following, notably to allow publishing
+artifacts to Maven Central:
 
 -  license information;
 
@@ -95,12 +114,12 @@ odlparent
 This inherits from ``odlparent-lite`` and mainly provides dependency and
 plugin management for OpenDaylight projects.
 
-| If you use any of the following libraries, you should rely on
-  ``odlparent`` to provide the appropriate versions:
+If you use any of the following libraries, you should rely on
+``odlparent`` to provide the appropriate versions:
 
 -  Akka (and Scala)
 
--  | Apache Commons:
+-  Apache Commons:
 
    -  ``commons-codec``
 
@@ -120,13 +139,13 @@ plugin management for OpenDaylight projects.
 
 -  JAX-RS with Jersey
 
--  | JSON processing:
+-  JSON processing:
 
    -  GSON
 
    -  Jackson
 
--  | Logging:
+-  Logging:
 
    -  Logback
 
@@ -134,13 +153,13 @@ plugin management for OpenDaylight projects.
 
 -  Netty
 
--  | OSGi:
+-  OSGi:
 
    -  Apache Felix
 
    -  core OSGi dependencies (``core``, ``compendium``\ …)
 
--  | Testing:
+-  Testing:
 
    -  Hamcrest
 
@@ -154,7 +173,7 @@ plugin management for OpenDaylight projects.
 
    -  PowerMock
 
--  | XML/XSL:
+-  XML/XSL:
 
    -  Xerces
 
@@ -224,8 +243,8 @@ ASL-licensed:
 bundle-parent
 ~~~~~~~~~~~~~
 
-| This inherits from ``odlparent`` and enables functionality useful for
-  OSGi bundles:
+This inherits from ``odlparent`` and enables functionality useful for
+OSGi bundles:
 
 -  ``maven-javadoc-plugin`` is activated, to build the Javadoc JAR;
 
@@ -240,12 +259,12 @@ scope.
 features-parent
 ~~~~~~~~~~~~~~~
 
-| This inherits from ``odlparent`` and enables functionality useful for
-  Karaf features:
+This inherits from ``odlparent`` and enables functionality useful for
+Karaf features:
 
 -  ``karaf-maven-plugin`` is activated, to build Karaf features — but
    for OpenDaylight, projects need to use “jar” packaging (**not**
-   “kar”);
+   “feature” or “kar”);
 
 -  ``features.xml`` files are processed from templates stored in
    ``src/main/features/features.xml``;
@@ -285,38 +304,97 @@ dependencies, bundle dependencies and configuration files. They must be
 specified traditionally (either hard-coded, or using Maven properties)
 for feature dependencies.
 
-Features
---------
+karaf-parent
+~~~~~~~~~~~~
+
+This allows building a Karaf 3 distribution, typically for local testing
+purposes. Any runtime-scoped feature dependencies will be included in the
+distribution, and the ``karaf.localFeature`` property can be used to
+specify the boot feature (in addition to ``standard``).
+
+single-feature-parent
+~~~~~~~~~~~~~~~~~~~~~
+
+This inherits from ``odlparent`` and enables functionality useful for
+Karaf 4 features:
+
+-  ``karaf-maven-plugin`` is activated, to build Karaf features, typically
+   with “feature” packaging (“kar” is also supported);
+
+-  ``feature.xml`` files are generated based on the compile-scope dependencies
+   defined in the POM, optionally initialised from a stub in
+   ``src/main/feature/feature.xml``.
+
+-  Karaf features are tested after build to ensure they can be activated
+   in a Karaf container.
+
+The ``feature.xml`` processing adds transitive dependencies by default, which
+allows features to be defined using only the most significant dependencies
+(those that define the feature); other requirements are determined
+automatically as long as they exist as Maven dependencies.
+
+“configfiles” need to be defined both as Maven dependencies (with the
+appropriate type and classifier) and as ``<configfile>`` elements in the
+``feature.xml`` stub.
+
+Other features which a feature depends on need to be defined as Maven
+dependencies with type “xml” and classifier “features” (note the plural here).
+
+feature-repo-parent
+~~~~~~~~~~~~~~~~~~~
+
+This inherits from ``odlparent`` and enables functionality useful for
+Karaf 4 feature repositories. It follows the same principles as
+``single-feature-parent``, but is designed specifically for repositories
+and should be used only for this type of artifacts.
+
+It builds a feature repository referencing all the (feature) dependencies
+listed in the POM.
+
+karaf4-parent
+~~~~~~~~~~~~~
 
-The ODL Parent component for OpenDaylight provides a number of Karaf
-features which can be used by other Karaf features to use certain
+This allows building a Karaf 4 distribution, typically for local testing
+purposes. Any runtime-scoped feature dependencies will be included in the
+distribution, and the ``karaf.localFeature`` property can be used to
+specify the boot feature (in addition to ``standard``).
+
+Features (for Karaf 3)
+----------------------
+
+The ODL Parent component for OpenDaylight provides a number of Karaf 3
+features which can be used by other Karaf 3 features to use certain
 third-party upstream dependencies.
 
-| These features are:
+These features are:
 
--  | Akka features (in the ``features-akka`` repository):
+-  Akka features (in the ``features-akka`` repository):
 
    -  ``odl-akka-all`` — all Akka bundles;
 
-   -  ``odl-akka-scala`` — Scala runtime for OpenDaylight;
+   -  ``odl-akka-scala-2.11`` — Scala runtime for OpenDaylight;
 
-   -  ``odl-akka-system`` — Akka actor framework bundles;
+   -  ``odl-akka-system-2.4`` — Akka actor framework bundles;
 
-   -  ``odl-akka-clustering`` — Akka clustering bundles and
+   -  ``odl-akka-clustering-2.4`` — Akka clustering bundles and
       dependencies;
 
-   -  ``odl-akka-leveldb`` — LevelDB;
+   -  ``odl-akka-leveldb-0.7`` — LevelDB;
 
-   -  ``odl-akka-persistence`` — Akka persistence;
+   -  ``odl-akka-persistence-2.4`` — Akka persistence;
 
 -  general third-party features (in the ``features-odlparent``
    repository):
 
-   -  ``odl-netty`` — all Netty bundles;
+   -  ``odl-netty-4`` — all Netty bundles;
+
+   -  ``odl-guava-18`` — Guava 18;
+
+   -  ``odl-guava-21`` — Guava 21 (not indended for use in Carbon);
 
-   -  ``odl-guava`` — Guava;
+   -  ``odl-lmax-3`` — LMAX Disruptor;
 
-   -  ``odl-lmax`` — LMAX Disruptor.
+   -  ``odl-triemap-0.2`` — Concurrent Trie HashMap.
 
 To use these, you need to declare a dependency on the appropriate
 repository in your ``features.xml`` file:
@@ -355,14 +433,14 @@ assuming the appropriate dependency management:
             <dependency>
                 <groupId>org.opendaylight.odlparent</groupId>
                 <artifactId>odlparent-artifacts</artifactId>
-                <version>1.7.0-SNAPSHOT</version>
+                <version>1.8.0-SNAPSHOT</version>
                 <scope>import</scope>
                 <type>pom</type>
             </dependency>
         </dependencies>
     </dependencyManagement>
 
-(the version number there is appropriate for Boron). For the time being
+(the version number there is appropriate for Carbon). For the time being
 you also need to depend separately on the individual JARs as
 compile-time dependencies to build your dependent code; the relevant
 dependencies are managed in ``odlparent``'s dependency management.
@@ -377,3 +455,55 @@ dependencies are managed in ``odlparent``'s dependency management.
 
 -  ``odl-lmax``: ``[3.3.4,4.0.0)``
 
+Features (for Karaf 4)
+----------------------
+
+There are equivalent features to all the Karaf 3 features, for Karaf 4.
+The repositories use “features4” instead of “features”, and the features
+use “odl4” instead of “odl”.
+
+The following new features are specific to Karaf 4:
+
+-  Karaf wrapper features (also in the ``features4-odlparent``
+   repository) — these can be used to pull in a Karaf feature
+   using a Maven dependency in a POM:
+
+   -  ``odl-karaf-feat-feature`` — the Karaf ``feature`` feature;
+
+   -  ``odl-karaf-feat-jdbc`` — the Karaf ``jdbc`` feature;
+
+   -  ``odl-karaf-feat-jetty`` — the Karaf ``jetty`` feature;
+
+   -  ``odl-karaf-feat-war`` — the Karaf ``war`` feature.
+
+To use these, all you need to do now is add the appropriate dependency
+in your feature POM; for example:
+
+::
+
+    <dependency>
+        <groupId>org.opendaylight.odlparent</groupId>
+        <artifactId>odl4-guava-18</artifactId>
+        <classifier>features</classifier>
+        <type>xml</type>
+    </dependency>
+
+assuming the appropriate dependency management:
+
+::
+
+    <dependencyManagement>
+        <dependencies>
+            <dependency>
+                <groupId>org.opendaylight.odlparent</groupId>
+                <artifactId>odlparent-artifacts</artifactId>
+                <version>1.8.0-SNAPSHOT</version>
+                <scope>import</scope>
+                <type>pom</type>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+
+(the version number there is appropriate for Carbon). We no longer use version
+ranges, the feature dependencies all use the ``odlparent`` version (but you
+should rely on the artifacts POM).