karaf/karaf-maven-plugin/src/site/apt/usage.apt

   1 ~~ Licensed to the Apache Software Foundation (ASF) under one
   2 ~~ or more contributor license agreements.  See the NOTICE file
   3 ~~ distributed with this work for additional information
   4 ~~ regarding copyright ownership.  The ASF licenses this file
   5 ~~ to you under the Apache License, Version 2.0 (the
   6 ~~ "License"); you may not use this file except in compliance
   7 ~~ with the License.  You may obtain a copy of the License at
   8 ~~
   9 ~~ http://www.apache.org/licenses/LICENSE-2.0
  10 ~~
  11 ~~ Unless required by applicable law or agreed to in writing,
  12 ~~ software distributed under the License is distributed on an
  13 ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  14 ~~ KIND, either express or implied.  See the License for the
  15 ~~ specific language governing permissions and limitations
  16 ~~ under the License.
  17
  18   ------
  19   Usage
  20   ------
  21
  22 Usage
  23
  24 Packagings
  25
  26   All packagings require that you mention the karaf-maven-plugin in pluginManagement or plugins with the extension element:
  27
  28 +---+
  29                 <plugin>
  30                     <groupId>org.apache.karaf.tooling</groupId>
  31                     <artifactId>karaf-maven-plugin</artifactId>
  32                     <version>${karaf.version}</version>
  33                     <extensions>true</extensions>
  34                 </plugin>
  35 +---+
  36
  37   You will also need to mention the karaf-maven-plugin in some build/plugins section of your pom or ancestor pom.  The examples below assume extensions is set in
  38   a pluginManagement section or an ancestor pom.
  39
  40 * feature
  41
  42   Specify the feature packaging in your pom with
  43
  44 +---+
  45     <packaging>feature</packaging>
  46 +---+
  47
  48   The feature packaging lifecycle uses these mojos:
  49
  50 +---+
  51                           <phases>
  52                               <compile>
  53                                   org.apache.karaf.tooling:karaf-maven-plugin:generate-features-xml
  54                               </compile>
  55                               <install>
  56                                   org.apache.maven.plugins:maven-install-plugin:install
  57                               </install>
  58                               <deploy>
  59                                   org.apache.maven.plugins:maven-deploy-plugin:deploy
  60                               </deploy>
  61                           </phases>
  62 +---+
  63
  64   Here's an example of a feature project with all configuration options set:
  65
  66 +---+
  67             <plugin>
  68                 <groupId>org.apache.karaf.tooling</groupId>
  69                 <artifactId>karaf-maven-plugin</artifactId>
  70                 <configuration>
  71                     <startLevel>50</startLevel>
  72                     <aggregateFeatures>true</aggregateFeatures>
  73                     <resolver>(OBR)</resolver>
  74
  75                     <checkDependencyChange>true</checkDependencyChange>
  76                     <warnOnDependencyChange>true</warnOnDependencyChange>
  77                     <logDependencyChanges>true</logDependencyChanges>
  78                     <overwriteChangedDependencies>true</overwriteChangedDependencies>
  79                 </configuration>
  80             </plugin>
  81 +---+
  82
  83   This packaging results in a features xml descriptor including a feature with the project artifactId as name and project version as version.
  84
  85   The suitably scoped project jar dependencies are added to this feature as bundles.  Compile and provided scope result in the dependency attribute false (unset) and
  86   runtime scope results in the dependency attribute set true.
  87
  88   startLevel determines the startLevel of bundles added to the constructed feature.
  89
  90   kar project dependencies are added to the constructed feature as dependencies.
  91
  92   If aggregate features is false or not set, feature project dependencies are added to the constructed feature as dependencies.  If aggregateFeatures is true,
  93   the features of all feature project dependencies are extracted from the dependency feature xml files and added as features to the constructed features xml.
  94
  95   If a source src/main/feature/feature.xml file is provided then it is filtered and used as a base for the generated feature xml file.  If there is a feature of the appropriate name
  96   it is extended with the project dependencies, otherwise one is created.  This allows you to specify alternate startLevels, configuration files, and configuration as well as
  97   completely configuring the feature xml file by hand.
  98
  99   The dependency change options allow you to set up change tracking so you can be alerted if the transitive project dependencies included in the feature have changed.  To turn this  on set
 100   checkDependencyChange true.  A stripped down feature xml file will be written to src/main/history/dependencies.xml that includes one feature with all the bundles from all the features.
 101   Subsequent builds will compare this historical file with a similar current file.  If it has changed, the new dependencies.xml added and removed lists,
 102   and a dependency tree will be written to target/history, and various options are available.
 103   If warnOnDependencyChange is missing or false, the build will fail.
 104   If logDependencyChanges is set, the added and removed lists will be shown in the maven build output.
 105   If overwriteChangedDependencies is set the historical src/main/history/dependencies.xml file will be overwritten with the new contents.
 106
 107   While the determination of bundle transitive dependencies uses aether, just like maven, the algorithm is slightly different.  We traverse the entire dependency graph
 108   and exclude bundle dependencies that are included as project dependencies of feature and kar dependencies.  Currently dependencies that are supplied in source feature xml
 109   of dependent features and kars are not tracked.
 110
 111 * kar
 112
 113   Specify the kar packaging in your pom with
 114
 115 +---+
 116     <packaging>kar</packaging>
 117 +---+
 118
 119   The kar packaging lifecycle uses these mojos:
 120
 121 +---+
 122                         <phases>
 123                             <process-resources>
 124                                 org.apache.maven.plugins:maven-resources-plugin:resources
 125                             </process-resources>
 126                             <compile>
 127                                 org.apache.karaf.tooling:karaf-maven-plugin:generate-features-xml
 128                             </compile>
 129                             <package>
 130                                 org.apache.karaf.tooling:karaf-maven-plugin:archive-kar
 131                             </package>
 132                             <install>
 133                                 org.apache.maven.plugins:maven-install-plugin:install
 134                             </install>
 135                             <deploy>
 136                                 org.apache.maven.plugins:maven-deploy-plugin:deploy
 137                             </deploy>
 138                         </phases>
 139 +---+
 140
 141   kar packaging configuration is exactly the same as feature packaging configuration.  All bundles that are not marked as dependencies in the feature.xml output from the xml generation stage are
 142   added to a maven-repo-like structure in the target kar.  In addition any resources from src are added.  Resources need to be under "resources" in the src resource directory in order to get
 143   unpacked when the kar is installed.  For example with default maven-resource-plugin configuration src/main/resources/resources/etc/foo.cfg will result in resources/etc/foo.cfg in the kar and
 144   etc/foo.cfg when installed in the server.
 145
 146
 147 * karaf-assembly
 148
 149   Specify the karaf-assembly packaging in your pom with
 150
 151 +---+
 152     <packaging>karaf-assembly</packaging>
 153 +---+
 154
 155   The karaf-assembly lifecycle uses these mojos:
 156
 157 +---+
 158                         <phases>
 159                             <process-resources>
 160                                 org.apache.maven.plugins:maven-resources-plugin:resources,
 161                                 org.apache.karaf.tooling:karaf-maven-plugin:assembly
 162                             </process-resources>
 163                             <compile>
 164                             </compile>
 165                             <package>
 166                                 org.apache.karaf.tooling:karaf-maven-plugin:archive-server
 167                             </package>
 168                             <install>
 169                                 org.apache.maven.plugins:maven-install-plugin:install
 170                             </install>
 171                             <deploy>
 172                                 org.apache.maven.plugins:maven-deploy-plugin:deploy
 173                             </deploy>
 174                         </phases>
 175 +---+
 176
 177   Here's an example of a karaf-assembly project with all configuration options set:
 178
 179 +---+
 180             <plugin>
 181                 <groupId>org.apache.karaf.tooling</groupId>
 182                 <artifactId>karaf-maven-plugin</artifactId>
 183                 <configuration>
 184                     <defaultStartLevel>50</defaultStartLevel>
 185                 </configuration>
 186             </plugin>
 187 +---+
 188
 189   property-file-edits specifies the location of an XML file that specifies edits to 'etc' files as they are
 190   copied from the reference to the assembly. By default, the value of this parameter is src/main/karaf/assembly-property-edits.xml;
 191   if you add a file at that location, the plugin will apply the edits you specify in it.
 192
 193   defaultStartLevel determines the start level of bundles that do not have startLevel set in the feature xml descriptor. If not set, the default is 30.
 194
 195   Project dependencies that are feature or kar packaging are treated differently depending on whether they are scope runtime, or compile/provided.  Runtime scope dependencies are installed
 196   less thoroughly.
 197
 198   This plugin:
 199
 200   - unpacks the resources content from project dependencies that are kars
 201
 202   - unpacks the system maven-repo-like structure from project dependencies that are kars. If the project dependency is scope compile or provided it is unpacked to system.
 203
 204   - locates and installs all the bundles mentioned in feature xml descriptors that are project dependencies or located in project dependencies that are kars of scope compile/provided.
 205
 206   - constructs a startup.properties file that includes all the bundles mentioned in feature descriptors of scope compile/provided at the specified or default start level.
 207
 208   - adds the feature project dependencies and features in kar dependencies of scope runtime to the features service configuration.
 209
 210   The result is packed up into zip and tar.gz assemblies.  Normally to get a working server you would include at least the karaf-framework kar and most likely the karaf-full kar: these are used
 211   to assemble the minimal and full server.