karaf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jbono...@apache.org
Subject [18/19] karaf git commit: KARAF-3679 - Switch documentation to asciidoc, close #65
Date Mon, 04 Jan 2016 09:57:45 GMT
http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/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..8a6eb83
--- /dev/null
+++ b/manual/src/main/asciidoc/developer-guide/custom-distribution.adoc
@@ -0,0 +1,650 @@
+//
+// 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.
+This 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`. 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.
+
+==== 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.
+You can use feature_name or feature_name/feature_version formats.
+* `<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.
+You can use feature_name or feature_name/feature_version formats.
+* `<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.
+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 assembly and archive goals -->
+            <plugin>
+                <groupId>org.apache.karaf.tooling</groupId>
+                <artifactId>karaf-maven-plugin</artifactId>
+                <extensions>true</extensions>
+                <configuration>
+                    <!-- no startupFeatures -->
+                    <bootFeatures>
+                        <feature>standard</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>minimal</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.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/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..1664438
--- /dev/null
+++ b/manual/src/main/asciidoc/developer-guide/debugging.adoc
@@ -0,0 +1,199 @@
+//
+// 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'
+----
+
+==== Debugging Environment Variables
+
+|===
+|Variable |Description |Default
+
+|KARAF_DEBUG
+|Set to TRUE to enable debugging.
+|
+
+|EXTRA_JAVA_OPTS
+|Java options append to JAVA_OPTS
+|
+
+|JAVA_DEBUG_OPTS
+|Java options to enable debuging.
+|Calculated based on the OS
+
+|JAVA_DEBUG_PORT
+|Port used by the debugger
+|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/3de05ae9/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..f41d8e4
--- /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/3de05ae9/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..18437b4
--- /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 `features.txt` file contains the list of all features, including current status
+* the `environment.txt` file contains details about Apache Karaf, OSGi framework, Operating System, JVM, system
+ properties, threads count, classes loaded
+* the `memory.txt` file contains the status of the JVM memory at the dump time
+* the `heapdump.txt` file contains a memory heap dump, with all objects instances, space usage, etc.
+* 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
+Created dump zip: 2015-07-01_171434.zip
+----
+
+We can see the file generated in the `KARAF_BASE` folder:
+
+----
+$ cd /opt/apache-karaf-4.0.0
+$ ls -lh *.zip
+-rw-rw-r-- 1 user group 17M Jul  1 17:14 2015-07-01_171434.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 50
+Enabling dynamic imports on bundle org.ops4j.pax.url.wrap [50]
+----
+
+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.
+
+{warning}
+Only Maven based URLs and Maven SNAPSHOTs will actually be updated automatically.
+{warning}
+
+The following command:
+
+----
+karaf@root()> bundle:watch *
+----
+
+will monitor all bundles that have a location matching mvn:* and '-SNAPSHOT' in their URL.

http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/developer-guide/ds.adoc
----------------------------------------------------------------------
diff --git a/manual/src/main/asciidoc/developer-guide/ds.adoc b/manual/src/main/asciidoc/developer-guide/ds.adoc
new file mode 100644
index 0000000..bb34893
--- /dev/null
+++ b/manual/src/main/asciidoc/developer-guide/ds.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.
+//
+
+== Declarative Service (DS)
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/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..62c56a4
--- /dev/null
+++ b/manual/src/main/asciidoc/developer-guide/extending.adoc
@@ -0,0 +1,359 @@
+//
+// 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 org.apache.karaf.shell.api.action.Action;
+import org.apache.karaf.shell.api.action.Command;
+import org.apache.karaf.shell.api.action.lifecycle.Service;
+
+@Command(scope = "test", name = "hello", description="Says hello")
+@Service
+public class HelloShellCommand implements Action {
+
+    @Override
+    public Object execute() throws Exception {
+        System.out.println("Executing Hello command");
+        return null;
+    }
+}
+----
+
+==== Manifest
+
+In order for Karaf to find your command, you need to add the `Karaf-Commands=*` manifest header.
+
+This is usually done by modifying the maven bundle plugin configuration
+
+----
+<plugin>
+    <groupId>org.apache.felix</groupId>
+    <artifactId>maven-bundle-plugin</artifactId>
+    <configuration>
+        <instructions>
+            <Karaf-Commands>*</Karaf-Commands>
+        </instructions>
+    </configuration>
+</plugin>
+----
+
+==== 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 org.apache.karaf.shell.api.action.Action;
+import org.apache.karaf.shell.api.action.Argument;
+import org.apache.karaf.shell.api.action.Command;
+import org.apache.karaf.shell.api.action.Completion;
+import org.apache.karaf.shell.api.action.lifecycle.Service;
+
+@Command(scope = "test", name = "hello", description="Says hello")
+@Service
+public class HelloShellCommand implements Action {
+
+    @Argument(index = 0, name = "name", description = "The name that sends the greet.", required = true, multiValued = false)
+    @Completion(SimpleNameCompleter.class)
+    String name = null;
+
+    @Override
+    public Object execute() throws Exception {
+        System.out.println("Hello " + name);
+        return null;
+    }
+}
+----
+
+==== Completer bean
+
+A completer is a bean which implements the Completer interface:
+
+----
+package org.apache.karaf.shell.samples;
+
+import org.apache.karaf.shell.api.action.lifecycle.Service;
+import org.apache.karaf.shell.api.console.CommandLine;
+import org.apache.karaf.shell.api.console.Completer;
+import org.apache.karaf.shell.api.console.Session;
+import org.apache.karaf.shell.support.completers.StringsCompleter;
+
+/**
+ * <p>
+ * A very simple completer.
+ * </p>
+ */
+@Service
+public class SimpleNameCompleter implements Completer {
+
+    public int complete(Session session, CommandLine commandLine, List<String> candidates) {
+        StringsCompleter delegate = new StringsCompleter();
+        delegate.getStrings().add("Mike");
+        delegate.getStrings().add("Eric");
+        delegate.getStrings().add("Jenny");
+        return delegate.complete(buffer, cursor, candidates);
+    }
+
+}
+----
+
+==== 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 org.apache.karaf.shell.api.action.Action;
+import org.apache.karaf.shell.api.action.Argument;
+import org.apache.karaf.shell.api.action.Command;
+import org.apache.karaf.shell.api.action.Completion;
+import org.apache.karaf.shell.api.action.Option;
+import org.apache.karaf.shell.api.action.lifecycle.Service;
+
+@Command(scope = "test", name = "hello", description="Says hello")
+@Service
+public class HelloShellCommand implements Action {
+
+    @Argument(index = 0, name = "name", description = "The name that sends the greet.", required = true, multiValued = false)
+    @Completion(SimpleNameCompleter.class)
+    String name = null;
+
+    @Option(name = "-g", aliases = "--greet", description = "The configuration pid", required = false, multiValued = false)
+    @Completion(GreetCompleter.class)
+    String greet = "Hello;
+
+    @Override
+    public Object execute() throws Exception {
+        System.out.println(greet + " " + name);
+        return null;
+    }
+}
+----
+
+==== 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.
+
+The Session object provides map like methods for storing key/value pairs and can be used to put/get the state.
+The pre-parsed CommandLine objects allows you to check the previous arguments and options on the command line and to fine tune
+the behavior of the Completer.
+Those two objects are given to the Completer when calling the `complete` method.
+
+==== 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.
+
+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/3de05ae9/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..de3c098
--- /dev/null
+++ b/manual/src/main/asciidoc/developer-guide/github-contributions.adoc
@@ -0,0 +1,81 @@
+//
+// 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/3de05ae9/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..e4ed117
--- /dev/null
+++ b/manual/src/main/asciidoc/developer-guide/karaf-maven-plugin.adoc
@@ -0,0 +1,486 @@
+//
+// 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
+
+=== Packaging
+
+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 and kar goals
+
+[NOTE]
+====
+You should use the features or kar packaging 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-descriptor`
+
+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-descriptor`
+
+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-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/4.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
+|===
+
+==== `karaf:create-kar`
+
+[NOTE]
+====
+Except in unusual circumstances, use the `<packaging>kar</packaging>` to run this goal.
+====
+
+The `karaf: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.
+
+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>
+----
+
+==== `karaf:install-kar`
+
+=== Instances and distributions goals
+
+[NOTE]
+====
+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:archive`
+
+[NOTE]
+====
+This goal is run as part of the karaf-assembly packaging.
+====
+
+The `karaf: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>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:assembly`
+
+=== Run, client, deploy goals
+
+==== `karaf:run`
+
+==== `karaf:client`
+
+==== `karaf:deploy`
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/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..64dae18
--- /dev/null
+++ b/manual/src/main/asciidoc/developer-guide/scripting.adoc
@@ -0,0 +1,406 @@
+//
+// 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/4.0.0
+----
+
+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.
+
+=== Expressions
+
+The shell has a built-in expression parser.  Expressions must be enclosed with the `%(...)` syntax.
+
+Examples:
+
+----
+karaf@root()> %(1+2)
+3
+karaf@root()> a = 0
+0
+karaf@root()> %(a+=1)
+1
+karaf@root()> %(a+=1)
+2
+karaf@root()> b=1
+1
+karaf@root()> %(SQRT(a^2 + b^2))
+1.7320508
+----
+
+==== Mathematical Operators
+
+|===
+|Operator |Description
+
+|+
+| Additive operator
+
+|-
+| Subtraction operator
+
+|*
+| Multiplication operator
+
+|/
+| Division operator
+
+|%
+| Remainder operator (Modulo)
+
+|^
+| Power operator
+|===
+
+==== Boolean Operators
+
+|===
+|Operator |Description
+
+|=
+| Equals
+
+|==
+| Equals
+
+|!=
+|Not equals
+
+|<>
+| Not equals
+
+|<
+| Less than
+
+|<=
+| Less than or equal to
+
+|>
+| Greater than
+
+|>=
+| Greater than or equal to
+
+|&&
+| Boolean and
+
+|\|\|
+|Boolean or
+|===
+
+==== Supported Functions
+
+|===
+|Function |Description
+
+|NOT(_expression_)
+|Boolean negation, 1 (means true) if the expression is not zero
+
+|IF(_condition_,_value_if_true_,_value_if_false_)
+|Returns one value if the condition evaluates to true or the other if it evaluates to false
+
+|RANDOM()
+|Produces a random number between 0 and 1
+
+|MIN(_e1_,_e2_)
+|Returns the smaller of both expressions
+
+|MAX(_e1_,_e2_)
+|Returns the bigger of both expressions
+
+|ABS(_expression_)
+|Returns the absolute (non-negative) value of the expression
+
+|ROUND(_expression_,precision)
+|Rounds a value to a certain number of digits, uses the current rounding mode
+
+|FLOOR(_expression_)
+|Rounds the value down to the nearest integer
+
+|CEILING(_expression_)
+|Rounds the value up to the nearest integer
+
+|LOG(_expression_)
+|Returns the natural logarithm (base e) of an expression
+
+|SQRT(_expression_)
+|Returns the square root of an expression
+
+|SIN(_expression_)
+|Returns the trigonometric sine of an angle (in degrees)
+
+|COS(_expression_)
+|Returns the trigonometric cosine of an angle (in degrees)
+
+|TAN(_expression_)
+|Returns the trigonometric tangens of an angle (in degrees)
+
+|SINH(_expression_)
+|Returns the hyperbolic sine of a value
+
+|COSH(_expression_)
+|Returns the hyperbolic cosine of a value
+
+|TANH(_expression_)
+|Returns the hyperbolic tangens of a value
+
+|RAD(_expression_)
+|Converts an angle measured in degrees to an approximately equivalent angle measured in radians
+
+|DEG(_expression_)
+|Converts an angle measured in radians to an approximately equivalent angle measured in degrees
+|===
+
+Functions names are case insensitive.
+
+==== Supported Constants
+
+|===
+|Constant |Description
+
+|PI
+|The value of _PI_, exact to 100 digits
+
+|TRUE
+|The value one
+
+|FALSE
+|The value zero
+|===
+
+=== 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`
+* ...
+
+See the link:commands[full list of `shell` commands] for details.
+
+=== 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