svn commit: r1188454 - /karaf/trunk/manual/src/main/webapp/developers-guide/custom-distribution.conf

[dj...@apache.org]

Author: djencks
Date: Tue Oct 25 00:12:00 2011
New Revision: 1188454

URL: http://svn.apache.org/viewvc?rev=1188454&view=rev
Log:
describe karaf-assembly packaging for the manual

Modified:
    karaf/trunk/manual/src/main/webapp/developers-guide/custom-distribution.conf

Modified: karaf/trunk/manual/src/main/webapp/developers-guide/custom-distribution.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/developers-guide/custom-distribution.conf?rev=1188454&r1=1188453&r2=1188454&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/developers-guide/custom-distribution.conf (original)
+++ karaf/trunk/manual/src/main/webapp/developers-guide/custom-distribution.conf Tue Oct 25 00:12:00 2011
@@ -15,6 +15,89 @@ This custom distribution could contain:
 
 h2. Maven assembly
 
+The recommended way to create a karaf server assembly is to use the karaf-assembly packaging with the karaf-maven-plugin.  This assembles a server from the maven dependencies in the project pom.  After explanation of the configuration options we present an example.  This is used to assemble the official karaf distributions, but due to maven limitations we have to simulate rather than use the karaf-assembly packaging.
+
+This packaging creates tar.gz and zip archives containing the assembled server.  They are identical except that zip archives don't unpack with appropriate unix file permissions for the scripts.
+
+h3. Maven dependencies
+Maven dependencies in a karaf-assembly project can be feature repositories (classifier "features") or kar archives.  Feature repositories are installed in the internal "system" maven structured repository.  Kar archives have their content unpacked on top of the server as well as contained feature repositories installed.
+
+The maven scope of a dependency determines whether its feature repository is listed in the features service configuration file etc/org.apache.karaf.features.cfg featuresRepositories property:
+
+compile (default): All the features in the repository (or for a kar repositories) will be installed into the startup.properties.  The feature repo is not listed in the features service configuration file.
+
+runtime: feature installation is controlled by <startupFeature>, <bootFeature>, and <installedFeature> elements in the karaf-maven-plugin configuration. The feature repo uri is listed in the features service configuration file.
+
+h3. Plugin configuration
+
+Control how features are installed using these elements referring to features from installed feature repositories:
+
+<startupFeature>foo</startupFeature>  This will result in the feature bundles being listed in startup.properties at the appropriate start level and the bundles being copied into the "system" internal repository.
+
+<bootFeature>bar</bootFeature> This will result in the feature name added to boot-features in the features service configuration file and all the bundles in the feature copied into the "system" internal repository.
+
+<installedFeature>baz</installedFeature> This will result in all the bundles in the feature being installed in the "system" internal repository.  Therefore at runtime the feature may be installed without access to external repositories.
+
+h3. Example
+
+This is the minimal assembly pom changed to use the packaging and annotated
+
+{code}
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+...
+    </parent>
+
+    <groupId>org.apache.karaf.assemblies</groupId>
+    <artifactId>apache-karaf-minimal</artifactId>
+    <version>3.0.0-SNAPSHOT</version>
+    <packaging>karaf-assembly</packaging>
+    <name>Apache Karaf :: Assemblies :: Minimal Distribution</name>
+
+    <dependencies>
+        <dependency>
+        <!-- scope is compile so all features (there is only one) are installed into startup.properties and the feature repo itself is not installed -->
+            <groupId>org.apache.karaf.features</groupId>
+            <artifactId>framework</artifactId>
+            <version>${project.version}</version>
+            <type>kar</type>
+        </dependency>
+        <dependency>
+        <!-- scope is runtime so the feature repo is listed in the features service config file, and features may be installed using the karaf-maven-plugin configuration -->
+            <groupId>org.apache.karaf.features</groupId>
+            <artifactId>standard</artifactId>
+            <classifier>features</classifier>
+            <type>xml</type>
+            <scope>runtime</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.karaf.tooling</groupId>
+                <artifactId>karaf-maven-plugin</artifactId>
+                <extensions>true</extensions>
+                <configuration>
+                    <!-- no startupFeatures -->
+                    <bootFeatures>
+                        <feature>standard</feature>
+                        <feature>management</feature>
+                    </bootFeatures>
+                    <!-- no installedFeatures -->
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>
+{code}
+
+
+h2. (deprecated old style) Maven assembly
+
 Basically a Karaf custom distribution involves:
 1. Uncompressing a standard Karaf distribution in a given directory.
 2. Populating the system repo with your features.