Standard directory layout for Native projects

The NAR Plugin assumes to find its native sources and resources in a directory structure parallel to the java sources. Test sources and test resources are organized the same way.

/yourproject
            /src
                /main
                     /java
                     /resources
                     /include
                     /c++
                     /c
                     /fortran
               /test
                    /java
                    /resources
                    /include
                    /c++
                    /c
                    /fortran                        

Organizing the information this way means that it is easy to find, for both people and the plugins that need to work with them.

A single Native project produces a single output

Maven produces one primary output (jar) per project. For the NAR Plugin the produced nar files are secondary outputs or attached artifact to the primary output. There are several reasons why the native artifacts are not primary outputs:

• When building a Native library, the object files and the include headers make a complete set. There is not much use of one without the other. Object files for one architecture combined in a nar file are no different than object files for another achitecture, their functionality is the same, its just for different machines. Neither the nar file with the include headers nor the nar files with the machine specific object files is a good primary output, so both attach to a jar file.
• When one builds a JNI library one needs both the java code in a jar file and native code in a shared library. The expected dependency is that the jar file needs the JNI library. However, javah generates the necessary header file from java, which would make the JNI library dependent on the jar file. Since this is impossible it would be better to attach the JNI library (in its nar file) as a secondary artifact to the primary jar file.
• When depending on a native library the user should just specify the artifactId, groupId and version, and not the architecture, os and linker it was build with. The latter is a derived value of the executable or library one is building at this time. Not specifying architecture, os and linker also means that the POM is generic. Since nar files are by default (except for the -noarch nar) architecture-os-linker specific they need to be secondary artifacts.

Standard naming conventions

When maven produces a jar file its normally named artifactId-version.jar. The NAR Plugin follows this convention for its attached artifacts:

artifactId-version-noarch.nar

contains the non architecture specific parts of the native library, such as include headers.

artifactId-version-aol-type.nar

contains the architecture specific parts of the native library, such as the library and object files. The aol is an Architecture-OS-Linker qualifier, for example: ppc-MacOSX-g++. The type specifies what binding the library is, for example: shared, static or jni.

Since the java compiler has a unified interface there is no need for any naming conventions here. Native compilers and linkers on different platforms tend to have radically different interfaces (command line options) so these were unified, allowing the user to switch on exception handling and debugging with the same tag in the configuration no matter which platform the NAR Plugin is running on. An example is below:

...
<plugin>
  <groupId>org.freehep</groupId>
  <artifactId>freehep-nar-plugin</artifactId>
  <configuration>
    <cpp>
      <exceptions>false</exceptions>
      <debug>true</debug>
    </cpp>
  </configuration>
</plugin>
...

NAR's project object model (POM)

The POM below is an example of how to compile, link and test a native shared library, which depends on a native math library (nmath).

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.app</groupId>
  <artifactId>my-app</artifactId>
  <packaging>nar</packaging>
  <version>1.0-SNAPSHOT</version>
  <build>
    <plugins>
      <plugin>
        <groupId>org.freehep</groupId>
        <artifactId>freehep-nar-plugin</artifactId>
        <version>nar-version-number</version>
        <extensions>true</extensions>
      </plugin>
    </plugins>
  </build>
  <dependencies>
    <dependency>
      <groupId>org.freehep</groupId>
      <artifactId>nmath</artifactId>
      <version>4.5.1</version>
    </dependency>
  </dependencies>
</project>

This POM will allow you to compile, link and test the java and native code in the project. The crucial part of the POM is the inclusion of the NAR plugin as an extension and the declaration of the "nar" packaging. The two will call the NAR Plugin goals as specified in the lifecycle.

For this POM the NAR Plugin will download and unpack the noarch and aol parts of the org.freehep nmath library version 4.5.1, for the platform you are running on.

Maven's Super POM is used for most of the default behaviour and the NAR Plugin's AOL Properties are used for native defaults.

NAR's build lifecycle

Maven's default build lifecycle, "jar", allows one to execute plugin goals as part of it, but this necessitates declaration of separate goals in each POM. To simplify the building of native artifacts we chose to define a "nar" lifecycle which calls all the goals the "jar" lifecycle has, interleaved with the goals of the NAR Plugin.