---
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>
+--