1 ODL Parent Developer Guide
2 ==========================
10 The ODL Parent component for OpenDaylight provides a number of Maven
11 parent POMs which allow Maven projects to be easily integrated in the
12 OpenDaylight ecosystem. Technically, the aim of projects in OpenDaylight
13 is to produce Karaf features, and these parent projects provide common
14 support for the different types of projects involved.
16 | These parent projects are:
18 - ``odlparent-lite`` — the basic parent POM for Maven modules which
19 don’t produce artifacts (*e.g.* aggregator POMs)
21 - ``odlparent`` — the common parent POM for Maven modules containing
24 - ``bundle-parent`` — the parent POM for Maven modules producing OSGi
27 - ``features-parent`` — the parent POM for Maven modules producing
33 | This is the base parent for all OpenDaylight Maven projects and
34 modules. It provides the following, notably to allow publishing
35 artifacts to Maven Central:
37 - license information;
39 - organization information;
41 - issue management information (a link to our Bugzilla);
43 - continuous integration information (a link to our Jenkins setup);
45 - default Maven plugins (``maven-clean-plugin``,
46 ``maven-deploy-plugin``, ``maven-install-plugin``,
47 ``maven-javadoc-plugin`` with HelpMojo support,
48 ``maven-project-info-reports-plugin``, ``maven-site-plugin`` with
49 Asciidoc support, ``jdepend-maven-plugin``);
51 - distribution management information.
53 It also defines two profiles which help during development:
55 - ``q`` (``-Pq``), the quick profile, which disables tests, code
56 coverage, Javadoc generation, code analysis, etc. — anything which
57 isn’t necessary to build the bundles and features (see `this blog
58 post <http://blog2.vorburger.ch/2016/06/improve-maven-build-speed-with-q.html>`__
61 - ``addInstallRepositoryPath``
62 (``-DaddInstallRepositoryPath=…/karaf/system``) which can be used to
63 drop a bundle in the appropriate Karaf location, to enable
64 hot-reloading of bundles during development (see `this blog
65 post <http://blog2.vorburger.ch/2016/06/maven-install-into-additional.html>`__
68 For modules which don’t produce any useful artifacts (*e.g.* aggregator
69 POMs), you should add the following to avoid processing artifacts:
76 <groupId>org.apache.maven.plugins</groupId>
77 <artifactId>maven-deploy-plugin</artifactId>
83 <groupId>org.apache.maven.plugins</groupId>
84 <artifactId>maven-install-plugin</artifactId>
95 This inherits from ``odlparent-lite`` and mainly provides dependency and
96 plugin management for OpenDaylight projects.
98 | If you use any of the following libraries, you should rely on
99 ``odlparent`` to provide the appropriate versions:
107 - ``commons-fileupload``
141 - core OSGi dependencies (``core``, ``compendium``\ …)
165 This list isn’t exhaustive. It’s also not cast in stone; if you’d
166 like to add a new dependency (or migrate a dependency), please
168 list <https://lists.opendaylight.org/mailman/listinfo/odlparent-dev>`__.
170 ``odlparent`` also enforces some Checkstyle verification rules. In
171 particular, it enforces the common license header used in all
177 * Copyright © ${year} ${holder} and others. All rights reserved.
179 * This program and the accompanying materials are made available under the
180 * terms of the Eclipse Public License v1.0 which accompanies this distribution,
181 * and is available at http://www.eclipse.org/legal/epl-v10.html
184 where “\ ``${year}``\ ” is initially the first year of publication, then
185 (after a year has passed) the first and latest years of publication,
186 separated by commas (*e.g.* “2014, 2016”), and “\ ``${holder}``\ ” is
187 the initial copyright holder (typically, the first author’s employer).
188 “All rights reserved” is optional.
190 If you need to disable this license check, *e.g.* for files imported
191 under another license (EPL-compatible of course), you can override the
192 ``maven-checkstyle-plugin`` configuration. ``features-test`` does this
193 for its ``CustomBundleUrlStreamHandlerFactory`` class, which is
199 <artifactId>maven-checkstyle-plugin</artifactId>
202 <id>check-license</id>
206 <phase>process-sources</phase>
208 <configLocation>check-license.xml</configLocation>
209 <headerLocation>EPL-LICENSE.regexp.txt</headerLocation>
210 <includeResources>false</includeResources>
211 <includeTestResources>false</includeTestResources>
212 <sourceDirectory>${project.build.sourceDirectory}</sourceDirectory>
214 <!-- Skip Apache Licensed files -->
215 org/opendaylight/odlparent/featuretest/CustomBundleUrlStreamHandlerFactory.java
217 <failsOnError>false</failsOnError>
218 <consoleOutput>true</consoleOutput>
227 | This inherits from ``odlparent`` and enables functionality useful for
230 - ``maven-javadoc-plugin`` is activated, to build the Javadoc JAR;
232 - ``maven-source-plugin`` is activated, to build the source JAR;
234 - ``maven-bundle-plugin`` is activated (including extensions), to build
235 OSGi bundles (using the “bundle” packaging).
237 In addition to this, JUnit is included as a default dependency in “test”
243 | This inherits from ``odlparent`` and enables functionality useful for
246 - ``karaf-maven-plugin`` is activated, to build Karaf features — but
247 for OpenDaylight, projects need to use “jar” packaging (**not**
250 - ``features.xml`` files are processed from templates stored in
251 ``src/main/features/features.xml``;
253 - Karaf features are tested after build to ensure they can be activated
254 in a Karaf container.
256 The ``features.xml`` processing allows versions to be ommitted from
257 certain feature dependencies, and replaced with “\ ``{{version}}``\ ”.
262 <features name="odl-mdsal-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.2.0"
263 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
264 xsi:schemaLocation="http://karaf.apache.org/xmlns/features/v1.2.0 http://karaf.apache.org/xmlns/features/v1.2.0">
266 <repository>mvn:org.opendaylight.odlparent/features-odlparent/{{VERSION}}/xml/features</repository>
269 <feature name='odl-mdsal-broker-local' version='${project.version}' description="OpenDaylight :: MDSAL :: Broker">
270 <feature version='${yangtools.version}'>odl-yangtools-common</feature>
271 <feature version='${mdsal.version}'>odl-mdsal-binding-dom-adapter</feature>
272 <feature version='${mdsal.model.version}'>odl-mdsal-models</feature>
273 <feature version='${project.version}'>odl-mdsal-common</feature>
274 <feature version='${config.version}'>odl-config-startup</feature>
275 <feature version='${config.version}'>odl-config-netty</feature>
276 <feature version='[3.3.0,4.0.0)'>odl-lmax</feature>
278 <bundle>mvn:org.opendaylight.controller/sal-dom-broker-config/{{VERSION}}</bundle>
279 <bundle start-level="40">mvn:org.opendaylight.controller/blueprint/{{VERSION}}</bundle>
280 <configfile finalname="${config.configfile.directory}/${config.mdsal.configfile}">mvn:org.opendaylight.controller/md-sal-config/{{VERSION}}/xml/config</configfile>
283 As illustrated, versions can be ommitted in this way for repository
284 dependencies, bundle dependencies and configuration files. They must be
285 specified traditionally (either hard-coded, or using Maven properties)
286 for feature dependencies.
291 The ODL Parent component for OpenDaylight provides a number of Karaf
292 features which can be used by other Karaf features to use certain
293 third-party upstream dependencies.
295 | These features are:
297 - | Akka features (in the ``features-akka`` repository):
299 - ``odl-akka-all`` — all Akka bundles;
301 - ``odl-akka-scala`` — Scala runtime for OpenDaylight;
303 - ``odl-akka-system`` — Akka actor framework bundles;
305 - ``odl-akka-clustering`` — Akka clustering bundles and
308 - ``odl-akka-leveldb`` — LevelDB;
310 - ``odl-akka-persistence`` — Akka persistence;
312 - general third-party features (in the ``features-odlparent``
315 - ``odl-netty`` — all Netty bundles;
317 - ``odl-guava`` — Guava;
319 - ``odl-lmax`` — LMAX Disruptor.
321 To use these, you need to declare a dependency on the appropriate
322 repository in your ``features.xml`` file:
326 <repository>mvn:org.opendaylight.odlparent/features-odlparent/{{VERSION}}/xml/features</repository>
328 and then include the feature, *e.g.*:
332 <feature name='odl-mdsal-broker-local' version='${project.version}' description="OpenDaylight :: MDSAL :: Broker">
334 <feature version='[3.3.0,4.0.0)'>odl-lmax</feature>
338 You also need to depend on the features repository in your POM:
343 <groupId>org.opendaylight.odlparent</groupId>
344 <artifactId>features-odlparent</artifactId>
345 <classifier>features</classifier>
349 assuming the appropriate dependency management:
353 <dependencyManagement>
356 <groupId>org.opendaylight.odlparent</groupId>
357 <artifactId>odlparent-artifacts</artifactId>
358 <version>1.7.0-SNAPSHOT</version>
359 <scope>import</scope>
363 </dependencyManagement>
365 (the version number there is appropriate for Boron). For the time being
366 you also need to depend separately on the individual JARs as
367 compile-time dependencies to build your dependent code; the relevant
368 dependencies are managed in ``odlparent``'s dependency management.
370 | The suggested version ranges are as follows:
372 - ``odl-netty``: ``[4.0.37,4.1.0)`` or ``[4.0.37,5.0.0)``;
374 - ``odl-guava``: ``[18,19)`` (if your code is ready for it, ``[19,20)``
375 is also available, but the current default version of Guava in
378 - ``odl-lmax``: ``[3.3.4,4.0.0)``