diff options
Diffstat (limited to 'src/site/apt/philosophy.apt')
| -rw-r--r-- | src/site/apt/philosophy.apt | 311 |
1 files changed, 311 insertions, 0 deletions
diff --git a/src/site/apt/philosophy.apt b/src/site/apt/philosophy.apt new file mode 100644 index 0000000..ce41e2b --- /dev/null +++ b/src/site/apt/philosophy.apt @@ -0,0 +1,311 @@ + --- +FreeHEP NAR Plugin + --- + --- +Mark Donszelmann + --- + +NAR Philosophy + + In the NAR plugin we follow Maven's main principles: + + * {{{#Convention over configuration}Convention over configuration}} + + * {{{#Reuse of build logic}Reuse of build logic}} + + * {{{#Declarative execution}Declarative execution}} + + * {{{#Coherent organization of dependencies}Coherent organization of dependencies}} + + [] + + below we explain how: + + +* {Convention over configuration} + + The NAR Plugin enables a cross-platform build technology for native +artifacts using Maven. Though the user has full flexibility in the choice +of compiler/linker and their options, sensible defaults are provided by the NAR +Plugin. The three primary conventions for the NAR Plugin are: + + * {{{#Standard directory layout for Native projects}Standard directory layout for Native projects}} + + * {{{#A single Native project produces a single output}A single Native project produces a single output}} + + * {{{#Standard naming conventions}Standard naming conventions}} + + [] + + and are detailed below: + + +** {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> +... ++-- + + +* {Reuse of build logic} + + The NAR Plugin provides multiple goals organized in the "nar" lifecycle. +The "nar" lifecycle integrates nicely with the default "jar" lifecycle to +build both jar and nar artifacts in parallel. Each of the NAR Plugin goals +can of course also be configured separately if needed. + + Most NAR goals are executed using the NarManager, which provides an API +that can also be used by other plugins when they need to deal with +NAR artifacts. + + +* {Declarative execution} + + All logic in Maven is setup in a declarative fashion using the Project +Object Model (POM). The NAR Plugin can be configured inside this model. +Moreover the "nar" lifecycle can be used to automatically integrate +all the NAR Plugin goals with the goals of the default "jar" lifecycle. + +** 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.html}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. + + +* {Coherent organization of dependencies} + + Maven uses a local repository to resolve its dependencies. If not found +one or more remote repositories are consulted to find a dependency. If found +the dependency is downloaded to the local repository and used from there by +any of the plugins. + + The NAR Plugin uses the same organization of dependencies and repositories. +Note that the dependency declared in the example above is a standard "jar" +dependency. It becomes a NAR depenency only because it contains the nar.properties +file and the NAR Plugin is configured for this project. When a user executes +install or deploy on a NAR project the jar file with its attached nar artifacts +will be installed in the local repository or deployed in the remote repository. + + A remote repository for the native math library would probably look +like this (note the support for multiple platforms and multiple library bindings): + ++-- +remoterepo/ + org/ + freehep/ + nmath/ + 4.5.1/ + nmath-4.5.1.pom + nmath-4.5.1.pom.sha1 + nmath-4.5.1.jar + nmath-4.5.1.jar.sha1 + nmath-4.5.1-noarch.nar + nmath-4.5.1-noarch.nar.sha1 + nmath-4.5.1-MacOSX-g++-static.nar + nmath-4.5.1-MacOSX-g++-static.nar.sha1 + nmath-4.5.1-MacOSX-g++-shared.nar + nmath-4.5.1-MacOSX-g++-shared.nar.sha1 + nmath-4.5.1-Linux-g++-shared.nar + nmath-4.5.1-Linux-g++-shared.nar.sha1 + nmath-4.5.1-Windows-msvc-shared.nar + nmath-4.5.1-Windows-msvc-shared.nar.sha1 + ... ++-- + + When a NAR dependency is encountered the jar file is already downloaded into +the local repository by maven itself. The nar-download goal will download any +attached NAR artifacts into the local repository and store them alongside the +jar file and the POM. Note that for these jar and nar files there is just one +POM, since it is just one artifact. If the nar files are already in the local +repository, due to someone calling nar-install on them, no extra download occurs. + + Now that the POM, jar and nar files are all in the local repository, the +nar-unpack goal unpacks the nar files. This is necessary because none of the +native compiler/linker tools understands nar files, so an unpacked directory +structure should be created. Unpacking only happens in the local repository. +A remote repository <<never>> contains an unpacked nar file. If unpacking was +already done, then no action is taken by the nar-unpack goal, unless the +artifact is a SNAPSHOT. + + The local repository for the native math library may look similar to this +if we were running on a MacOS X PowerPC system (Note the unpacked nar directory +and nar only for one platform): + ++-- +repository/ + org/ + freehep/ + nmath/ + 4.5.1/ + nmath-4.5.1.pom + nmath-4.5.1.pom.sha1 + nmath-4.5.1.jar + nmath-4.5.1.jar.sha1 + nmath-4.5.1-noarch.nar + nmath-4.5.1-noarch.nar.sha1 + nmath-4.5.1-MacOSX-g++-shared.nar + nmath-4.5.1-MacOSX-g++-shared.nar.sha1 + ... + nar/ + bin/ + ppc-MacOSX-g++/ + NMath + include/ + nmath/ + NMath.hh + data/ + NMath.data + lib/ + ppc-MacOSX-g++/ + shared/ + libNMath.so + libNMathExtra.so ++-- + + The usage of local repository by the NAR Plugin works seamlessly with the +usage of it by other Maven plugins. The SWIG Plugin for instance downloads +the native swig executable (wrapped in a NAR artifact), installs and unpacks +it in the local repository and then uses the executable in the bin directory +location. |