Moved files in from freehep-nar-plugin version 2.0-alpha-11-SNAPSHOT

1 files changed, 228 insertions, 0 deletions

diff --git a/src/site/apt/usage.apt b/src/site/apt/usage.apt
new file mode 100644
index 0000000..c64b9f3
--- /dev/null
+++ b/src/site/apt/usage.apt
@@ -0,0 +1,228 @@
+	---
+FreeHEP NAR Plugin
+	---
+	---
+Mark Donszelmann
+	---
+	
+Usage
+
+	The following fragments can be used to execute the NAR plugin to compile
+and link native code.
+
+* Create a Shared Library (but not a JNI library).
+
++--
+<project>
+  ...
+  <packaging>nar</packaging>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.freehep</groupId>
+        <artifactId>freehep-nar-plugin</artifactId>
+        <version>nar-version-number</version>
+        <extensions>true</extensions>
+      </plugin>
+    </plugins>
+  </build>
+</project>
++--
+
+* Create a JNI Library
+
++--
+<project>
+  ...
+  <packaging>nar</packaging>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.freehep</groupId>
+        <artifactId>freehep-nar-plugin</artifactId>
+        <extensions>true</extensions>
+        <configuration>
+          <libraries>
+            <library>
+              <type>jni</type>
+              <packageName>com.mycompany.mypackage</packageName>
+            </library>
+          </libraries>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>
++--
+
+* Create a JNI Library without linking to C++
+
+	It is possible to write your JNI code in C++, use the C++ compiler
+to compile it and then link it only with the C library (as long as
+you have not used any C++ library calls). Note the two tags
+to disable exceptions and not link with C++.
+
++--
+<project>
+  ...
+  <packaging>nar</packaging>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.freehep</groupId>
+        <artifactId>freehep-nar-plugin</artifactId>
+        <extensions>true</extensions>
+        <configuration>
+          <cpp>
+            <exceptions>false</exceptions>
+          </cpp>
+          <libraries>
+            <library>
+              <type>jni</type>
+              <linkCPP>false</linkCPP>
+            </library>
+          </libraries>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>
++--
+
+* Create a JNI Library using SWIG generated code
+
+	Since SWIG already generated the .h file normally
+generated by javah, we exclude this file from javah.
+We also include the compilation and linking with java.
+The example also shows how to configure the 
+{{{http://java.freehep.org/freehep-swig-plugin}freehep-swig-plugin}}.
+
++--
+<project>
+  ...
+  <packaging>nar</packaging>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.freehep</groupId>
+        <artifactId>freehep-swig-plugin</artifactId>
+        <extensions>true</extensions>
+        <executions>
+          <execution>
+            <id>swig</id>
+            <goals>
+              <goal>generate</goal>
+            </goals>
+            <configuration>
+              <cpp>true</cpp>
+              <packageName>org.domain.packagename</packageName>
+              <source>Module.swg</source>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+      ...
+      <plugin>
+        <groupId>org.freehep</groupId>
+        <artifactId>freehep-nar-plugin</artifactId>
+        <configuration>
+          <java>
+            <include>true</include>
+          </java>
+          <javah>
+            <excludes>
+              <exclude>**/ModuleJNI.class</exclude>
+            </excludes>
+          </javah>
+          <libraries>
+            <library>
+              <type>jni</type>
+            </library>
+          </libraries>
+        </configuration>
+      </plugin>    
+    </plugins>
+  </build>
+</project>
++--
+
+* Assemble libraries made on different platforms for distribution
+
+	This example shows how to download, unpack and assemble
+the already deployed machine dependent libraries.
+It also shows the setup of the standard maven-assembly-plugin
+to pick up the unpacked libraries.
+
+	Note there is no "nar" packaging as the normal packaging for 
+assemblies would be "pom".
+
++--
+<project>
+  ...
+  <packaging>pom</packaging>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <artifactId>maven-assembly-plugin</artifactId>
+        <!--  NOTE 2.1 fails -->
+        <version>2.0.1</version>
+        <configuration>
+          <descriptors>
+			...
+            <descriptor>src/main/assembly/x86-Windows-msvc.xml</descriptor>
+            <descriptor>src/main/assembly/ppc-MacOSX-g++.xml</descriptor>
+            <descriptor>src/main/assembly/i386-Linux-g++.xml</descriptor>
+          </descriptors>
+        </configuration>
+      </plugin>
+	  ...    
+      <plugin>
+        <groupId>org.freehep</groupId>
+        <artifactId>freehep-nar-plugin</artifactId>
+        <configuration>
+          <classifiers>
+            <classifier>x86-Windows-msvc</classifier>
+            <classifier>ppc-MacOSX-g++</classifier>
+            <classifier>i386-Linux-g++</classifier>
+          </classifiers>
+        </configuration>
+        <executions>
+          <execution>
+            <goals>
+              <goal>nar-download</goal>
+              <goal>nar-unpack</goal>
+              <goal>nar-assembly</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+</project>
++--
+
+	The i386-Linux-g++ assembly descriptor is below:
+
++--
+<assembly>
+  <id>i386-Linux-g++</id>
+  <formats>
+    <format>tar.gz</format>
+  </formats>
+  <fileSets>
+    <fileSet>
+      <directory>target/nar/lib/i386-Linux-g++/jni</directory>
+      <outputDirectory>lib/i386-Linux-g++</outputDirectory>      
+      <includes>
+        <include>*</include>
+      </includes>
+    </fileSet>
+  </fileSets>
+</assembly>
++--
+