karaf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jbono...@apache.org
Subject [14/15] karaf git commit: KARAF-3679 - Switch user guide to asciidoc
Date Tue, 05 Jan 2016 14:02:39 GMT
http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/developer-guide/custom-distribution.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/developer-guide/custom-distribution.adoc b/manual/src/main/asciidoc/developer-guide/custom-distribution.adoc
new file mode 100644
index 0000000..73a828a
--- /dev/null
+++ b/manual/src/main/asciidoc/developer-guide/custom-distribution.adoc
@@ -0,0 +1,669 @@
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+=== Custom distributions
+
+As Karaf is an OSGi container, it's heavily used as as application and middleware kernel.
+
+You may wish to construct your own Karaf distribution preconfigured to your requirements.
+This custom distribution could contain:
+
+* branding to change the Karaf console look-and-feel
+* configuration files (in the etc folder) altered to your requirements
+* pre-packaged artifacts in the deploy folder
+* a pre-populated system repository (containing your own bundle and features descriptor)
+* renamed or specific scripts in the bin folder
+* system documentation files
+
+==== Maven assembly
+
+The recommended way to create a Karaf server assembly is to use the karaf-assembly packaging with the karaf-maven-plugin.
+It assembles a server from the maven dependencies in the project pom.
+After explanation of the configuration options we present an example.
+
+The Karaf project effectively uses this packaging 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.
+
+===== 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.
+* 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.
+
+===== Plugin configuration
+
+Control how features are installed using these elements referring to features from installed feature repositories:
+
+* `<startupFeature>foo</startupFeature>` 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. You can use feature_name or feature_name/feature_version formats.
+* `<bootFeature>bar</bootFeature>` 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. You can use feature_name or feature_name/feature_version formats.
+* `<installedFeature>baz</installedFeature>` 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. You can use feature_name or feature_name/feature_version formats.
+
+===== Minimal Distribution Example
+
+This is the minimal assembly pom changed to use the packaging and annotated
+
+----
+<?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</groupId>
+    <artifactId>apache-karaf-minimal</artifactId>
+    <version>${project.version}</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 added in etc/org.apache.karaf.features.cfg file -->
+            <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 etc/org.apache.karaf.features.cfg file, and features will installed into the system directory -->
+            <groupId>org.apache.karaf.features</groupId>
+            <artifactId>standard</artifactId>
+            <classifier>features</classifier>
+            <type>xml</type>
+            <scope>runtime</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <!-- if you want to include resources in the distribution -->
+        <resources>
+            <resource>
+                <directory>src/main/resources</directory>
+                <filtering>false</filtering>
+                <includes>
+                    <include>**/*</include>
+                </includes>
+            </resource>
+            <resource>
+                <directory>src/main/filtered-resources</directory>
+                <filtering>true</filtering>
+                <includes>
+                    <include>**/*</include>
+                </includes>
+            </resource>
+        </resources>
+
+        <plugins>
+            <!-- if you want to include resources in the distribution -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-resources-plugin</artifactId>
+                <version>2.6</version>
+                <executions>
+                    <execution>
+                        <id>process-resources</id>
+                        <goals>
+                            <goal>resources</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            <!-- karaf-maven-plugin will call both install-kar and instance-create-archive goals -->
+            <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>
+----
+
+===== Custom Distribution Example
+
+It's possible to specify feature versions using the name/version format.
+
+For instance, to pre-install Spring 4.0.7.RELEASE_1 feature in your custom distribution, you can use the following pom.xml:
+
+----
+<?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>
+
+    <groupId>my.custom</groupId>
+    <artifactId>my.distribution</artifactId>
+    <version>1.0</version>
+    <packaging>karaf-assembly</packaging>
+
+    <dependencies>
+        <dependency>
+        <!-- scope is compile so all features (there is only one) are installed into startup.properties and the feature repo itself is not added in etc/org.apache.karaf.features.cfg file -->
+            <groupId>org.apache.karaf.features</groupId>
+            <artifactId>framework</artifactId>
+            <version>4.0.0</version>
+            <type>kar</type>
+        </dependency>
+        <dependency>
+        <!-- scope is runtime so the feature repo is listed in etc/org.apache.karaf.features.cfg file, and features will installed into the system directory if specify in the plugin configuration -->
+            <groupId>org.apache.karaf.features</groupId>
+            <artifactId>standard</artifactId>
+            <classifier>features</classifier>
+            <type>xml</type>
+            <scope>runtime</scope>
+        </dependency>
+        <dependency>
+        <!-- scope is runtime so the feature repo is listed in etc/org.apache.karaf.features.cfg file, and features will installed into the system directory if specify in the plugin configuration -->
+            <groupId>org.apache.karaf.features</groupId>
+            <artifactId>spring</artifactId>
+            <classifier>features</classifier>
+            <type>xml</type>
+            <scope>runtime</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <!-- if you want to include resources in the distribution -->
+        <resources>
+            <resource>
+                <directory>src/main/resources</directory>
+                <filtering>false</filtering>
+                <includes>
+                    <include>**/*</include>
+                </includes>
+            </resource>
+            <resource>
+                <directory>src/main/filtered-resources</directory>
+                <filtering>true</filtering>
+                <includes>
+                    <include>**/*</include>
+                </includes>
+            </resource>
+        </resources>
+
+        <plugins>
+            <!-- if you want to include resources in the distribution -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-resources-plugin</artifactId>
+                <version>2.6</version>
+                <executions>
+                    <execution>
+                        <id>process-resources</id>
+                        <goals>
+                            <goal>resources</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.karaf.tooling</groupId>
+                <artifactId>karaf-maven-plugin</artifactId>
+                <version>4.0.0</version>
+                <extensions>true</extensions>
+                <configuration>
+                    <!-- no startupFeatures -->
+                    <bootFeatures>
+                        <feature>jaas</feature>
+                        <feature>shell</feature>
+                        <feature>ssh</feature>
+                        <feature>management</feature>
+                        <feature>bundle</feature>
+                        <feature>config</feature>
+                        <feature>deployer</feature>
+                        <feature>diagnostic</feature>
+                        <feature>instance</feature>
+                        <feature>kar</feature>
+                        <feature>log</feature>
+                        <feature>package</feature>
+                        <feature>service</feature>
+                        <feature>system</feature>
+                    </bootFeatures>
+                    <installedFeatures>
+                        <feature>wrapper</feature>
+                        <feature>spring/4.0.7.RELEASE_1</feature>
+                    </installedFeatures>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>
+----
+
+==== (deprecated old style) Maven assembly
+
+Basically a Karaf custom distribution involves:
+
+. Uncompressing a standard Karaf distribution in a given directory.
+. Populating the system repo with your features.
+. Populating the lib directory with your branding or other system bundle jar files.
+. Overriding the configuration files in the etc folder.
+
+These tasks could be performed using scripting, or more easily and portable, using Apache Maven and a set of Maven plugins.
+
+For instance, the Maven POM could look like:
+
+----
+<?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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+  <groupId>my.company</groupId>
+  <artifactId>mycustom-karaf</artifactId>
+  <version>1.0</version>
+  <packaging>pom</packaging>
+  <name>My Unix Custom Karaf Distribution</name>
+
+  <properties>
+    <karaf.version>${project.version}</karaf.version>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.karaf</groupId>
+      <artifactId>apache-karaf</artifactId>
+      <version>${karaf.version}</version>
+      <type>tar.gz</type>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.karaf</groupId>
+      <artifactId>apache-karaf</artifactId>
+      <version>${karaf.version}</version>
+      <type>xml</type>
+      <classifier>features</classifier>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <resources>
+      <resource>
+        <directory>${project.basedir}/src/main/filtered-resources</directory>
+        <filtering>true</filtering>
+        <includes>
+          <include>**/*</include>
+        </includes>
+      </resource>
+    </resources>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-resources-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>filter</id>
+            <phase>generate-resources</phase>
+            <goals>
+              <goal>resources</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.karaf.tooling</groupId>
+        <artifactId>karaf-maven-plugin</artifactId>
+        <version>${karaf.version}</version>
+        <executions>
+          <execution>
+           <id>add-features-to-repo</id>
+           <phase>generate-resources</phase>
+           <goals>
+             <goal>features-add-to-repo</goal>
+           </goals>
+           <configuration>
+              <descriptors>
+                <descriptor>mvn:org.apache.karaf/apache-karaf/${karaf.version}/xml/features</descriptor>
+                <descriptor>file:${project.basedir}/target/classes/my-features.xml</descriptor>
+              </descriptors>
+              <features>
+                <feature>my-feature</feature>
+              </features>
+           </configuration>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-dependency-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>copy</id>
+            <phase>generate-resources</phase>
+            <goals>
+              <goal>copy</goal>
+            </goals>
+            <configuration>
+               <!-- Define here the artifacts which should be considered in the assembly -->
+               <!-- For instance, the branding jar -->
+               <artifactItems>
+                 <artifactItem>
+                    <groupId>my.groupId</groupId>
+                    <artifactId>my.branding.id</artifactId>
+                    <version>1.0</version>
+                    <outputDirectory>target/dependencies</outputDirectory>
+                    <destFileName>mybranding.jar</destFileName>
+                 </artifactItem>
+               </artifactItems>
+            </configuration>
+          </execution>
+          <execution>
+            <!-- Uncompress the standard Karaf distribution -->
+            <id>unpack</id>
+            <phase>generate-resources</phase>
+            <goals>
+              <goal>unpack</goal>
+            </goals>
+            <configuration>
+              <artifactItems>
+                <artifactItem>
+                  <groupId>org.apache.karaf</groupId>
+                  <artifactId>apache-karaf</artifactId>
+                  <type>tar.gz</type>
+                  <outputDirectory>target/dependencies</outputDirectory>
+                </artifactItem>
+              </artifactItems>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-assembly-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>bin</id>
+            <phase>package</phase>
+            <goals>
+              <goal>single</goal>
+            </goals>
+            <configuration>
+              <descriptors>
+                <descriptor>src/main/descriptors/bin.xml</descriptor>
+              </descriptors>
+              <appendAssemblyId>false</appendAssemblyId>
+              <tarLongFileMode>gnu</tarLongFileMode>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+
+</project>
+----
+
+The Maven POM will download the Karaf standard distribution and prepare resources to be processed by the Maven assembly plugin.
+
+Your Maven project structure should look like:
+
+* `pom.xml`: the previous POM file
+* `src/main/descriptors/bin.xml`: the assembly Maven plugin descriptor (see below)
+* `src/main/filtered-resources`: contains all resource files that have Maven property values to be filtered/replaced. Typically, this will include features descriptor and configuration files.
+* `src/main/distribution`: contains all raw files which will be copied as-is into your custom distribution.
+
+For instance, `src/main/filtered-resources` could contain:
+
+* `my-features.xml` where Maven properties will be replaced
+* `etc/org.apache.karaf.features.cfg` file containing your my-features descriptor:
+
+----
+#
+# Comma separated list of features repositories to register by default
+#
+featuresRepositories=mvn:org.apache.karaf/apache-karaf/${karaf.version}/xml/features,mvn:my.groupId/my-features/${project.version}/xml/features
+
+#
+# Comma separated list of features to install at startup
+#
+featuresBoot=config,ssh,management,my-feature
+----
+
+The `src/main/distribution` contains all your custom Karaf configuration files and script, as, for examples:
+
+* etc/org.ops4j.pax.logging.cfg
+
+----
+# Root logger
+log4j.rootLogger=INFO, out, osgi:VmLogAppender
+log4j.throwableRenderer=org.apache.log4j.OsgiThrowableRenderer
+
+# CONSOLE appender not used by default
+log4j.appender.stdout=org.apache.log4j.ConsoleAppender
+log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
+log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32C %4L | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
+
+# File appender
+log4j.appender.out=org.apache.log4j.RollingFileAppender
+log4j.appender.out.layout=org.apache.log4j.PatternLayout
+log4j.appender.out.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32C %4L | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
+log4j.appender.out.file=${karaf.home}/log/my-customer-distribution.log
+log4j.appender.out.append=true
+log4j.appender.out.maxFileSize=1MB
+log4j.appender.out.maxBackupIndex=10
+
+# Sift appender
+log4j.appender.sift=org.apache.log4j.sift.MDCSiftingAppender
+log4j.appender.sift.key=bundle.name
+log4j.appender.sift.default=my-custom
+log4j.appender.sift.appender=org.apache.log4j.FileAppender
+log4j.appender.sift.appender.layout=org.apache.log4j.PatternLayout
+log4j.appender.sift.appender.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32c{1} | %-32.32C %4L | %m%n
+log4j.appender.sift.appender.file=${karaf.data}/log/$\\{bundle.name\\}.log
+log4j.appender.sift.appender.append=true
+----
+
+* etc/system.properties
+
+----
+#
+# The properties defined in this file will be made available through system
+# properties at the very beginning of the FAS boot process.
+#
+
+# Log level when the pax-logging service is not available
+# This level will only be used while the pax-logging service bundle
+# is not fully available.
+# To change log levels, please refer to the org.ops4j.pax.logging.cfg file
+# instead.
+org.ops4j.pax.logging.DefaultServiceLog.level=ERROR
+
+#
+# Name of this custom instance.
+#
+karaf.name=my-custom
+
+#
+# Default repository where bundles will be loaded from before using
+# other Maven repositories. For the full Maven configuration, see the
+# org.ops4j.pax.url.mvn.cfg file.
+#
+karaf.default.repository=system
+
+#
+# Location of a shell script that will be run when starting a shell
+# session. This script can be used to create aliases and define
+# additional commands.
+#
+karaf.shell.init.script=${karaf.home}/etc/shell.init.script
+
+#
+# Set this empty property to avoid errors when validating xml documents.
+#
+xml.catalog.files=
+
+#
+# Suppress the bell in the console when hitting backspace to many times
+# for example
+#
+jline.nobell=true
+
+#
+# Default port for the OSGi HTTP Service
+#
+org.osgi.service.http.port=8181
+
+#
+# Allow usage of ${custom.home} as an alias for ${karaf.home}
+#
+custom.home=${karaf.home}
+----
+
+* etc/users.properties
+
+----
+admin=admin,admin
+----
+
+* You can add a `etc/custom.properties`, it's a placeholder for any override you may need. For instance:
+
+----
+karaf.systemBundlesStartLevel=50
+obr.repository.url=http://svn.apache.org/repos/asf/servicemix/smx4/obr-repo/repository.xml
+org.osgi.framework.system.packages.extra = \
+  org.apache.karaf.branding; \
+  com.sun.org.apache.xalan.internal.xsltc.trax; \
+  com.sun.org.apache.xerces.internal.dom; \
+  com.sun.org.apache.xerces.internal.jaxp; \
+  com.sun.org.apache.xerces.internal.xni; \
+  com.sun.jndi.ldap
+----
+
+Now, we can "assemble" our custom distribution using the Maven assembly plugin. The Maven assembly plugin uses an
+assembly descriptor, configured in POM above to be `src/main/descriptors/bin.xml`:
+
+----
+<assembly>
+
+    <id>bin</id>
+
+    <formats>
+        <format>tar.gz</format>
+    </formats>
+
+    <fileSets>
+
+        <!-- Expanded Karaf Standard Distribution -->
+        <fileSet>
+            <directory>target/dependencies/apache-karaf-${karaf.version}</directory>
+            <outputDirectory>/</outputDirectory>
+            <excludes>
+                <exclude>**/demos/**</exclude>
+                <exclude>bin/**</exclude>
+                <exclude>etc/system.properties</exclude>
+                <exclude>etc/users.properties</exclude>
+                <exclude>etc/org.apache.karaf.features.cfg</exclude>
+                <exclude>etc/org.ops4j.pax.logging.cfg</exclude>
+                <exclude>LICENSE</exclude>
+                <exclude>NOTICE</exclude>
+                <exclude>README</exclude>
+                <exclude>RELEASE-NOTES</exclude>
+                <exclude>karaf-manual*.html</exclude>
+                <exclude>karaf-manual*.pdf</exclude>
+            </excludes>
+        </fileSet>
+
+        <!-- Copy over bin/* separately to get the correct file mode -->
+        <fileSet>
+            <directory>target/dependencies/apache-karaf-${karaf.version}</directory>
+            <outputDirectory>/</outputDirectory>
+            <includes>
+                <include>bin/admin</include>
+                <include>bin/karaf</include>
+                <include>bin/start</include>
+                <include>bin/stop</include>
+            </includes>
+            <fileMode>0755</fileMode>
+        </fileSet>
+
+        <!-- Copy over jar files -->
+        <fileSet>
+            <directory>target/dependencies</directory>
+            <includes>
+                <include>my-custom.jar</include>
+            </includes>
+            <outputDirectory>/lib/</outputDirectory>
+        </fileSet>
+
+        <fileSet>
+            <directory>src/main/distribution</directory>
+            <outputDirectory>/</outputDirectory>
+            <fileMode>0644</fileMode>
+        </fileSet>
+        <fileSet>
+            <directory>target/classes/etc</directory>
+            <outputDirectory>/etc/</outputDirectory>
+            <lineEnding>unix</lineEnding>
+            <fileMode>0644</fileMode>
+        </fileSet>
+
+        <fileSet>
+            <directory>target/features-repo</directory>
+            <outputDirectory>/system</outputDirectory>
+        </fileSet>
+
+    </fileSets>
+
+    <files>
+        <file>
+            <source>${basedir}/target/dependencies/apache-karaf-${karaf.version}/bin/karaf</source>
+            <outputDirectory>/bin/</outputDirectory>
+            <destName>my-custom</destName>
+            <fileMode>0755</fileMode>
+            <lineEnding>unix</lineEnding>
+        </file>
+        <file>
+            <source>${basedir}/target/classes/features.xml</source>
+            <outputDirectory>/system/my.groupid/my-features/${project.version}</outputDirectory>
+            <destName>my-features-${project.version}-features.xml</destName>
+            <fileMode>0644</fileMode>
+            <lineEnding>unix</lineEnding>
+        </file>
+    </files>
+
+</assembly>
+----
+
+To build your custom Karaf distribution, just run:
+
+----
+mvn install
+----
+
+You will find your Karaf custom distribution tar.gz in the target directory.
+
+==== Custom distribution examples
+
+* [Apache ServiceMix 4|http://svn.apache.org/repos/asf/servicemix/smx4/features/trunk/assemblies/]
+* [Apache ServiceMix NMR|http://svn.apache.org/repos/asf/servicemix/smx4/nmr/trunk/bundle/]
+* [BuildProcess BuildEraser|http://buildprocess.svn.sourceforge.net/viewvc/buildprocess/builderaser/trunk/assembly/]

http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/developer-guide/debugging.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/developer-guide/debugging.adoc b/manual/src/main/asciidoc/developer-guide/debugging.adoc
new file mode 100644
index 0000000..d21496a
--- /dev/null
+++ b/manual/src/main/asciidoc/developer-guide/debugging.adoc
@@ -0,0 +1,177 @@
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+=== Troubleshooting, Debugging, Profiling, and Monitoring
+
+==== Troubleshooting
+
+===== Logging
+
+Logging is easy to control through the console, with commands grouped under `log` shell. To learn about the available
+logging commands type:
+
+----
+karaf@root> log<tab>
+
+log:display              log:display-exception    log:get                  log:set
+karaf@root>
+----
+
+Typical usage is:
+ 
+. Use `log:set` to dynamically change the global log level
+. Execute the problematic operation
+. Use `log:display` (or `log:display-exception` to display the log
+
+===== Worst Case Scenario
+
+If you end up with a Karaf in a really bad state (i.e. you can not boot it anymore) or you just want to revert to a
+clean state quickly, you can safely remove the `data` directory just in the installation directory.  This folder
+contains transient data and will be recreated if removed when you relaunch Karaf.
+You may also want to remove the files in the `deploy` folder to avoid them being automatically installed when Karaf
+is started the first time.
+
+==== Debugging
+
+Usually, the easiest way to debug Karaf or any application deployed onto it is to use remote debugging.
+Remote debugging can be easily activated by using the `debug` parameter on the command line.
+
+----
+> bin/karaf debug
+----
+
+or on Windows
+
+----
+> bin\karaf.bat debug
+----
+
+Another option is to set the `KARAF_DEBUG` environment variable to `TRUE`.
+
+This can be done using the following command on Unix systems:
+
+----
+export KARAF_DEBUG=true
+----
+
+On Windows, use the following command
+
+----
+set KARAF_DEBUG=true
+----
+
+Then, you can launch Karaf using the usual way:
+
+----
+bin/karaf
+----
+
+or
+
+----
+bin\karaf.bat
+----
+
+Last, inside your IDE, connect to the remote application (the default port to connect to is 5005).
+
+This option works fine when it is needed to debug a project deployed top of Apache Karaf. Nervertheless, you will be blocked
+if you would like to debug the server Karaf. In this case, you can change the following parameter suspend=y in the
+karaf.bat script file. That will cause the JVM to pause just before running main() until you attach a debugger then it
+will resume the execution.  This way you can set your breakpoints anywhere in the code and you should hit them no matter
+how early in the startup they are.
+
+----
+export DEFAULT_JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005'
+----
+
+and on Windows,
+
+----
+set DEFAULT_JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005'
+----
+
+==== Profiling
+
+===== jVisualVM
+
+You have to edit the `etc/config.properties` configuration file to add the jVisualVM package:
+
+----
+org.osgi.framework.bootdelegation=...,org.netbeans.lib.profiler.server
+----
+
+Run Karaf from the console, and you should now be able to connect using jVisualVM.
+
+===== YourKit
+
+You need a few steps to be able to profile Karaf using YourKit.
+
+The first one is to edit the `etc/config.properties` configuration file and add the following property:
+
+----
+org.osgi.framework.bootdelegation=...,com.yourkit.*
+----
+
+Then, set the `JAVA_OPTS` environment variable:
+
+----
+export JAVA_OPTS='-Xmx512M -agentlib:yjpagent'
+----
+
+or, on Windows
+
+----
+set JAVA_OPTS='-Xmx512M -agentlib:yjpagent'
+----
+
+Run Karaf from the console, and you should now be able to connect using YourKit standalone or from your favorite IDE.
+
+==== Monitoring
+
+Karaf uses JMX for monitoring and management of all Karaf components.
+
+The JMX connection could be:
+
+* local using the process id
+
+image::jconsole_connect.jpg[]
+
+* remote using the `rmiRegistryPort` property defined in `etc/org.apache.karaf.management.cfg` file.
+
+Using JMX, you can have a clean overview of the running Karaf instance:
+
+* A overview with graphics displaying the load in terms of thread, heap/GC, etc:
+
+image::jconsole_overview.jpg[]
+
+* A thread overview:
+
+image::jconsole_threads.jpg[]
+
+* A memory heap consumption, including "Perform GC" button:
+
+image::jconsole_memory.jpg[]
+
+* A complete JVM summary, with all number of threads, etc:
+
+image::jconsole_summary.jpg[]
+
+You can manage Karaf features like you are in the shell. For example, you have access to the Admin service MBean,
+allowing you to create, rename, destroy, change SSH port, etc. Karaf instances:
+
+image::jconsole_admin.jpg[]
+
+You can also manage Karaf features MBean to list, install, and uninstall Karaf features:
+
+image::jconsole_features.jpg[]

http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/developer-guide/dev-cdi.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/developer-guide/dev-cdi.adoc b/manual/src/main/asciidoc/developer-guide/dev-cdi.adoc
new file mode 100644
index 0000000..9e64e35
--- /dev/null
+++ b/manual/src/main/asciidoc/developer-guide/dev-cdi.adoc
@@ -0,0 +1,15 @@
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+=== CDI
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/developer-guide/developer-commands.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/developer-guide/developer-commands.adoc b/manual/src/main/asciidoc/developer-guide/developer-commands.adoc
new file mode 100644
index 0000000..59c4df5
--- /dev/null
+++ b/manual/src/main/asciidoc/developer-guide/developer-commands.adoc
@@ -0,0 +1,242 @@
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+=== Developer commands
+
+As you can see in the users guide, Apache Karaf is an enterprise ready OSGi container.
+
+It's also a container designed to simplify the life for developers and administrators to get details about the
+running container.
+
+==== Dump
+
+If you encounter issues like performance degradations, weird behaviour, it could be helpful to have a kind of snapshot
+about the current activity of the container.
+
+The `dev:dump-create` command creates a dump file containing:
+
+* the `bundles.txt` file contains the list of all OSGi bundles, with id, symbolic name, version, current status
+* the `environment.txt` file contains details about Apache Karaf, OSGi framework, Operating System, JVM, system
+ properties, threads count, classes loaded
+* the `features.txt` file contains the list of Apache Karaf features repositories, features with version, current
+ status, and bundles provided.
+* the `threads.txt` file contains a thread dump, with all threads, waiting status, etc.
+* the `log` folder contains the `data/log` folder, with all log files.
+
+By default, the `dev:dump-create` command creates a zip file in the `KARAF_BASE` folder, with the timestamp of the
+dump creation:
+
+----
+karaf@root()> dev:dump-create
+Diagnostic dump created.
+----
+
+We can see the file generated in the `KARAF_BASE` folder:
+
+----
+$ cd /opt/apache-karaf-3.0.0
+$ ls -lh *.zip
+-rw-r--r-- 1 user group 11K Dec 23 16:08 2013-12-23_160858.zip
+----
+
+You can specify the file name of the zip archive:
+
+----
+karaf@root()> dev:dump-create mydump.zip
+Diagnostic dump created.
+----
+
+Instead of a zip archive, you can create the dump (exploded) in a directory using the `-d` (`--directory`) option:
+
+----
+karaf@root()> dev:dump-create -d /tmp/mydump
+Diagnostic dump created.
+----
+
+==== Diagnostic
+
+It's not always easy for the developers to understand why a bundle is not active.
+
+It could be because the Activator failed, the Blueprint container start failed, etc.
+
+The `bundle:diag` command gives you details about a bundle is not active:
+
+----
+karaf@root()> bundle:diag
+Apache ServiceMix :: Bundles :: avro-ipc (81)
+---------------------------------------------
+Status: Installed
+Unsatisfied Requirements:
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=javax.servlet)(version>=2.5.0)(!(version>=3.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=javax.servlet.http)(version>=2.5.0)(!(version>=3.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.data)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.file)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.generic)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.io)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.reflect)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.specific)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.util)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity)
+[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity.app)
+[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity.context)
+[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity.exception)
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.bootstrap)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.buffer)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.channel)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.channel.group)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.channel.socket.nio)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.handler.codec.frame)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.handler.codec.oneone)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.handler.execution)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty)(version>=6.1.0)(!(version>=7.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty.bio)(version>=6.1.0)(!(version>=7.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty.nio)(version>=6.1.0)(!(version>=7.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty.servlet)(version>=6.1.0)(!(version>=7.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.resource)(version>=6.1.0)(!(version>=7.0.0)))
+----
+
+==== Dynamic import
+
+The `bundle:dynamic-import` command allows you to enable or disable the dynamic import of a given bundle:
+
+----
+karaf@root()> bundle:dynamic-import 77
+Enabling dynamic imports on bundle org.apache.karaf.config.core [77]
+----
+
+The purpose of dynamic import is to allow a bundle to be wired up to packages that may not be knwon about in advance.
+When a class is requested, if it cannot be solved via the bundle's existing imports, the dynamic import allows other
+bundles to be considered for a wiring import to be added.
+
+The `bundle:dynamic-import` command allows or doesn't allow this behaviour.
+
+==== OSGi framework
+
+The `system:framework` command allows to display the current OSGi framework in use, and enable/disable debugging inside the OSGi framework.
+
+----
+karaf@root()> system:framework
+Current OSGi framework is felix
+karaf@root()> system:framework -debug
+Enabling debug for OSGi framework (felix)
+karaf@root()> system:framework -nodebug
+Disabling debug for OSGi framework (felix)
+----
+
+==== Stack traces printout
+
+The `shell:stack-traces-print` command prints the full stack trace when the execution of a command
+throws an exception.
+
+You can enable or disable this behaviour by passing true (to enable) or false (to disable) on the command on the fly:
+
+----
+karaf@root()> stack-traces-print
+Printing of stacktraces set to true
+karaf@root()> bundle:start
+java.lang.RuntimeException: Access to system bundle 0 denied. You can override with -f
+        at org.apache.karaf.bundle.command.BundlesCommand.assertNoSystemBundles(BundlesCommand.java:57)
+        at org.apache.karaf.bundle.command.BundlesCommand.doExecute(BundlesCommand.java:48)
+        at org.apache.karaf.bundle.command.BundlesCommandWithConfirmation.doExecute(BundlesCommandWithConfirmation.java:41)
+        at org.apache.karaf.shell.console.AbstractAction.execute(AbstractAction.java:33)
+        at org.apache.karaf.shell.console.OsgiCommandSupport.execute(OsgiCommandSupport.java:39)
+        at org.apache.karaf.shell.commands.basic.AbstractCommand.execute(AbstractCommand.java:33)
+        at sun.reflect.GeneratedMethodAccessor30.invoke(Unknown Source)
+        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
+        at java.lang.reflect.Method.invoke(Method.java:601)
+        at org.apache.aries.proxy.impl.ProxyHandler$1.invoke(ProxyHandler.java:54)
+        at org.apache.aries.proxy.impl.ProxyHandler.invoke(ProxyHandler.java:119)
+        at org.apache.karaf.shell.console.commands.$BlueprintCommand14083304.execute(Unknown Source)
+        at sun.reflect.GeneratedMethodAccessor30.invoke(Unknown Source)
+        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
+        at java.lang.reflect.Method.invoke(Method.java:601)
+        at org.apache.aries.proxy.impl.ProxyHandler$1.invoke(ProxyHandler.java:54)
+        at org.apache.aries.proxy.impl.ProxyHandler.invoke(ProxyHandler.java:119)
+        at org.apache.karaf.shell.console.commands.$BlueprintCommand14083304.execute(Unknown Source)
+        at org.apache.felix.gogo.runtime.CommandProxy.execute(CommandProxy.java:78)
+        at org.apache.felix.gogo.runtime.Closure.executeCmd(Closure.java:477)
+        at org.apache.felix.gogo.runtime.Closure.executeStatement(Closure.java:403)
+        at org.apache.felix.gogo.runtime.Pipe.run(Pipe.java:108)
+        at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:183)
+        at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:120)
+        at org.apache.felix.gogo.runtime.CommandSessionImpl.execute(CommandSessionImpl.java:89)
+        at org.apache.karaf.shell.console.impl.jline.ConsoleImpl$DelegateSession.execute(ConsoleImpl.java:497)
+        at org.apache.karaf.shell.console.impl.jline.ConsoleImpl.run(ConsoleImpl.java:198)
+        at java.lang.Thread.run(Thread.java:722)
+        at org.apache.karaf.shell.console.impl.jline.ConsoleFactoryService$3.doRun(ConsoleFactoryService.java:118)
+        at org.apache.karaf.shell.console.impl.jline.ConsoleFactoryService$3$1.run(ConsoleFactoryService.java:109)
+        at java.security.AccessController.doPrivileged(Native Method)
+        at org.apache.karaf.jaas.modules.JaasHelper.doAs(JaasHelper.java:47)
+        at org.apache.karaf.shell.console.impl.jline.ConsoleFactoryService$3.run(ConsoleFactoryService.java:107)
+karaf@root()> stack-traces-print false
+Printing of stacktraces set to false
+karaf@root()> bundle:start
+Error executing command: Access to system bundle 0 denied. You can override with -f
+----
+
+==== Bundle tree
+
+The `bundle:tree-show` command shows the bundle dependency tree based on the wiring information of a given single bundle
+ID.
+
+----
+karaf@root()> bundle:tree-show 40
+Bundle org.ops4j.pax.url.wrap [40] is currently ACTIVE
+
+org.ops4j.pax.url.wrap [40]
++- org.ops4j.base.util.property [14]
++- org.ops4j.pax.url.commons [49]
+|  +- org.ops4j.base.util.property [14]
+|  +- org.ops4j.pax.logging.pax-logging-api [23]
+|  +- org.ops4j.pax.swissbox.property [31]
+|  |  +- org.ops4j.base.util.property [14]
+|  |  +- org.ops4j.base.lang [41]
+|  +- org.apache.felix.configadmin [43]
+|  |  +- org.ops4j.pax.logging.pax-logging-api [23]
+|  +- org.ops4j.base.lang [41]
++- org.ops4j.pax.logging.pax-logging-api [23]
++- org.ops4j.pax.swissbox.bnd [25]
+|  +- biz.aQute.bndlib [30]
+|  |  +- org.apache.servicemix.bundles.junit [36]
+|  +- org.ops4j.pax.logging.pax-logging-api [23]
+|  +- org.ops4j.base.lang [41]
++- org.apache.felix.configadmin [43]
++- org.ops4j.base.net [29]
+|  +- org.ops4j.base.monitors [37]
+|  +- org.ops4j.base.lang [41]
++- org.ops4j.base.lang [41]
+----
+
+==== Watch
+
+The `bundle:watch` command enables watching the local Maven repository for updates on bundles.
+If the bundle file changes on the Maven repository, Apache Karaf will automatically update the bundle.
+
+The `bundle:watch` allows you to configure a set of URLs to monitore. All bundles bundles whose location matches the
+given URL will be automatically updated. It avoids needing to manually update the bundles or even copy the bundle to the
+system folder.
+
+[NOTE]
+====
+Only Maven based URLs and Maven SNAPSHOTs will actually be updated automatically.
+====
+
+The following command:
+
+----
+karaf@root> dev:watch *
+----
+
+will monitore all bundles that have a location matching mvn:* and having '-SNAPSHOT' in their URL.

http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/developer-guide/extending.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/developer-guide/extending.adoc b/manual/src/main/asciidoc/developer-guide/extending.adoc
new file mode 100644
index 0000000..8190211
--- /dev/null
+++ b/manual/src/main/asciidoc/developer-guide/extending.adoc
@@ -0,0 +1,420 @@
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+=== Extending
+
+Apache Karaf is a very flexible container that you can extend very easily.
+
+==== Console
+
+In this section, you will see how to extend the console by adding your own command.
+
+We will leverage Apache Maven to create and build the OSGi bundle.
+This OSGi bundle will use Blueprint. We don't cover the details of OSGi bundle and Blueprint, see the specific
+sections for details.
+
+===== Create the Maven project
+
+To create the Maven project, we can:
+
+* use a Maven archetype
+* create by hand
+
+====== Using archetype
+
+The Maven Quickstart archetype can create an empty Maven project where you can put your project definition.
+
+You can directly use:
+
+----
+mvn archetype:create \
+  -DarchetypeArtifactId=maven-archetype-quickstart \
+  -DgroupId=org.apache.karaf.shell.samples \
+  -DartifactId=shell-sample-commands \
+  -Dversion=1.0-SNAPSHOT
+----
+
+It results to a ready to use project, including a `pom.xml`.
+
+You can also use Maven archetype in interactive mode. You will have to answer to some questions used to generate
+the project with the `pom.xml`:
+
+----
+mvn archetype:generate
+Choose a number:  (1/2/3/4/5/6/7/.../32/33/34/35/36) 15: : 15
+Define value for groupId: : org.apache.karaf.shell.samples
+Define value for artifactId: : shell-sample-commands
+Define value for version:  1.0-SNAPSHOT: : 
+Define value for package: : org.apache.karaf.shell.samples
+----
+
+===== By hand
+
+Alternatively, you can simply create the directory `shell-sample-commands` and create the `pom.xml` file inside it:
+
+----
+<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>
+
+  <groupId>org.apache.karaf.shell.samples</groupId>
+  <artifactId>shell-sample-commands<artifactId>
+  <packaging>bundle</packaging>
+  <version>1.0-SNAPSHOT</version>
+  <name>shell-sample-commmands</name>
+
+
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.karaf.shell</groupId>
+      <artifactId>org.apache.karaf.shell.console</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <version>3.8.1</version>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.felix</groupId>
+        <artifactId>maven-bundle-plugin</artifactId>
+        <version>${felix.plugin.version}</version>
+        <configuration>
+          <instructions>
+            <Import-Package>
+              org.apache.felix.service.command,
+              org.apache.karaf.shell.commands,
+              org.apache.karaf.shell.console,
+              *
+            </Import-Package>
+          </instructions>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+
+</project>
+----
+
+===== Configuring for Java 6/7
+
+We are using annotations to define commands, so we need to ensure Maven will actually use JDK 1.6 or 1.7 to compile the jar.
+Just add the following snippet after the `dependencies` section.
+
+----
+<build>
+  <plugins>
+    <plugin>
+      <groupId>org.apache.maven.plugins</groupId>
+      <artifactId>maven-compiler-plugin</artifactId>
+      <configuration>
+        <target>1.6</target>
+        <source>1.6</source>
+      </configuration>
+    </plugin>
+  </plugins>
+</build>
+----
+
+===== Loading the project in your IDE
+
+We can use Maven to generate the needed files for your IDE:
+
+Inside the project, run the following command
+
+----
+mvn eclipse:eclipse
+----
+
+or
+
+----
+mvn idea:idea
+----
+
+The project files for your IDE should now be created. Just open the IDE and load the project.
+
+===== Creating a basic command class
+
+We can now create the command class `HelloShellCommand.java`
+
+----
+package org.apache.karaf.shell.samples;
+
+import Command;
+import org.apache.karaf.shell.console.OsgiCommandSupport;
+
+@Command(scope = "test", name = "hello", description="Says hello")
+public class HelloShellCommand extends OsgiCommandSupport {
+
+    @Override
+    protected Object doExecute() throws Exception {
+        System.out.println("Executing Hello command");
+        return null;
+    }
+}
+----
+
+===== Blueprint definition
+
+Blueprint is an injection framework for OSGi. It allows you to declare beans in a XML file and contains specific statement for OSGi services.
+
+For the command, we use Blueprint to create the command bean and register as an OSGi service.
+
+The blueprint definition file is located in the `OSGI-INF/blueprint` folder of our bundle.
+
+If you don't have the `src/main/resources` directory yet, create it.
+
+----
+mkdir src/main/resources
+----
+
+Then, re-generate the IDE project files and reload it so that this folder is now recognized as a source folder.
+
+Inside this directory, create the `OSGI-INF/blueprint/` directory and put the following file inside (the name of this file has no impact at all):
+
+----
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+
+    <command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.1.0">
+        <command>
+            <action class="org.apache.karaf.shell.samples.HelloShellCommand"/>
+        </command>
+    </command-bundle>
+
+</blueprint>
+----
+
+===== Compile
+
+Let's try to build the jar.  Remove the test classes and sample classes if you used the artifact, then from the command line, run:
+
+----
+mvn install
+----
+
+The end of the maven output should look like:
+----
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESSFUL
+[INFO] ------------------------------------------------------------------------
+----
+
+===== Test
+
+Launch Apache Karaf and install your bundle:
+
+----
+karaf@root()> bundle:install -s mvn:org.apache.karaf.shell.samples/shell-sample-commands/1.0-SNAPSHOT
+----
+
+Let's try running the command:
+
+----
+karaf@root()> test:hello
+Executing Hello command
+----
+
+===== Command completer
+
+A completer allows you to automatically complete a command argument using <tab>. A completer is simply a bean which is
+injected to a command.
+
+Of course to be able to complete it, the command should require an argument.
+
+===== Command argument
+
+We add an argument to the HelloCommand:
+
+----
+package org.apache.karaf.shell.samples;
+
+import Command;
+import Argument;
+import org.apache.karaf.shell.console.OsgiCommandSupport;
+
+@Command(scope = "test", name = "hello", description="Says hello")
+public class HelloShellCommand extends OsgiCommandSupport {
+
+    @Argument(index = 0, name = "name", description = "The name that sends the greet.", required = true, multiValued = false)
+    String name = null;
+
+    @Override
+    protected Object doExecute() throws Exception {
+        System.out.println("Hello " + name);
+        return null;
+    }
+}
+----
+
+The Blueprint configuration file is the same as previously.
+
+===== Completer bean
+
+A completer is a bean which implements the Completer interface:
+
+----
+package org.apache.karaf.shell.samples;
+
+import org.apache.karaf.shell.console.completer.StringsCompleter;
+import org.apache.karaf.shell.console.Completer;
+
+/**
+ * <p>
+ * A very simple completer.
+ * </p>
+ */
+public class SimpleNameCompleter implements Completer {
+
+ /**
+  * @param buffer the beginning string typed by the user
+  * @param cursor the position of the cursor
+  * @param candidates the list of completions proposed to the user
+  */
+ public int complete(String buffer, int cursor, List candidates) {
+   StringsCompleter delegate = new StringsCompleter();
+   delegate.getStrings().add("Mike");
+   delegate.getStrings().add("Eric");
+   delegate.getStrings().add("Jenny");
+   return delegate.complete(buffer, cursor, candidates);
+ }
+
+}
+----
+
+===== Blueprint with completer
+
+Using Blueprint, you can "inject" the completer linked to your command. The same completer could be used for several commands and a command can have several completers:
+
+----
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+
+    <command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.1.0">
+        <command>
+            <action class="org.apache.karaf.shell.samples.HelloShellCommand"/>
+            <completers>
+                <ref component-id="simpleNameCompleter"/>
+                <null/>
+            </completers>
+        </command>
+    </command-bundle>
+
+    <bean id="simpleNameCompleter" class="org.apache.karaf.shell.samples.SimpleNameCompleter"/>
+
+</blueprint>
+----
+
+You can have multiple completers for a single class, each matching a command argument.
+The order of the completers must match the order of the arguments, in order to have the desirable results.
+
+===== Completers for option values
+
+Quite often your commands will not have just arguments, but also options. You can provide completers for option values.
+The snippet below shows the HelloShellCommand with an option to specify what the greet message will be.
+
+----
+package org.apache.karaf.shell.samples;
+
+import Command;
+import Argument;
+import org.apache.karaf.shell.console.OsgiCommandSupport;
+
+@Command(scope = "test", name = "hello", description="Says hello")
+public class HelloShellCommand extends OsgiCommandSupport {
+
+    @Argument(index = 0, name = "name", description = "The name that sends the greet.", required = true, multiValued = false)
+    String name = null;
+
+    @Option(name = "-g", aliases = "--greet", description = "The configuration pid", required = false, multiValued = false)
+    String greet = "Hello;
+
+    @Override
+    protected Object doExecute() throws Exception {
+        System.out.println(greet + " " + name);
+        return null;
+    }
+}
+----
+
+We can now specify a completer for the greet option. All that is required is to add an optional-completer element in the
+blueprint configuration that will associate a completer with the -g option or its --greet alias.
+
+----
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+
+    <command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.1.0">
+        <command>
+            <action class="org.apache.karaf.shell.samples.HelloShellCommand"/>
+            <completers>
+                <ref component-id="simpleNameCompleter"/>
+                <null/>
+            </completers>
+            <optional-completers>
+                <entry key="-g" value-ref="greetCompleter"/>
+            </optional-completers>
+        </command>
+    </command-bundle>
+
+    <bean id="simpleNameCompleter" class="org.apache.karaf.shell.samples.SimpleNameCompleter"/>
+    <bean id="greetCompleter" class="org.apache.karaf.shell.samples.GreetCompleter"/>
+
+</blueprint>
+----
+
+===== Completers with state
+
+Some times we want to tune the behavior of the completer depending on the commands already executed, in the current shell
+or even the rest of the arguments that have been already passed to the command. Such example is the config:set-property
+command which will provide auto completion for only for the properties of the pid specified by a previously issued config:edit
+command or by the option --pid.
+
+This is done by accessing the CommandSession object which holds the state of the console. To get access to the CommandSession:
+
+----
+CommandSession session = CommandSessionHolder.getSession();
+----
+
+CommandSession provides map like methods for storing key/value pairs and can be used to put/get the state.
+
+If you want to get access to the list of arguments that is already passed to the command, you can simply:
+
+----
+ArgumentCompleter.ArgumentList list = (ArgumentCompleter.ArgumentList) commandSession.get(ArgumentCompleter.ARGUMENTS_LIST);
+----
+
+===== Test
+
+Launch a Karaf instance and run the following command to install the newly created bundle:
+
+----
+karaf@root()> bundle:install -s mvn:org.apache.karaf.shell.samples/shell-sample-commands/1.0-SNAPSHOT
+----
+
+Let's try running the command:
+
+----
+karaf@root> test:hello <tab>
+ one    two    three
+----
+
+==== WebConsole
+
+You can also extend the Apache Karaf WebConsole by providing and installing a webconsole plugin.o
+
+A plugin is an OSGi bundle that register a Servlet as an OSGi service with some webconsole properties.

http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/developer-guide/github-contributions.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/developer-guide/github-contributions.adoc b/manual/src/main/asciidoc/developer-guide/github-contributions.adoc
new file mode 100644
index 0000000..e9c631c
--- /dev/null
+++ b/manual/src/main/asciidoc/developer-guide/github-contributions.adoc
@@ -0,0 +1,82 @@
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+=== Github Contributions
+
+Some people prefer to make contributions to karaf source via github. If you are one of them, this is for you!
+
+==== Introduction
+
+Apache Karaf is available as a periodically replicated mirror on: https://github.com/apache/karaf
+
+==== Suggested Workflow
+
+. Make a fork of karaf repo github mirror
+. Do all your new work on your own karaf fork
+. When ready, file a jira issue [https://issues.apache.org/jira/browse/KARAF], attach the link to your github pull request, and ask for a review
+. One of karaf committers will discuss your pull request on github; and at some point your pull request will be accepted
+. When your pull request is accepted, squash it into a single commit and attach single patch file to the original jira, with ASF grant check box selected
+. Now pray to your favorite ASF committer to really accept the patch :-)
+. When your patch is committed to the svn, and you can verify it in the latest karaf snapshot, close your pull request on github
+
+==== License Reminder
+
+in order for your contributions to be accepted:
+
+* all files must contain ASL license grant header
+* you must select ASF grant check box when attaching patch to the jira
+
+==== How to Generate a One-File-Patch Via Throw-Away Branch
+
+here is one way to generate squash of your commits:
+
+http://stackoverflow.com/questions/616556/how-do-you-squash-commits-into-one-patch-with-git-format-patch
+
+----
+
+#
+# 'archon' referers to karaf mirror
+# 'origin' referers to your own fork
+#
+
+# attach karaf mirror as remote, if not done yet
+git remote add archon https://github.com/apache/karaf
+
+# fetch latest karaf mirror
+git fetch archon 
+
+# ensure you are on your fork trunk
+git checkout origin/trunk
+
+# kill previous patch delivery, if you had one
+git branch -D delivery
+
+# make new delivery throw-away branch, based on latest karaf mirror
+git branch delivery archon/trunk
+
+# use it
+git checkout delivery
+
+# squash all your local development into a single commit
+git merge --squash trunk
+
+# commit it to the delivery branch
+git commit -m "delivery"
+
+# generate a patch file against the mirror
+git format-patch archon/trunk
+
+----
+
+root of your karaf source now contains a file named "0001-delivery.patch.txt" (please attach the .txt ending;this will allow commiters to open your patch directly in the browser and give it a short look there) which you should attach to your karaf jira, and ask to commit to the svn trunk

http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/developer-guide/karaf-maven-plugin.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/developer-guide/karaf-maven-plugin.adoc b/manual/src/main/asciidoc/developer-guide/karaf-maven-plugin.adoc
new file mode 100644
index 0000000..4635c44
--- /dev/null
+++ b/manual/src/main/asciidoc/developer-guide/karaf-maven-plugin.adoc
@@ -0,0 +1,456 @@
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+=== Using the karaf-maven-plugin
+
+The Karaf Maven plugin allows you:
+
+    * to work with Karaf features: validate a features descriptor, add features bundle into a repository, create a KAR archive from a features descriptor, etc.
+    * to create Karaf commands help: it generates help from Karaf commands
+    * to modify Karaf instances and create distributions
+
+==== Packagings
+The most generally useful features of the karaf-maven-plugin are exposed as packagings.  To use the packagings the pom or an ancestor must configure the karaf-maven-plugin with extensions:
+
+----
+    <build>
+        <pluginManagement>
+            <plugins>
+                <plugin>
+                    <groupId>org.apache.karaf.tooling</groupId>
+                    <artifactId>karaf-maven-plugin</artifactId>
+                    <version>${project.version}</version>
+                    <extensions>true</extensions>
+                </plugin>
+            </plugins>
+        </pluginManagement>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.karaf.tooling</groupId>
+                <artifactId>karaf-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+----
+
+Then specify the packaging in your project as usual, e.g.
+
+----
+    <packaging>kar</packaging>
+----
+
+|===
+|Packaging |Description
+
+|`feature`
+|The feature packaging generates a features.xml descriptor using the `karaf:features-generate-descriptor`
+
+|`kar`
+|The kar packaging generates a features.xml descriptor using the `karaf:features-generate-descriptor` and then packages a kar using the `karaf:features-create-kar`
+
+|`karaf-assembly`
+|Assembles a Karaf server based on the features descriptors and kar files listed as Maven dependencies
+|===
+
+==== Commands goals
+
+The `karaf-maven-plugin` is able to generate documentation for Karaf commands.
+
+===== `karaf:commands-generate-help`
+
+The `karaf:commands-generate-help` goal generates documentation containing Karaf commands help.
+
+It looks for Karaf commands in the current project class loader and generates the help as displayed with the --help
+option in the Karaf shell console.
+
+====== Example
+
+The example below generates help for the commands in the current project:
+
+----
+<project>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.karaf.tooling</groupId>
+        <artifactId>karaf-maven-plugin</artifactId>
+        <version>${project.version}</version>
+
+        <executions>
+          <execution>
+            <id>document-commands</id>
+            <phase>generate-resources</phase>
+            <goals>
+              <goal>commands-generate-help</goal>
+            </goals>
+            <configuration>
+              <targetFolder>${project.build.directory}/docbook/sources</targetFolder>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+</project>
+----
+
+====== Parameters
+
+|===
+|Name |Type |Description
+
+|`targetFolder`
+|`File`
+|The directory where the documentation output files are to be generated. Default value: ${project.build.directory}/docbkx/sources
+
+|`format`
+|`String`
+|The output format (docbx, asciidoc, or conf) of the commands documentation. Default value: docbx
+
+|`classLoader`
+|`String`
+|The class loader to use in loading the commands. Default value: ${project}
+|===
+
+==== Features goals
+
+Normally you should use the features or kar packagings instead of these individual goals.
+The `karaf-maven-plugin` provides several goals to help you create and validate features XML descriptors as well as leverage your features to create a custom Karaf distribution.
+
+===== `karaf:features-generate-description`
+
+Except in unusual circumstances, use the `<packaging>feature</packaging>` to run this goal.
+
+The `karaf:features-generate-descriptor` goal generates a features XML file based on the Maven dependencies.
+By default, it will follow Maven transitive dependencies, stopping when it encounters bundles already present in features that are Maven dependencies.
+
+A record of the dependency tree search can be found in target/history/treeListing.txt.
+
+You can track dependency changes and warn or fail on change.
+
+====== Configuration
+
+Specify the packaging as a top level element
+
+----
+<packaging>feature</packaging>
+----
+
+You can supply a feature descriptor to extend in `src/main/feature/feature.xml`.
+
+|===
+|Parameter Name |Type |Description
+
+|aggregateFeatures
+|boolean (false)
+|Specifies processing of feature repositories that are (transitive) Maven dependencies. If false, all features in these repositories become dependencies of the generated feature.  If true, all features in these repositories are copied into the generated feature repository.
+
+|startLevel
+|int
+|The start level for the bundles determined from Maven dependencies. This can be overridden by specifying the bundle in the source feature.xml with the desired startlevel.
+
+|includeTransitiveDependency
+|boolean (true)
+|Whether to follow Maven transitive dependencies.
+
+|checkDependencyChange
+|boolean (false)
+|Whether to record dependencies in `src/main/history.dependencies.xml` for change tracking.
+
+|warnOnDependencyChange
+|boolean (false)
+|whether to fail on changed dependencies (false, default) or warn in the build output (true).
+
+|logDependencyChanges
+|boolean (false)
+|If true, added and removed dependencies are shown in target/history.
+
+|overwriteChangedDependencies
+|boolean (false)
+|If true, the `src/main/history/dependencies.xml` file will be overwritten if it has changed.
+|===
+
+====== Example
+
+----
+<project>
+...
+  <packaging>feature</packaging>
+  <dependencies>
+    <dependency>
+      <groupId>org.apache</groupId>
+      <artifactId>bundle1</artifactId>
+      <version>1.0</version>
+    </dependency>
+  </dependencies>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.karaf.tooling</groupId>
+        <artifactId>karaf-maven-plugin</artifactId>
+        <version>${project.version}</version>
+        <extensions>true</extensions>
+          <configuration>
+            <startLevel>80</startLevel>
+            <aggregateFeatures>true</aggregateFeatures>
+          </configuration>
+        </plugin>
+    </plugins>
+  </build>
+</project>
+----
+
+===== `karaf:features-validate-description`
+
+The `karaf:features-validate-descriptor` goal validates a features XML descriptor by checking if all the required imports
+for the bundles defined in the features can be matched to a provided export.
+
+By default, the plugin tries to add the Karaf core features (standard and enterprise) in the repositories set.
+It means that it's not required to explicitly define the Karaf features descriptor in the repository section of your features descriptor.
+
+====== Example
+
+The example below validates the features defined in the `target/features.xml` by checking all the imports and exports.
+It reads the definition for the packages that are exported by the system bundle from the `src/main/resources/config.properties` file.
+
+----
+<project>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.karaf.tooling</groupId>
+        <artifactId>karaf-maven-plugin</artifactId>
+        <version>${project.version}</version>
+          <executions>
+            <execution>
+              <id>validate</id>
+              <phase>process-resources</phase>
+              <goals>
+                <goal>features-validate-descriptor</goal>
+              </goals>
+              <configuration>
+                <file>target/features.xml</file>
+                <karafConfig>src/main/resources/config.properties</karafConfig>
+              </configuration>
+            </execution>
+          </executions>
+          <dependencies>
+            <dependency>
+              <groupId>org.slf4j</groupId>
+              <artifactId>slf4j-simple</artifactId>
+              <version>1.4.3</version>
+	        </dependency>
+          </dependencies>
+        </plugin>
+    </plugins>
+  </build>
+</project>
+----
+
+====== Parameters
+
+|===
+|Name |Type |Description
+
+|`file`
+|`File`
+|The features XML descriptor file to validate. Default value: `${project.build.directory}/classes/features.xml`
+
+|`karafConfig`
+|`String`
+|The Karaf `config.properties` file to use during the validation process. Default value: `config.properties`
+
+|`jreVersion`
+|`String`
+|The JRE version that is used during the validation process. Default value: `jre-1.5`
+
+|`karafVersion`
+|`String`
+| The target Karaf version used to get the Karaf core features (standard and enterprise) \\ Default is the version of the plugin |
+
+|`repositories`
+|`String[]`
+|Additional features XML descriptors that will be used during the validation process
+|===
+
+===== `karaf:features-create-kar`
+
+Except in unusual circumstances, use the `<packaging>kar</packaging>` to run this goal.
+
+The `karaf:features-create-kar` goal assembles a KAR archive from a features XML descriptor file, normally generated in
+the same project with the `karaf:features-generate-descriptor` goal.
+
+====== kar layout
+
+There are two important directories in a kar:
+
+* `repository/`  contains a Maven structured repository of artifacts to be copied into the Karaf repository.
+The features descriptor and all the bundles mentioned in it are installed in this directory.
+* `resources/` contains other resources to be copied over the Karaf installation.
+
+Everything in `target/classes` is copied into the kar.
+Therefore resources you want installed into Karaf need to be in e.g. `src/main/resources/resources`.
+This choice is so other resources such as legal files from the maven-remote-resources-plugin can be included under META-INF in the kar, without getting installed into Karaf.
+
+====== Example
+
+----
+<project>
+...
+  <packaging>kar</packaging>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.karaf.tooling</groupId>
+        <artifactId>karaf-maven-plugin</artifactId>
+        <version>${project.version}</version>
+        <extensions>true</extensions>
+        <!-- There is no useful configuration for the kar mojo. The features-generate-descriptor mojo configuration may be useful -->
+      </plugin>
+    </plugins>
+  </build>
+</project>
+----
+
+==== Instances and distributions goals
+
+Normally you should use the karaf-assembly packaging instead of this individual goal.
+The `karaf-maven-plugin` helps you to build custom Karaf distributions or archives existing Karaf instances.
+
+===== `karaf:install-kars`
+
+===== `karaf:instance-create-archive`
+
+Normally this is run as part of the `karaf-assembly` packaging.
+
+The `karaf:instance-create-archive` goal packages a Karaf instance archive from a given assembled instance.
+
+Both tar.gz and zip formats are generated in the destination folder.
+
+====== Example
+
+The example below create archives for the given Karaf instance:
+
+----
+<project>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.karaf.tooling</groupId>
+        <artifactId>karaf-maven-plugin</artifactId>
+        <version>${project.version}</version>
+          <executions>
+            <execution>
+              <id>generate</id>
+              <phase>package</phase>
+              <goals>
+                <goal>instance-create-archive</goal>
+              </goals>
+              <configuration>
+                <destDir>${project.build.directory}</destDir>
+                <targetServerDirectory>${project.build.directory}/assembly</targetServerDirectory>
+                <targetFile>${project.file}</targetFile>
+              </configuration>
+            </execution>
+          </executions>
+        </plugin>
+    </plugins>
+  </build>
+</project>
+----
+
+====== Parameters
+
+|===
+|Name |Type |Description
+
+|`destDir`
+|`File`
+|The target directory of the project. Default value: ${project.build.directory}
+
+|`targetServerDirectory`
+|`File`
+|The location of the server repository. Default value: ${project.build.directory}/assembly
+
+|`targetFile`
+|`File`
+|The target file to set as the project's artifact. Default value: ${project.file}
+|===
+
+===== `karaf:features-add-to-repository`
+
+Consider using the karaf-assembly packaging which makes it easy to assemble a custom distribution in one step instead of this individual goal.
+
+The `karaf:features-add-to-repository` goal adds all the required bundles for a given set of features into directory.
+You can use this goal to create a `/system` directory for building your own Karaf-based distribution.
+
+By default, the Karaf core features descriptors (standard and enterprise) are automatically included in the descriptors set.
+
+====== Example
+
+The example below copies the bundles for the `spring` and `war` features defined in the Karaf features XML descriptor into the `target/features-repo` directory.
+
+----
+<project>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.karaf.tooling</groupId>
+        <artifactId>karaf-maven-plugin</artifactId>
+        <version>${project.version}</version>
+
+        <executions>
+          <execution>
+            <id>features-add-to-repo</id>
+            <phase>generate-resources</phase>
+            <goals>
+              <goal>features-add-to-repository</goal>
+            </goals>
+            <configuration>
+              <descriptors>
+                <descriptor>mvn:org.apache.karaf.features/standard/3.0.0/xml/features</descriptor>
+                <descriptor>mvn:my.groupid/my.artifactid/1.0.0/xml/features</descriptor>
+              </descriptors>
+              <features>
+                <feature>spring</feature>
+                <feature>war</feature>
+                <feature>my</feature>
+              </features>
+              <repository>target/features-repo</repository>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+</project>
+----
+
+====== Parameters
+
+|===
+|Name |Type |Description
+
+|`descriptors`
+|`String[]`
+|List of features XML descriptors where the features are defined
+
+|`features`
+|`String[]`
+|List of features that bundles should be copied to the repository directory
+
+|`repository`
+|`File`
+|The directory where the bundles will be copied by the plugin goal
+|===
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/karaf/blob/9f08eb9e/manual/src/main/asciidoc/developer-guide/scripting.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/developer-guide/scripting.adoc b/manual/src/main/asciidoc/developer-guide/scripting.adoc
new file mode 100644
index 0000000..947d718
--- /dev/null
+++ b/manual/src/main/asciidoc/developer-guide/scripting.adoc
@@ -0,0 +1,243 @@
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+=== Scripting
+
+In the console section of the users guide, we introduced the scripting support.
+
+==== Assignation
+
+You already know the first usage of scripting: execution of command.
+
+----
+karaf@root()> echo hello world
+hello world
+----
+
+You can also assign value to session variables:
+
+----
+karaf@root()> msg = "hello world"
+hello world
+----
+
+Once you have assigned a value to a variable, you can display this value using the "resolved" variable name:
+
+----
+karaf@root()> echo $msg
+hello world
+----
+
+The () are execution quotes (like the backquotes when you use bash on Unix).
+
+----
+karaf@root()> ($.context bundle 1) location
+mvn:org.apache.karaf.jaas/org.apache.karaf.jaas.modules/3.0.1-SNAPSHOT
+----
+
+The `$.context` access the context variables in the current session.
+We access to the `bundle` variable (an array containing all bundles), and we want to display the bundle location for
+the bundle at the index 1 in the bundle array.
+
+==== List, maps, pipes and closures
+
+Using [], you can define array variable:
+
+----
+karaf@root()> list = [1 2 a b]
+1
+2
+a
+b
+
+----
+
+You can also create a map if you put variables assignation in the array:
+
+----
+karaf@root()> map = [Jan=1 Feb=2 Mar=3]
+Jan                 1
+Feb                 2
+Mar                 3
+----
+
+Using the | character, you can pipe output from a command as an input to another one.
+
+For instance, you can access to the bundles context variables and send it as input to the grep command:
+
+----
+karaf@root()> ($.context bundles) | grep -i felix
+    0|Active     |    0|org.apache.felix.framework (4.2.1)
+   21|Active     |   11|org.apache.felix.fileinstall (3.2.6)
+   43|Active     |   10|org.apache.felix.configadmin (1.6.0)
+   51|Active     |   30|org.apache.felix.gogo.runtime (0.10.0)
+----
+
+You can assign name to script execution. It's what we use for alias:
+
+----
+karaf@root()> echo2 = { echo xxx $args yyy }
+echo xxx $args yyy
+karaf@root()> echo2 hello world
+xxx hello world yyy
+----
+
+==== Startup
+
+The `etc/shell.init.script` file is executed at startup in each shell session, allowing the definition of additional
+variables or aliases or even complex functions. It's like the bashrc or profile on Unix.
+
+==== Constants and variables
+
+Apache Karaf console provides a set of implicit constants and variables that you can use in your script.
+
+* `$.context` to access a bundle context
+* `$.variables` to access the list of defined variables
+* `$.commands` to access the list of defined commands
+
+The variables starting with a # that are defined as Function (such as closures) will be executed automatically:
+
+----
+karaf@root> \#inc = { var = "${var}i" ; $var }
+var = "${var}i" ; $var
+karaf@root> echo $inc
+i
+karaf@root> echo $inc
+ii
+karaf@root>
+----
+
+==== Built-in variables and commands
+
+Apache Karaf console provides built-in variable very useful for scripting:
+
+* `$args` retrieves the list of script parameters, given to the closure being executed
+* `$1 .. $999` retrieves the nth argument of the closure
+* `$it` (same as `$1`) is used in a loop to access the current iterator value
+
+Apache Karaf console provides commands for scripting:
+
+* `shell:if`
+* `shell:new`
+* `shell:each`
+* ...
+
+==== Leveraging existing Java capabilities (via reflection)
+
+Apache Karaf console supports loading and execution of Java classes.
+
+The `$karaf.lastException` implicit variable contains the latest Exception thrown.
+
+----
+karaf@root()> ($.context bundle) loadClass foo
+Error executing command: foo not found by org.apache.karaf.shell.console [17]
+karaf@root()> $karaf.lastException printStackTrace
+java.lang.ClassNotFoundException: foo not found by org.apache.karaf.shell.console [17]
+	at org.apache.felix.framework.BundleWiringImpl.findClassOrResourceByDelegation(BundleWiringImpl.java:1460)
+	at org.apache.felix.framework.BundleWiringImpl.access$400(BundleWiringImpl.java:72)
+	at org.apache.felix.framework.BundleWiringImpl$BundleClassLoader.loadClass(BundleWiringImpl.java:1843)
+	at java.lang.ClassLoader.loadClass(ClassLoader.java:247)
+	at org.apache.felix.framework.Felix.loadBundleClass(Felix.java:1723)
+	at org.apache.felix.framework.BundleImpl.loadClass(BundleImpl.java:926)
+	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+	at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
+	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
+	at java.lang.reflect.Method.invoke(Method.java:597)
+	at org.apache.felix.gogo.runtime.Reflective.invoke(Reflective.java:137)
+	at org.apache.felix.gogo.runtime.Closure.executeMethod(Closure.java:527)
+	at org.apache.felix.gogo.runtime.Closure.executeStatement(Closure.java:403)
+	at org.apache.felix.gogo.runtime.Pipe.run(Pipe.java:108)
+	at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:183)
+	at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:120)
+	at org.apache.felix.gogo.runtime.CommandSessionImpl.execute(CommandSessionImpl.java:89)
+	at org.apache.karaf.shell.console.jline.Console.run(Console.java:166)
+	at java.lang.Thread.run(Thread.java:680)
+----
+
+It's possible to create objects to create commands "on the fly":
+
+----
+karaf@root()> addcommand system (($.context bundle) loadClass java.lang.System)
+karaf@root()> system:getproperty karaf.name
+root
+----
+
+It means that you can create object using the `new` directive, and call methods on the objects:
+
+----
+karaf@root> map = (new java.util.HashMap)
+karaf@root> $map put 0 0
+karaf@root> $map
+0                   0
+----
+
+==== Examples
+
+The following examples show some scripts defined in `etc/shell.init.script`.
+
+The first example show a script to add a value into a configuration list:
+
+----
+#
+# Add a value at the end of a property in the given OSGi configuration
+#
+# For example:
+# > config-add-to-list org.ops4j.pax.url.mvn org.ops4j.pax.url.mvn.repositories http://scala-tools.org/repo-releases
+#
+config-add-to-list = {
+  config:edit $1 ;
+  a = (config:property-list | grep --color never $2 | tac) ;
+  b = (echo $a | grep --color never "\b$3\b" | tac) ;
+  if { ($b trim) isEmpty } {
+    if { $a isEmpty } {
+      config:property-set $2 $3
+    } {
+      config:property-append $2 ", $3"
+    } ;
+    config:update
+  } {
+    config:cancel
+  }
+}
+----
+
+This second example shows a script to wait for an OSGi service, up to a given timeout, and combine this script in
+other scripts:
+
+----
+#
+# Wait for the given OSGi service to be available
+#
+wait-for-service-timeout = {
+  _filter = $.context createFilter $1 ;
+  _tracker = shell:new org.osgi.util.tracker.ServiceTracker $.context $_filter null ;
+  $_tracker open ;
+  _service = $_tracker waitForService $2 ;
+  $_tracker close
+}
+#
+# Wait for the given OSGi service to be available with a timeout of 10 seconds
+#
+wait-for-service = {
+  wait-for-service-timeout $1 10000
+}
+#
+# Wait for the given command to be available with a timeout of 10 seconds
+# For example:
+# > wait-for-command dev watch
+#
+wait-for-command = {
+  wait-for-service "(&(objectClass=org.apache.felix.service.command.Function)(osgi.command.scope=$1)(osgi.command.function=$2))"
+}
+----


Mime
View raw message