1 .. _odl-parent-developer-guide:
3 ODL Parent Developer Guide
4 ==========================
12 The ODL Parent component for OpenDaylight provides a number of Maven
13 parent POMs which allow Maven projects to be easily integrated in the
14 OpenDaylight ecosystem. Technically, the aim of projects in OpenDaylight
15 is to produce Karaf features, and these parent projects provide common
16 support for the different types of projects involved.
18 These parent projects are:
20 - ``odlparent-lite`` — the basic parent POM for Maven modules which
21 don’t produce artifacts (*e.g.* aggregator POMs)
23 - ``odlparent`` — the common parent POM for Maven modules containing
26 - ``bundle-parent`` — the parent POM for Maven modules producing OSGi
29 The following parent projects are deprecated, but still used in Carbon:
31 - ``feature-parent`` — the parent POM for Maven modules producing
32 Karaf 3 feature repositories
34 - ``karaf-parent`` — the parent POM for Maven modules producing Karaf 3
37 The following parent projects are new in Carbon, for Karaf 4 support (which
38 won’t be complete until Nitrogen):
40 - ``single-feature-parent`` — the parent POM for Maven modules producing
41 a single Karaf 4 feature
43 - ``feature-repo-parent`` — the parent POM for Maven modules producing
44 Karaf 4 feature repositories
46 - ``karaf4-parent`` — the parent POM for Maven modules producing Karaf 4
52 This is the base parent for all OpenDaylight Maven projects and
53 modules. It provides the following, notably to allow publishing
54 artifacts to Maven Central:
56 - license information;
58 - organization information;
60 - issue management information (a link to our Bugzilla);
62 - continuous integration information (a link to our Jenkins setup);
64 - default Maven plugins (``maven-clean-plugin``,
65 ``maven-deploy-plugin``, ``maven-install-plugin``,
66 ``maven-javadoc-plugin`` with HelpMojo support,
67 ``maven-project-info-reports-plugin``, ``maven-site-plugin`` with
68 Asciidoc support, ``jdepend-maven-plugin``);
70 - distribution management information.
72 It also defines two profiles which help during development:
74 - ``q`` (``-Pq``), the quick profile, which disables tests, code
75 coverage, Javadoc generation, code analysis, etc. — anything which
76 isn’t necessary to build the bundles and features (see `this blog
77 post <http://blog2.vorburger.ch/2016/06/improve-maven-build-speed-with-q.html>`__
80 - ``addInstallRepositoryPath``
81 (``-DaddInstallRepositoryPath=…/karaf/system``) which can be used to
82 drop a bundle in the appropriate Karaf location, to enable
83 hot-reloading of bundles during development (see `this blog
84 post <http://blog2.vorburger.ch/2016/06/maven-install-into-additional.html>`__
87 For modules which don’t produce any useful artifacts (*e.g.* aggregator
88 POMs), you should add the following to avoid processing artifacts:
95 <groupId>org.apache.maven.plugins</groupId>
96 <artifactId>maven-deploy-plugin</artifactId>
102 <groupId>org.apache.maven.plugins</groupId>
103 <artifactId>maven-install-plugin</artifactId>
114 This inherits from ``odlparent-lite`` and mainly provides dependency and
115 plugin management for OpenDaylight projects.
117 If you use any of the following libraries, you should rely on
118 ``odlparent`` to provide the appropriate versions:
126 - ``commons-fileupload``
160 - core OSGi dependencies (``core``, ``compendium``\ …)
184 This list isn’t exhaustive. It’s also not cast in stone; if you’d
185 like to add a new dependency (or migrate a dependency), please
187 list <https://lists.opendaylight.org/mailman/listinfo/odlparent-dev>`__.
189 ``odlparent`` also enforces some Checkstyle verification rules. In
190 particular, it enforces the common license header used in all
196 * Copyright © ${year} ${holder} and others. All rights reserved.
198 * This program and the accompanying materials are made available under the
199 * terms of the Eclipse Public License v1.0 which accompanies this distribution,
200 * and is available at http://www.eclipse.org/legal/epl-v10.html
203 where “\ ``${year}``\ ” is initially the first year of publication, then
204 (after a year has passed) the first and latest years of publication,
205 separated by commas (*e.g.* “2014, 2016”), and “\ ``${holder}``\ ” is
206 the initial copyright holder (typically, the first author’s employer).
207 “All rights reserved” is optional.
209 If you need to disable this license check, *e.g.* for files imported
210 under another license (EPL-compatible of course), you can override the
211 ``maven-checkstyle-plugin`` configuration. ``features-test`` does this
212 for its ``CustomBundleUrlStreamHandlerFactory`` class, which is
218 <artifactId>maven-checkstyle-plugin</artifactId>
221 <id>check-license</id>
225 <phase>process-sources</phase>
227 <configLocation>check-license.xml</configLocation>
228 <headerLocation>EPL-LICENSE.regexp.txt</headerLocation>
229 <includeResources>false</includeResources>
230 <includeTestResources>false</includeTestResources>
231 <sourceDirectory>${project.build.sourceDirectory}</sourceDirectory>
233 <!-- Skip Apache Licensed files -->
234 org/opendaylight/odlparent/featuretest/CustomBundleUrlStreamHandlerFactory.java
236 <failsOnError>false</failsOnError>
237 <consoleOutput>true</consoleOutput>
246 This inherits from ``odlparent`` and enables functionality useful for
249 - ``maven-javadoc-plugin`` is activated, to build the Javadoc JAR;
251 - ``maven-source-plugin`` is activated, to build the source JAR;
253 - ``maven-bundle-plugin`` is activated (including extensions), to build
254 OSGi bundles (using the “bundle” packaging).
256 In addition to this, JUnit is included as a default dependency in “test”
262 This inherits from ``odlparent`` and enables functionality useful for
265 - ``karaf-maven-plugin`` is activated, to build Karaf features — but
266 for OpenDaylight, projects need to use “jar” packaging (**not**
269 - ``features.xml`` files are processed from templates stored in
270 ``src/main/features/features.xml``;
272 - Karaf features are tested after build to ensure they can be activated
273 in a Karaf container.
275 The ``features.xml`` processing allows versions to be ommitted from
276 certain feature dependencies, and replaced with “\ ``{{version}}``\ ”.
281 <features name="odl-mdsal-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.2.0"
282 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
283 xsi:schemaLocation="http://karaf.apache.org/xmlns/features/v1.2.0 http://karaf.apache.org/xmlns/features/v1.2.0">
285 <repository>mvn:org.opendaylight.odlparent/features-odlparent/{{VERSION}}/xml/features</repository>
288 <feature name='odl-mdsal-broker-local' version='${project.version}' description="OpenDaylight :: MDSAL :: Broker">
289 <feature version='${yangtools.version}'>odl-yangtools-common</feature>
290 <feature version='${mdsal.version}'>odl-mdsal-binding-dom-adapter</feature>
291 <feature version='${mdsal.model.version}'>odl-mdsal-models</feature>
292 <feature version='${project.version}'>odl-mdsal-common</feature>
293 <feature version='${config.version}'>odl-config-startup</feature>
294 <feature version='${config.version}'>odl-config-netty</feature>
295 <feature version='[3.3.0,4.0.0)'>odl-lmax</feature>
297 <bundle>mvn:org.opendaylight.controller/sal-dom-broker-config/{{VERSION}}</bundle>
298 <bundle start-level="40">mvn:org.opendaylight.controller/blueprint/{{VERSION}}</bundle>
299 <configfile finalname="${config.configfile.directory}/${config.mdsal.configfile}">mvn:org.opendaylight.controller/md-sal-config/{{VERSION}}/xml/config</configfile>
302 As illustrated, versions can be ommitted in this way for repository
303 dependencies, bundle dependencies and configuration files. They must be
304 specified traditionally (either hard-coded, or using Maven properties)
305 for feature dependencies.
310 This allows building a Karaf 3 distribution, typically for local testing
311 purposes. Any runtime-scoped feature dependencies will be included in the
312 distribution, and the ``karaf.localFeature`` property can be used to
313 specify the boot feature (in addition to ``standard``).
315 single-feature-parent
316 ~~~~~~~~~~~~~~~~~~~~~
318 This inherits from ``odlparent`` and enables functionality useful for
321 - ``karaf-maven-plugin`` is activated, to build Karaf features, typically
322 with “feature” packaging (“kar” is also supported);
324 - ``feature.xml`` files are generated based on the compile-scope dependencies
325 defined in the POM, optionally initialised from a stub in
326 ``src/main/feature/feature.xml``.
328 - Karaf features are tested after build to ensure they can be activated
329 in a Karaf container.
331 The ``feature.xml`` processing adds transitive dependencies by default, which
332 allows features to be defined using only the most significant dependencies
333 (those that define the feature); other requirements are determined
334 automatically as long as they exist as Maven dependencies.
336 “configfiles” need to be defined both as Maven dependencies (with the
337 appropriate type and classifier) and as ``<configfile>`` elements in the
338 ``feature.xml`` stub.
340 Other features which a feature depends on need to be defined as Maven
341 dependencies with type “xml” and classifier “features” (note the plural here).
346 This inherits from ``odlparent`` and enables functionality useful for
347 Karaf 4 feature repositories. It follows the same principles as
348 ``single-feature-parent``, but is designed specifically for repositories
349 and should be used only for this type of artifacts.
351 It builds a feature repository referencing all the (feature) dependencies
357 This allows building a Karaf 4 distribution, typically for local testing
358 purposes. Any runtime-scoped feature dependencies will be included in the
359 distribution, and the ``karaf.localFeature`` property can be used to
360 specify the boot feature (in addition to ``standard``).
362 Features (for Karaf 3)
363 ----------------------
365 The ODL Parent component for OpenDaylight provides a number of Karaf 3
366 features which can be used by other Karaf 3 features to use certain
367 third-party upstream dependencies.
371 - Akka features (in the ``features-akka`` repository):
373 - ``odl-akka-all`` — all Akka bundles;
375 - ``odl-akka-scala-2.11`` — Scala runtime for OpenDaylight;
377 - ``odl-akka-system-2.4`` — Akka actor framework bundles;
379 - ``odl-akka-clustering-2.4`` — Akka clustering bundles and
382 - ``odl-akka-leveldb-0.7`` — LevelDB;
384 - ``odl-akka-persistence-2.4`` — Akka persistence;
386 - general third-party features (in the ``features-odlparent``
389 - ``odl-netty-4`` — all Netty bundles;
391 - ``odl-guava-18`` — Guava 18;
393 - ``odl-guava-21`` — Guava 21 (not indended for use in Carbon);
395 - ``odl-lmax-3`` — LMAX Disruptor;
397 - ``odl-triemap-0.2`` — Concurrent Trie HashMap.
399 To use these, you need to declare a dependency on the appropriate
400 repository in your ``features.xml`` file:
404 <repository>mvn:org.opendaylight.odlparent/features-odlparent/{{VERSION}}/xml/features</repository>
406 and then include the feature, *e.g.*:
410 <feature name='odl-mdsal-broker-local' version='${project.version}' description="OpenDaylight :: MDSAL :: Broker">
412 <feature version='[3.3.0,4.0.0)'>odl-lmax</feature>
416 You also need to depend on the features repository in your POM:
421 <groupId>org.opendaylight.odlparent</groupId>
422 <artifactId>features-odlparent</artifactId>
423 <classifier>features</classifier>
427 assuming the appropriate dependency management:
431 <dependencyManagement>
434 <groupId>org.opendaylight.odlparent</groupId>
435 <artifactId>odlparent-artifacts</artifactId>
436 <version>1.8.0-SNAPSHOT</version>
437 <scope>import</scope>
441 </dependencyManagement>
443 (the version number there is appropriate for Carbon). For the time being
444 you also need to depend separately on the individual JARs as
445 compile-time dependencies to build your dependent code; the relevant
446 dependencies are managed in ``odlparent``'s dependency management.
448 | The suggested version ranges are as follows:
450 - ``odl-netty``: ``[4.0.37,4.1.0)`` or ``[4.0.37,5.0.0)``;
452 - ``odl-guava``: ``[18,19)`` (if your code is ready for it, ``[19,20)``
453 is also available, but the current default version of Guava in
456 - ``odl-lmax``: ``[3.3.4,4.0.0)``
458 Features (for Karaf 4)
459 ----------------------
461 There are equivalent features to all the Karaf 3 features, for Karaf 4.
462 The repositories use “features4” instead of “features”, and the features
463 use “odl4” instead of “odl”.
465 The following new features are specific to Karaf 4:
467 - Karaf wrapper features (also in the ``features4-odlparent``
468 repository) — these can be used to pull in a Karaf feature
469 using a Maven dependency in a POM:
471 - ``odl-karaf-feat-feature`` — the Karaf ``feature`` feature;
473 - ``odl-karaf-feat-jdbc`` — the Karaf ``jdbc`` feature;
475 - ``odl-karaf-feat-jetty`` — the Karaf ``jetty`` feature;
477 - ``odl-karaf-feat-war`` — the Karaf ``war`` feature.
479 To use these, all you need to do now is add the appropriate dependency
480 in your feature POM; for example:
485 <groupId>org.opendaylight.odlparent</groupId>
486 <artifactId>odl4-guava-18</artifactId>
487 <classifier>features</classifier>
491 assuming the appropriate dependency management:
495 <dependencyManagement>
498 <groupId>org.opendaylight.odlparent</groupId>
499 <artifactId>odlparent-artifacts</artifactId>
500 <version>1.8.0-SNAPSHOT</version>
501 <scope>import</scope>
505 </dependencyManagement>
507 (the version number there is appropriate for Carbon). We no longer use version
508 ranges, the feature dependencies all use the ``odlparent`` version (but you
509 should rely on the artifacts POM).