diff options
Diffstat (limited to 'src/site')
| -rw-r--r-- | src/site/apt/HelloWorld.apt | 61 | ||||
| -rw-r--r-- | src/site/apt/aol.apt | 384 | ||||
| -rw-r--r-- | src/site/apt/configuration.apt | 453 | ||||
| -rw-r--r-- | src/site/apt/cpptasks.apt | 88 | ||||
| -rw-r--r-- | src/site/apt/faq.apt | 50 | ||||
| -rw-r--r-- | src/site/apt/intro.apt | 243 | ||||
| -rw-r--r-- | src/site/apt/lifecycle.apt | 48 | ||||
| -rw-r--r-- | src/site/apt/narDependencies.apt | 54 | ||||
| -rw-r--r-- | src/site/apt/narLibrary.apt | 109 | ||||
| -rw-r--r-- | src/site/apt/philosophy.apt | 311 | ||||
| -rw-r--r-- | src/site/apt/usage.apt | 228 | ||||
| -rw-r--r-- | src/site/resources/NARPlugin.ppt | bin | 0 -> 457728 bytes | |||
| -rw-r--r-- | src/site/site.xml | 59 |
13 files changed, 2088 insertions, 0 deletions
diff --git a/src/site/apt/HelloWorld.apt b/src/site/apt/HelloWorld.apt new file mode 100644 index 0000000..90f5123 --- /dev/null +++ b/src/site/apt/HelloWorld.apt @@ -0,0 +1,61 @@ + --- +FreeHEP NAR Plugin + --- + --- +Mark Donszelmann + --- + +HelloWorld Examples + + These example contain a simple C method "sayHello". This method can be called from a C program, a Java program, put into +a static library, put into a shared library, use a third party library, ... +There are also some unit test which are run and call the same method. + + The following examples are available: + + [helloworldexe] A C routine. + + [helloworldstaticexe] A C routine statically linked with the C-runtime library. + + [] + + [helloworldjni] A C routine called from Java and a Java unit test. + + [helloworldjnilibjava] A java project which depends on helloworldjni. + + [helloworldstaticjni] A C routine called from Java statically linked with the C-runtime library and a Java unit test. + + [hellothirdpartyjni] A third party JNI library called from Java. + The third party library is "helloworldjni" and is added as resource to the project in the + form of a JNI library and a corresponding jar file. A Java unit test is provided. + + [] + + [helloworldsharedlib] A C routine which gets archived into a shared library. A C test executable + is created and run. + + [helloworldsharedlibexe] A C executable which depends on "helloworldsharedlib" and links dynamically + with it. The executable is created and run. + + [helloworldsharedlibjni] A C routine called from Java, which depends on + "helloworldsharedlib" and links dynamically with it. A Java unit test is provided. + + [] + + [helloworldstaticlib] A C routine which gets archived into a static library. A C test executable + is created and run. + + [helloworldstaticlibexe] A C executable which depends on "helloworldstaticlib" and links statically + with it. The executabe is created and run. + + [helloworldstaticlibjni] A C routine called from Java, which depends on + "helloworldstaticlib" and links statically with it. A Java unit test is provided. + + [] + + These examples are now all run as tests when you try to run maven on the freehep-nar-plugin from its top-level directory. + + For the sources of these tests, see: +{{{http://java.freehep.org/svn/repobrowser.svn?path=%2ffreehep%2ftrunk%2fmaven-plugins%2ffreehep-nar-plugin%2ftests&revision=HEAD&name=freehep&bypassEmpty=true} +the SVN repository}}. + diff --git a/src/site/apt/aol.apt b/src/site/apt/aol.apt new file mode 100644 index 0000000..0acaa96 --- /dev/null +++ b/src/site/apt/aol.apt @@ -0,0 +1,384 @@ + --- +FreeHEP NAR Plugin + --- + --- +Mark Donszelmann + --- + +AOL Properties + + Below a copy of the AOL Properties file which is used by the NAR plugin for AOL dependent default settings: + ++-- +# +# Windows ("Windows *" => Windows) +# +x86.Windows.linker=msvc + +x86.Windows.msvc.cpp.compiler=msvc +x86.Windows.msvc.cpp.defines=Windows WIN32 +x86.Windows.msvc.cpp.options= +x86.Windows.msvc.cpp.includes=**/*.cc **/*.cpp **/*.cxx +x86.Windows.msvc.cpp.excludes= + +x86.Windows.msvc.c.compiler=msvc +x86.Windows.msvc.c.defines=Windows WIN32 +x86.Windows.msvc.c.options= +x86.Windows.msvc.c.includes=**/*.c +x86.Windows.msvc.c.excludes= + +x86.Windows.msvc.fortran.compiler=df +x86.Windows.msvc.fortran.defines=Windows WIN32 +x86.Windows.msvc.fortran.options= +x86.Windows.msvc.fortran.includes=**/*.f **/*.for +x86.Windows.msvc.fortran.excludes= + +x86.Windows.msvc.java.include=include;include/win32 +x86.Windows.msvc.java.runtimeDirectory=lib + +x86.Windows.msvc.lib.prefix= +x86.Windows.msvc.shared.extension=dll +x86.Windows.msvc.static.extension=lib +x86.Windows.msvc.plugin.extension=dll +x86.Windows.msvc.jni.extension=dll +x86.Windows.msvc.executable.extension=exe + +#x86.Windows.msvc.arch.includes=lib/**/*.lib lib/**/*.dll + +# +# Windows g++ +# +x86.Windows.g++.cpp.compiler=g++ +x86.Windows.g++.cpp.defines=Windows +x86.Windows.g++.cpp.options=-Wall +x86.Windows.g++.cpp.includes=**/*.cc **/*.cpp **/*.cxx +x86.Windows.g++.cpp.excludes= + +x86.Windows.g++.c.compiler=gcc +x86.Windows.g++.c.defines=Windows +x86.Windows.g++.c.options=-Wall +x86.Windows.g++.c.includes=**/*.c +x86.Windows.g++.c.excludes= + +x86.Windows.g++.fortran.compiler=g77 +x86.Windows.g++.fortran.defines=Windows +x86.Windows.g++.fortran.options=-Wall +x86.Windows.g++.fortran.includes=**/*.f **/*.for +x86.Windows.g++.fortran.excludes= + +x86.Windows.g++.java.include=include;include/Windows +x86.Windows.g++.java.runtimeDirectory=lib + +x86.Windows.g++.lib.prefix=lib +x86.Windows.g++.static.extension=a +x86.Windows.g++.shared.extension=so +x86.Windows.g++.plugin.extension=so +x86.Windows.g++.jni.extension=so +x86.Windows.g++.executable.extension= + +# +# Linux +# +i386.Linux.linker=g++ + +i386.Linux.g++.cpp.compiler=g++ +i386.Linux.g++.cpp.defines=Linux GNU_GCC f2cFortran +i386.Linux.g++.cpp.options=-Wall -Wno-long-long -Wpointer-arith -Wconversion +i386.Linux.g++.cpp.includes=**/*.cc **/*.cpp **/*.cxx +i386.Linux.g++.cpp.excludes= + +i386.Linux.g++.c.compiler=gcc +i386.Linux.g++.c.defines=Linux GNU_GCC f2cFortran +i386.Linux.g++.c.options=-Wall -Wno-long-long -Wpointer-arith -Wconversion +i386.Linux.g++.c.includes=**/*.c +i386.Linux.g++.c.excludes= + +i386.Linux.g++.fortran.compiler=g77 +i386.Linux.g++.fortran.defines=Linux GNU_GCC f2cFortran +i386.Linux.g++.fortran.options=-Wall +i386.Linux.g++.fortran.includes=**/*.f **/*.for +i386.Linux.g++.fortran.excludes= + +i386.Linux.g++.java.include=include;include/linux +i386.Linux.g++.java.runtimeDirectory=jre/lib/i386/client + +i386.Linux.g++.lib.prefix=lib +i386.Linux.g++.static.extension=a +i386.Linux.g++.shared.extension=so +i386.Linux.g++.plugin.extension=so +i386.Linux.g++.jni.extension=so +i386.Linux.g++.executable.extension= + +#i386.Linux.g++.arch.includes=lib/**/*.a lib/**/*.so + +# +# Linux icc (C linker) +# +i386.Linux.icc.cpp.compiler=NONE +i386.Linux.icc.cpp.defines=Linux +i386.Linux.icc.cpp.options=-ansi -mp -no-gcc -w1 +i386.Linux.icc.cpp.includes=**/*.cc **/*.cpp **/*.cxx +i386.Linux.icc.cpp.excludes= + +i386.Linux.icc.c.compiler=icc +i386.Linux.icc.c.defines=Linux +i386.Linux.icc.c.options=-ansi -mp -no-gcc -w1 +i386.Linux.icc.c.includes=**/*.c +i386.Linux.icc.c.excludes= + +i386.Linux.icc.fortran.compiler=ifort +i386.Linux.icc.fortran.defines=Linux +i386.Linux.icc.fortran.options= +i386.Linux.icc.fortran.includes=**/*.f **/*.for +i386.Linux.icc.fortran.excludes= + +i386.Linux.icc.java.include=include;include/linux +i386.Linux.icc.java.runtimeDirectory=jre/lib/i386/client + +i386.Linux.icc.lib.prefix=lib +i386.Linux.icc.static.extension=a +i386.Linux.icc.shared.extension=so +i386.Linux.icc.plugin.extension=so +i386.Linux.icc.jni.extension=so +i386.Linux.icc.executable.extension= + + +# +# Linux icpc (C++ linker) +# +i386.Linux.icpc.cpp.compiler=icpc +i386.Linux.icpc.cpp.defines=Linux +i386.Linux.icpc.cpp.options=-ansi -mp -no-gcc -w1 +i386.Linux.icpc.cpp.includes=**/*.cc **/*.cpp **/*.cxx +i386.Linux.icpc.cpp.excludes= + +i386.Linux.icpc.c.compiler=icc +i386.Linux.icpc.c.defines=Linux +i386.Linux.icpc.c.options=-ansi -mp -no-gcc -w1 +i386.Linux.icpc.c.includes=**/*.c +i386.Linux.icpc.c.excludes= + +i386.Linux.icpc.fortran.compiler=ifort +i386.Linux.icpc.fortran.defines=Linux +i386.Linux.icpc.fortran.options= +i386.Linux.icpc.fortran.includes=**/*.f **/*.for +i386.Linux.icpc.fortran.excludes= + +i386.Linux.icpc.java.include=include;include/linux +i386.Linux.icpc.java.runtimeDirectory=jre/lib/i386/client + +i386.Linux.icpc.lib.prefix=lib +i386.Linux.icpc.static.extension=a +i386.Linux.icpc.shared.extension=so +i386.Linux.icpc.plugin.extension=so +i386.Linux.icpc.jni.extension=so +i386.Linux.icpc.executable.extension= + +# +# Linux ecc (C linker) +# +i386.Linux.ecc.cpp.compiler=NONE +i386.Linux.ecc.cpp.defines=Linux +i386.Linux.ecc.cpp.options=-ansi -mp -no-gcc -w1 +i386.Linux.ecc.cpp.includes=**/*.cc **/*.cpp **/*.cxx +i386.Linux.ecc.cpp.excludes= + +i386.Linux.ecc.c.compiler=ecc +i386.Linux.ecc.c.defines=Linux +i386.Linux.ecc.c.options=-ansi -mp -no-gcc -w1 +i386.Linux.ecc.c.includes=**/*.c +i386.Linux.ecc.c.excludes= + +# Should this be efc ? +i386.Linux.ecc.fortran.compiler=ifort +i386.Linux.ecc.fortran.defines=Linux +i386.Linux.ecc.fortran.options= +i386.Linux.ecc.fortran.includes=**/*.f **/*.for +i386.Linux.ecc.fortran.excludes= + +i386.Linux.ecc.java.include=include;include/linux +i386.Linux.ecc.java.runtimeDirectory=jre/lib/i386/client + +i386.Linux.ecc.lib.prefix=lib +i386.Linux.ecc.static.extension=a +i386.Linux.ecc.shared.extension=so +i386.Linux.ecc.plugin.extension=so +i386.Linux.ecc.jni.extension=so +i386.Linux.ecc.executable.extension= + +# +# Linux ecpc (C++ linker) +# +i386.Linux.ecpc.cpp.compiler=ecpc +i386.Linux.icpc.cpp.defines=Linux +i386.Linux.ecpc.cpp.options=-ansi -mp -no-gcc -w1 +i386.Linux.ecpc.cpp.includes=**/*.cc **/*.cpp **/*.cxx +i386.Linux.ecpc.cpp.excludes= + +i386.Linux.ecpc.c.compiler=ecc +i386.Linux.ecpc.c.defines=Linux +i386.Linux.ecpc.c.options=-ansi -mp -no-gcc -w1 +i386.Linux.ecpc.c.includes=**/*.c +i386.Linux.ecpc.c.excludes= + +# Should this be efc ? +i386.Linux.ecpc.fortran.compiler=ifort +i386.Linux.ecpc.fortran.defines=Linux +i386.Linux.ecpc.fortran.options= +i386.Linux.ecpc.fortran.includes=**/*.f **/*.for +i386.Linux.ecpc.fortran.excludes= + +i386.Linux.ecpc.java.include=include;include/linux +i386.Linux.ecpc.java.runtimeDirectory=jre/lib/i386/client + +i386.Linux.ecpc.lib.prefix=lib +i386.Linux.ecpc.static.extension=a +i386.Linux.ecpc.shared.extension=so +i386.Linux.ecpc.plugin.extension=so +i386.Linux.ecpc.jni.extension=so +i386.Linux.ecpc.executable.extension= + +# +# Linux +# +amd64.Linux.linker=g++ + +amd64.Linux.g++.cpp.compiler=g++ +amd64.Linux.g++.cpp.defines=Linux GNU_GCC f2cFortran +amd64.Linux.g++.cpp.options=-Wall -Wno-long-long -Wpointer-arith -Wconversion +amd64.Linux.g++.cpp.includes=**/*.cc **/*.cpp **/*.cxx +amd64.Linux.g++.cpp.excludes= + +amd64.Linux.g++.c.compiler=gcc +amd64.Linux.g++.c.defines=Linux GNU_GCC f2cFortran +amd64.Linux.g++.c.options=-Wall -Wno-long-long -Wpointer-arith -Wconversion +amd64.Linux.g++.c.includes=**/*.c +amd64.Linux.g++.c.excludes= + +amd64.Linux.g++.fortran.compiler=g77 +amd64.Linux.g++.fortran.defines=Linux GNU_GCC f2cFortran +amd64.Linux.g++.fortran.options=-Wall +amd64.Linux.g++.fortran.includes=**/*.f **/*.for +amd64.Linux.g++.fortran.excludes= + +amd64.Linux.g++.java.include=include;include/linux +amd64.Linux.g++.java.runtimeDirectory=jre/lib/amd64/server + +amd64.Linux.g++.lib.prefix=lib +amd64.Linux.g++.static.extension=a +amd64.Linux.g++.shared.extension=so +amd64.Linux.g++.plugin.extension=so +amd64.Linux.g++.jni.extension=so +amd64.Linux.g++.executable.extension= + +#amd64.Linux.g++.arch.includes=lib/**/*.a lib/**/*.so + +# +# MacOSX ("Mac OS X" => MacOSX) +# +ppc.MacOSX.linker=g++ + +ppc.MacOSX.g++.cpp.compiler=g++ +ppc.MacOSX.g++.cpp.defines=Darwin GNU_GCC f2cFortran +ppc.MacOSX.g++.cpp.options=-Wall -Wno-long-long -Wpointer-arith -Wconversion +ppc.MacOSX.g++.cpp.includes=**/*.cc **/*.cpp **/*.cxx +ppc.MacOSX.g++.cpp.excludes= + +ppc.MacOSX.g++.c.compiler=gcc +ppc.MacOSX.g++.c.defines=Darwin GNU_GCC f2cFortran +ppc.MacOSX.g++.c.options=-Wall -Wno-long-long -Wpointer-arith -Wconversion +ppc.MacOSX.g++.c.includes=**/*.c +ppc.MacOSX.g++.c.excludes= + +ppc.MacOSX.g++.fortran.compiler=g77 +ppc.MacOSX.g++.fortran.defines=Darwin GNU_GCC +ppc.MacOSX.g++.fortran.options=-Wall -fno-automatic -fno-second-underscore +ppc.MacOSX.g++.fortran.includes=**/*.f **/*.for +ppc.MacOSX.g++.fortran.excludes= + +ppc.MacOSX.g++.java.include=include +ppc.MacOSX.g++.java.runtimeDirectory=IGNORED + +ppc.MacOSX.g++.lib.prefix=lib +ppc.MacOSX.g++.static.extension=a +ppc.MacOSX.g++.shared.extension=dylib +ppc.MacOSX.g++.plugin.extension=bundle +ppc.MacOSX.g++.jni.extension=jnilib +ppc.MacOSX.g++.executable.extension= + +#ppc.MacOSX.g++.arch.includes=lib/**/*.a lib/**/*.so lib/**/*.dylib lib/**/*.jnilib + +# +# MacOSX ("Mac OS X" => MacOSX) Intel +# +i386.MacOSX.linker=g++ + +i386.MacOSX.g++.cpp.compiler=g++ +i386.MacOSX.g++.cpp.defines=Darwin GNU_GCC +i386.MacOSX.g++.cpp.options=-Wall -Wno-long-long -Wpointer-arith -Wconversion +i386.MacOSX.g++.cpp.includes=**/*.cc **/*.cpp **/*.cxx +i386.MacOSX.g++.cpp.excludes= + +i386.MacOSX.g++.c.compiler=gcc +i386.MacOSX.g++.c.defines=Darwin GNU_GCC +i386.MacOSX.g++.c.options=-Wall -Wno-long-long -Wpointer-arith -Wconversion +i386.MacOSX.g++.c.includes=**/*.c +i386.MacOSX.g++.c.excludes= + +i386.MacOSX.g++.fortran.compiler=gfortran +i386.MacOSX.g++.fortran.defines=Darwin GNU_GCC +i386.MacOSX.g++.fortran.options=-Wall -fno-automatic -fno-second-underscore +i386.MacOSX.g++.fortran.includes=**/*.f **/*.for +i386.MacOSX.g++.fortran.excludes= + +i386.MacOSX.g++.java.include=include +i386.MacOSX.g++.java.runtimeDirectory=IGNORED + +i386.MacOSX.g++.lib.prefix=lib +i386.MacOSX.g++.static.extension=a +i386.MacOSX.g++.shared.extension=dylib +i386.MacOSX.g++.plugin.extension=bundle +i386.MacOSX.g++.jni.extension=jnilib +i386.MacOSX.g++.executable.extension= + +#i386.MacOSX.g++.arch.includes=lib/**/*.a lib/**/*.so lib/**/*.dylib lib/**/*.jnilib + +# +# Solaris +# +sparc.SunOS.linker=CC + +sparc.SunOS.CC.cpp.compiler=CC +sparc.SunOS.CC.cpp.defines=SOLARIS2 +sparc.SunOS.CC.cpp.options= +sparc.SunOS.CC.cpp.includes=**/*.cc **/*.cpp **/*.cxx +sparc.SunOS.CC.cpp.excludes= + +sparc.SunOS.CC.c.compiler=suncc +sparc.SunOS.CC.c.defines=SOLARIS2 +sparc.SunOS.CC.c.options= +sparc.SunOS.CC.c.includes=**/*.c +sparc.SunOS.CC.c.excludes= + +sparc.SunOS.CC.fortran.compiler=sunf77 +sparc.SunOS.CC.fortran.defines=SOLARIS2 +sparc.SunOS.CC.fortran.options= +sparc.SunOS.CC.fortran.includes=**/*.f **/*.for +sparc.SunOS.CC.fortran.excludes= + +sparc.SunOS.CC.java.include=include;include/solaris +sparc.SunOS.CC.java.runtimeDirectory=jre/lib/sparc/server + +sparc.SunOS.CC.linker.systemLibs=pthread:shared + +sparc.SunOS.CC.lib.prefix=lib +sparc.SunOS.CC.static.extension=a +sparc.SunOS.CC.shared.extension=so +sparc.SunOS.CC.plugin.extension=so +sparc.SunOS.CC.jni.extension=so +sparc.SunOS.CC.executable.extension= + +#sparc.SunOS.CC.arch.includes=lib/**/*.a lib/**/*.so ++-- + + diff --git a/src/site/apt/configuration.apt b/src/site/apt/configuration.apt new file mode 100644 index 0000000..6b01b91 --- /dev/null +++ b/src/site/apt/configuration.apt @@ -0,0 +1,453 @@ + --- +FreeHEP NAR Plugin + --- + --- +Mark Donszelmann + --- + +NAR Configuration + + The following shows the possible tags in the NAR configuration section: + ++-- +<configuration> + <arch/> + <os/> + <javaHome/> + <aol/> + <resourceDirectory/> + <resourceBinDir/> + <resourceIncludeDir/> + <resourceLibDir/> + <maxCores/> + <targetDirectory/> + <output/> + <failOnError/> + <runtime/> + <libtool/> + + <libraries> + <library> + <type/> + <linkCPP/> + <linkFortran/> + <run/> + <args> + <arg/> + </args> + </library> + </libraries> + + <tests> + <test> + <name/> + <link/> + <run/> + <args> + <arg/> + </args> + </test> + </tests> + + <linker> + <name/> + <incremental/> + <map/> + <options> + <option/> + </options> + <clearDefaultOptions/> + <libs> + <lib> + <name/> + <type/> + <directory/> + </lib> + </libs> + <sysLibs> + <sysLib> + <name/> + <type/> + </sysLib> + </sysLibs> + </linker> + + <cpp> + <name/> + <sourceDirectory/> + <includes> + <include> + </includes> + <excludes> + <exclude> + </excludes> + <debug/> + <exceptions/> + <rtti/> + <optimize/> + <multiThreaded/> + <defines> + <define/> + </defines> + <clearDefaultDefines/> + <undefines> + <undefine/> + </undefines> + <clearDefaultUndefines/> + <includePaths> + <includePath/> + </includePaths> + <systemIncludePaths> + <systemIncludePath/> + </systemIncludePaths> + <options> + <option/> + </options> + <clearDefaultOptions/> + </cpp> + + <c> + ... same as for <cpp> + </c> + + <fortran> + ... same as for <cpp> + </fortran> + + <java> + <include/> + <includePaths> + <includePath/> + </includePaths> + <link/> + <runtimeDirectory/> + <runtime/> + </java> + + <javah> + <name/> + <bootClassPaths> + <bootClassPath/> + </bootClassPaths> + <classPaths> + <classPath/> + </classPaths> + <jniDirectory/> + <classDirectory/> + <includes> + <include> + </includes> + <excludes> + <exclude> + </excludes> + </javah> + + <link/> +</configuration> ++-- + + +* {arch} + + The Architecture for which we produce the native library. Examples are +i386, x86, ppc, ppc64, etc... Default is the system property os.arch. + +* {os} + + The Operating System for which we produce the native library. Examples +are Windows, Linux, MacOSX, SunOS, ... Default is derived from os.name, without spaces and +in the case of Windows generalized. + +* {javaHome} + + The location of the Java installation. Default is derived from the system +property java.home, corrected for MacOSX. + +* {aol} + + The Architecture-OS-Linker qualifier. Default is composed from the arch, +os and linker.name value. + +* {resourceDirectory} + + Directory with NAR related resources. Used by the nar-resources goal, which +copies resources over to the target area. Defaults to ${basedir}/src/nar/resources. + +* {resourceBinDir} + + Directory with binaries, relative to ${resourceDirectory}. Defaults to bin. + +* {resourceIncludeDir} + + Directory with includes, relative to ${resourceDirectory}. Defaults to include. + +* {resourceLibDir} + + Directory with libraries, relative to ${resourceDirectory}. Defaults to lib. + +* {maxCores} + + Specifies the maximum number or Cores/CPUs to use for compilation. +If set to 0 it will use all the Cores/CPUs available. + +* {targetDirectory} + + Directory for all NAR related output. +Defaults to "${project.build.directory}/nar" for "compile" goal +Defaults to "${project.build.directory}/test-nar" for "compile-test" goal + +* {output} + + Name of the output. Default is ${project.artifactId}-${project.version}. + +* {failOnError} + + Fail on compilation/linking error. Default is true. + +* {runtime} + + Sets the type of runtime library, possible values "dynamic", "static". +Default is dynamic. + +* {libtool} + + Set use of libtool. If set to true, the "libtool " will be prepended to +the command line for compatible compilers/linkers. Default is false. + +* {libraries} + + Section to specify what type or libraries to create. For each library you may specify: + + [type] The type of the library: shared, static, jni, plugin, executable. Default is shared. + + [linkCPP] Specifies if the stdc++ library should be linked with. Default is true. + + [linkFortran] Specifies if the fortran library should be linked with. Default is false. + + [narSystemPackage] If specified a NarSystem class will be generated in this package and + added to the main jar artifact. The NarSystem class contains the following methods: + + * loadLibrary() - which will load the <artifact>-<version> JNI library. + + [narSystemName] Specifies the NarSystem class. Defaults to NarSystem. + + [narSystemDirectory] Specifies the NarSystem source directory. Defaults to target/nar/nar-generated. + + [] + + [run] If true will run this executable (only if type is executable). + + [args] List of arguments to be provided to executable. + + [] + +* {tests} + + Section to specify which test executables should be created. For each test you may specify: + + [name] Name of the executable. + + [link] Type of linking to be used: shared or static. Default is shared. + + [run] If true will run this test + + [args] List of arguments to be provided to test. + + [] + +* {linker} + + Section to specify parameters for the linker. + +** {linker name} + + The Linker. Some choices are: "msvc", "g++", "CC", "icpc", ... + Default is Architecture OS specific. + +** {linker incremental} + + Enables incremental linking. Default is false. + +** {linker map} + + Enables the production of a map file. Default is false. + +** {linker options} + + Additional options for the linker. + Defaults to AOL specific values. + +** {linker clearDefaultOptions} + + Clear options specified in AOL properties. + +** {linker libs} + + Adds libraries to the linker. For each lib you have to specify: + + [name] Name of the library, or a dependency groupId:artifactId if this library contains sublibraries + + [type] Type of linking for this library. Default is shared. + + [directory] Location for this library. + + [] + +** {linker sysLibs} + + Adds system libraries to the linker. For each syslib you have to specify: + + [name] Name of the system library + + [type] Type of linking for this system library. Default is shared. + + [] + + +* {cpp} + + Section to specify parameters for the c++ compiler. + +** {cpp name} + + The name of the compiler. Some choices are: "msvc", "g++", "gcc", "CC", "cc", "icc", "icpc", ... + Default is AOL specific. + +** {cpp sourceDirectory} + + Source directory for native files + +** {cpp includes} + + Include patterns for sources, relative to sourceDirectory in "ant" style. + +** {cpp excludes} + + Exclude patterns for sources, relative to sourceDirectory in "ant" style. + +** {cpp debug} + + Compile with debug information. Default is false. + +** {cpp exceptions} + + Enables generation of exception handling code. Default is true. + +** {cpp rtti} + + Enables run-time type information. Default is true. + +** {cpp optimize} + + Sets optimization. + Possible choices are: "none", "size", "minimal", "speed", "full", "aggressive", "extreme", "unsafe". + Default is none. + +** {cpp multiThreaded} + + Enables or disables generation of multithreaded code. + Default value: false, except on Windows. + +** {cpp defines} + + Additional list of defines. + +** {cpp clearDefaultDefines} + + Clear the defines specified in AOL properties. + +** {cpp undefines} + + Additional list of undefines. + +** {cpp clearDefaultUndefines} + + Clear undefines specified in AOL properties. + +** {cpp includePaths} + + Include Paths, relative to ${baseDir}. + Defaults to "${sourceDirectory}/include" + +** {cpp systemIncludePaths} + + System Include Paths, which are added at the end of all include paths + +** {cpp options} + + Additional options for the C++ compiler. Some of these options can be set by specific tags (debug, rtti, ...). + Defaults to AOL specific values. + +** {cpp clearDefaultOptions} + + Clear options specified in AOL properties. + +* {c} + + Same definitions as for \<cpp\> + + +* {fortran} + + Same definitions as for \<cpp\> + + +* {java} + + Section to specify parameters for java + +** {java include} + + Add Java includes to includepath. Default is false. + +** {java includePaths} + + List of Java Include Paths, relative to javaHome. + Defaults to: "javaHome/include" and "javaHome/include/os-specific". + +** {java link} + + Add Java Runtime to linker. Default is false. + +** {java runtimeDirectory} + + Relative path from javaHome to the java runtime to link with. + Defaults to AOL specific value. + +** {java runtime} + + Name of the runtime. Default is jvm. + +* {javah} + + Section to specify parameters for javah + +** {javah name} + + Javah command to run. + +** {javah bootClassPaths} + + List of boot class paths. By default none. + +** {javah classPaths} + + List of classpaths. By default the classDirectory directory is included and all dependent classes. + +** {javah jniDirectory} + + The target directory into which to generate the output. + +** {javah classDirectory} + + The class directory to scan for class files with native interfaces. + +** {javah includes} + + The set of files/patterns to include, relative to classDirectory/sourceDirectory. Defaults to "**/*.class" + +** {javah excludes} + + A list of exclusion filters, relative to classDirectory/sourceDirectory. Defaults to none. + + diff --git a/src/site/apt/cpptasks.apt b/src/site/apt/cpptasks.apt new file mode 100644 index 0000000..55704cb --- /dev/null +++ b/src/site/apt/cpptasks.apt @@ -0,0 +1,88 @@ + --- +FreeHEP NAR Plugin + --- + --- +Mark Donszelmann + --- + +CppTasks + + To handle the variety of architectures, compilers and linkers, the NAR Plugin uses +the {{{http://ant-contrib.sourceforge.net/cc.html}cpptasks}} library available +from {{{http://ant-contrib.sourceforge.net/}ant-contrib}}. +This library allows to specify compilers and linkers from ant (and thus from maven) +and unifies most common options for those compilers and linkers. + + The NAR Plugin uses cpptasks 1.0 beta 4 from +{{{http://sourceforge.net/project/showfiles.php?group_id=36177}sourceforge}} +with some minor extensions: + ++-- +** Misc. +- [src/net/sf/antcontrib/cpptasks/gcc/AbstractLdLinker.java] no more need for -prebind as of 10.4 +- [src/net/sf/antcontrib/cpptasks/gcc/AbstractLdLinker.java] removed trailing space after "-framework" to avoid quoting +- [src/net/sf/antcontrib/cpptasks/gcc/GppLinker.java] added -shared-libgcc/-static-libgcc for linking gcc and c++. +- [src/net/sf/antcontrib/cpptasks/gcc/GccLinker.java] added -dynamic as a valid option to GccLinker +- [src/net/sf/antcontrib/cpptasks/gcc/AbstractLdLinker.java] no -Bstatic for Darwin and no -Bdynamic for framework +- [src/net/sf/antcontrib/cpptasks/compaq/CompaqVisualFortranCompiler.java] removed addition of quotes. +- [src/net/sf/antcontrib/cpptasks/gcc/GccCompatibleCCompiler.java] added missing code for -fno-exceptions +- [src/net/sf/antcontrib/cpptasks/CCTask.java] added log statement to identify linker and compiler +- [src/net/sf/antcontrib/cpptasks/gcc/GppLinker.java] g++ linking now includes option -fexceptions +- [src/net/sf/antcontrib/cpptasks/CommandLineLinker] use absolute paths for filenames if they are shorter than relative paths to overcome windows file length limit. +- [src/net/sf/antcontrib/cpptasks/CCTask.java] added thread to keep progress + +** -fno-rtti changes +- [src/net/sf/antcontrib/cpptasks/gcc/GccCompatibleCCompiler.java] removed -fno-rtti flag +- [src/net/sf/antcontrib/cpptasks/gcc/GccCCompiler.java] only add -fno-rtti for g++ and c++ + +** Launch process change +- [src/net/sf/antcontrib/cpptasks/compiler/CaptureStreamHandler.java] rewrote the launching of subprocesses (NARPLUGIN-71). +- [src/net/sf/antcontrib/cpptasks/compiler/CaptureStreamHandler.java] added protection against null return of run() method. + +** libstdc++ linking +- [src/net/sf/antcontrib/cpptasks/CCTask.java] added method to link with CPP +- [src/net/sf/antcontrib/cpptasks/compiler/LinkType.java] added method to link with CPP +- [src/net/sf/antcontrib/cpptasks/compiler/gcc/GppLinker.java] link with or without CPP + +** jni libraries (MacOS X) +- [src/net/sf/antcontrib/cpptasks/OutputTypeEnum.java] added jni +- [src/net/sf/antcontrib/cpptasks/compiler/LinkType] add jni as type +- [src/net/sf/antcontrib/cpptasks/gcc/AbstractLdLinker] added jni +- [src/net/sf/antcontrib/cpptasks/gcc/GccLinker.java] add jni as type and special linker for MacOS X to output jnilib files. +- [src/net/sf/antcontrib/cpptasks/gcc/GppLinker.java] add jni as type and special linker for MacOS X to output jnilib files. + +** gfortran compiler +- [src/net/sf/antcontrib/cpptasks/gcc/GccCCompiler.java] added gfortran compiler +- [src/net/sf/antcontrib/cpptasks/CompilerEnum.java] added gfortran compiler + +** intel compilers name change +- [src/net/sf/antcontrib/cpptasks/intel/IntelLinux32CLinker.java] added (icpc) +- [src/net/sf/antcontrib/cpptasks/intel/IntelLinux32Compiler.java] added (icpc) +- [src/net/sf/antcontrib/cpptasks/intel/IntelLinux64CLinker.java] added (ecpc) +- [src/net/sf/antcontrib/cpptasks/intel/IntelLinux64Compiler.java] added (ecpc) +- [src/net/sf/antcontrib/cpptasks/LinkerEnum.java] added and changed linkers +- [src/net/sf/antcontrib/cpptasks/CompilerEnum.java] added and changed compilers. +- [src/net/sf/antcontrib/cpptasks/intel/IntelLinux32CCompiler.java] links to IntelLinux32CLinker. +- [src/net/sf/antcontrib/cpptasks/intel/IntelLinux64CCompiler.java] links to IntelLinux64CLinker. +- [src/net/sf/antcontrib/cpptasks/intel/IntelLinux32Linker.java] changed linker name from icc to icpc for version 8.1 of Intel Compilers. +- [src/net/sf/antcontrib/cpptasks/intel/IntelLinux64Linker.java] changed linker name from ecc to ecpc for version 8.1 of Intel Compilers. + +** sun c and fortran compiles +- [src/net/sf/antcontrib/cpptasks/sun/ForteCCompiler.java] added (suncc) +- [src/net/sf/antcontrib/cpptasks/sun/ForteF77Compiler.java] added (sunf77) +- [src/net/sf/antcontrib/cpptasks/CompilerEnum] Added the above (suncc, sunf77). + +** bug [ 1109917 ] g++ linker does not add runtime w/o other libs referenced +- [src/net/sf/antcontrib/cpptasks/compiler/CommandLineLinker] always call addLibrarySets + +** bug [ 795683 ] cpptasks speedup +- [src/net/sf/antcontrib/cpptasks/DependencyTable.java] cpptasks speedup +- [src/net/sf/antcontrib/cpptasks/DependencyInfo.java] cpptasks speedup ++-- + + You can find the latest of our mods in our svn repository: + ++-- +svn co svn://svn.freehep.org/svn/misc/trunk/cpptasks ++-- + diff --git a/src/site/apt/faq.apt b/src/site/apt/faq.apt new file mode 100644 index 0000000..ec1796f --- /dev/null +++ b/src/site/apt/faq.apt @@ -0,0 +1,50 @@ + --- +FreeHEP NAR Plugin + --- + --- +Mark Donszelmann + --- + +Frequently Asked Questions + + [Why does the nar-package goal run before the (general) jar goal] +The nar-package goal generates the nar.properties file which needs to +be included in the general jar artifact. + + [Why does the nar plugin produce both a jar artifact and an + attached -noarch.nar artifact. Could these two not be combined?] +The jar artifact contains only java classes and gets added to the classpath. +It needs no further processing. The -noarch.nar artifact contains include +files and needs to be unpacked to be useful for the native compilers. +It does not need to be added to the classpath. Combining the two artifacts +would complicate matters. + + [I use the nar-plugin to create a JNI type library. How do I load this library + from my code?] +The JNI library is strictly connected to the corresponding java code in the +main artifact (jar file). Since the main artifact has a version number, we decided +that the JNI library should have the same version number. If you add the subtag +<packageName> to the <library> tag, the nar-plugin will generate a NarSystem +class for you which will load the library. Assuming you specified com.mycompany.mypackage +as packageName, then you need to add the following code to the class with the native +methods: + ++-- +import com.mycompany.mypackage.NarSystem + +public class ... { + + ... + + static { + NarSystem.loadLibrary(); + } + + ... + +} ++-- + + + +
\ No newline at end of file diff --git a/src/site/apt/intro.apt b/src/site/apt/intro.apt new file mode 100644 index 0000000..4b641a1 --- /dev/null +++ b/src/site/apt/intro.apt @@ -0,0 +1,243 @@ + --- +FreeHEP NAR Plugin + --- + --- +Mark Donszelmann + --- + +Introduction + + NOTE: <<bold>> print is <<NOT implemented yet>>. + + This plugin for Maven 2 allows you to compile native code (c++, c and fortran) on +a number of different architectures (Linux, Windows, MacOSX, Solaris, ...) and with +a number of different compilers/linkers (g++, Microsoft Visual C++, CC, ...) +The output produced is wrapped up in Native ARchive files (.nar) some of which +are machine independent (-noarch), while others are machine specific and thus depend +on a combination of machine architecture(A), operating-system(O) and linker(L) identified +as AOL. +These nar files can be installed in the local maven repository and deployed to a +standard maven (web) server, using the standard maven-install-plugin and maven-deploy-plugin. + + Other maven projects may specify dependencies on these nar files using the standard +maven dependency declaration. Nar files get downloaded, unpacked and +installed in the local maven repository, just like jar files are (apart from the +unpacking). + + The NAR plugin executes the following goals, in the order below, to create and deploy nar files. +The goals are part of the +<<<nar>>> packaging/{{{lifecycle.html}lifecycle}}, which inserts the nar goals into the standard lifecyle. Using nar packaging +allows you to build a jar file as well as nar files. The list below shows the sequence of the NAR goals: + + [[1]] {{{#nar-download}nar-download}} + + [[2]] {{{#nar-system-generate}nar-system-generate}} + + [[3]] {{{#nar-unpack}nar-unpack}} + + [[4]] {{{#nar-resources}nar-resources}} + + [[5]] {{{#nar-javah}nar-javah}} + + [[6]] {{{#nar-compile}nar-compile}} + + [[7]] {{{#nar-testCompile}nar-testCompile}} + + [[8]] {{{#nar-test}nar-test}} + + [[9]] {{{#nar-package}nar-package}} + + [[10]] {{{#nar-integration-test}nar-integration-test}} + + [[11]] {{{#install}install (standard maven goal)}} + + [[12]] {{{#deploy}deploy (standard maven goal)}} + + [] + +* Initialization + + The NAR Plugin starts off by setting and deducing all kinds of property values for usage +in the goals below. The configuration section of the NAR plugin allows one to override +most of the default settings. The default settings come from the AOL properties file +which allows us to specify different defaults depending on the architecture-os-linker +combination, see {{{aol.html}AOL Properties}}. + + The NAR Plugin tries to deduce the "Operating System" +and the "Architecture" of the machine. Both can be overridden by setting <<<os>>> +and <<<arch>>> in the {{{configuration.html}configuration}}. + + The name of the linker is looked up in a architecture-os specific way, but can be overridden +by setting <<<linker.name>>> (this means the subtag \<name\> of the \<linker\> tag in the +configuration section). Now that the linker name is known +all other properties are looked up with a prefix of <<<[arch.[os.[linker.]]]>>> from the AOL Properties +file, but can be overridden in the configuration section (which can be made AOL specific by +putting it inside a profile. + + +* {nar-download} + + Your NAR artifact(s) may be dependent on other nar artifacts. The standard maven dependency +declaration in the POM is used to describe such dependencies, see {{{nar-dependencies.html} +nar-dependencies}}. By the time this goal is running maven will have already downloaded +all dependent jar files some of which may include a nar.properties file. +This property file contains information on what other machine dependent and machine independent nar files to download. +This goal will download any further necessary nar files into the local repository. + +* {nar-system-generate} + + This goal generates a NarSystem class if necessary. This class contains helper methods for your +code to handle things at run-time. The static method "loadLibrary()" is currently the only method +generated and will load your JNI library with name "artifactId-version". This goals only executed +if you produce a JNI library and you specify a <packageName> as subtag of <library>. The NarSystem +class will then end up in this package. + +* {nar-unpack} + + Since a nar file is of no use to any native compilation process the nar-unpack goal unpacks the nar into +the "nar" subdirectory of the local repository. A flag is set not to download and unpack this nar file again, +except if it is a SNAPSHOT artifact. <<TBD The actual nar file is deleted to preserve diskspace.>> + +* {nar-resources} + + This is an optional goal. It will take any resources in src/nar/resources and copy them into +specific areas under target/nar. Resources may include pre-compiled/linked libraries and other +shareable items. This goal can be used to create a nar library from a distribution that comes +with compiled shareable libraries. + +* {nar-javah} + + This goal will run the javah tool on any class file in the <<<javah.classDirectory>>> directory +that has native methods in it. The actual class files are inspected (rather than their sources). +The javah tool is picked up from the java installation and is run with a classpath of the +<<<javah.classDirectory>>> and all depencies' classpaths, unless you specify a list in <<<javah.classPaths>>>. +You can also set a boot classpath using <<<javah.bootClassPaths>>>. + + This goal has no effect if there are no java sources, or if none of the java classes contain a native +method. + +* {nar-compile} + + This goal will compile the native source code (c, c++ or fortran) and archive it into a shared library. +You can also produce a jni or a static library by setting <<<library.type>>>. +To handle the variety of compilers and linkers, the NAR plugin uses the cpptasks from the ant-contrib +project, with some minor improvements and additions of compilers, see {{{cpptasks.html}cpptasks}}. +Most of the settings for cpptasks, such as compiler, linker, options and include dirs are available +through the NAR plugin, see {{{configuration.html}configuration}}. + + The NAR plugin searches the directory structure under COMPILER.sourceDirectory, which defaults to +src/main. The standard way to separate your sources for different languages would be src/main/c, src/main/c++ +and src/main/fortran, but any file under src/main is searched for. + + The nar plugin will automatically select the correct compiler (c, c++ or fortran) based on the type of +source, as specified in the patterns in <<<AOL.c.includes>>>, +<<<AOL.cpp.includes>>> and <<<AOL.fortran.includes>>>, where AOL is a dotted qualifier of the architecture, +os and linker (x86.Windows.msvc for example). + + Include paths are added in this order from: + + * any directories set in <<<COMPILER.includePaths>>>, where COMPILER is c, cpp or fortran. + + * the <<<javah.jniDirectory>>>. + + * only if <<<java.include>>> is true or if <<<javah.jniDirectory>>> + exists we add one of the following, relative to the java home directory: + + * <<<java.includePaths>>> if set, + + * otherwise the <<<AOL.java.include>>> property from the AOL properties. + + [] + + + * the header files of any of the nar type dependencies, unless it is a jni library. + + * any system directories set in <<<COMPILER.sysincludepath>>>, where COMPILER is c, cpp or fortran. + + [] + + The static or dynamic library is linked against: + + * the list of libraries set in <<<linker.libs>>>. Using nar dependencies is preferred though. + + * the libraries of any of the nar type dependencies. + + * the java virtual machine if you set + <<<java.link>>> to true. The location of the runtime can be overridden in <<<java.runtimeDirectory>>>. + + [] + + All include files from <<<COMPILER.includePaths>>> are copied to be included +in the noarch nar file. + + << TBD If you set freehep.nar.includefilesonly to true the compilation step will be +skipped. This flag can be used if you want to distribute a library that only contains pure +abstract classes in include files.>> + + +* {nar-testCompile} + + This goal will compile the native test source code (c, c++ or fortran) and create executables from it. +To handle the variety of compilers and linkers, the NAR plugin uses the cpptasks from the ant-contrib +project, with some minor improvements and additions of compilers, see {{{cpptasks.html}cpptasks}}. +Most of the settings for cpptasks, such as compiler, linker, options and include dirs are available +through the NAR plugin, see {{{configuration.html}configuration}}. + + The NAR plugin searches the directory structure under COMPILER.sourceDirectory, which defaults to +src/test. The standard way to separate your sources for different languages would be src/test/c, src/test/c++ +and src/test/fortran, but any file under src/test is searched for. + + The compiler will automatically select the correct compiler (c, c++ or fortran) based on the type of +sources, as specified in the patterns in <<<AOL.c.includes>>>, +<<<AOL.nar.src.includes>>> and <<<AOL.fortran.includes>>>, where AOL is a dotted qualifier of the architecture, +os and linker (x86.Windows.msvc for example). + + <<TBD If you set freehep.nar.includefilesonly to true the compile-tests goal will be +skipped.>> + + +* {nar-test} + + Runs any native tests as well as any executables that have been produced. + +* {nar-package} + + This goal creates the artifact jar/nar file(s). The jar file is created by the standard package goal. +The following jar and nar files are created: + + * \<Artifact\>-\<version\>.jar, containing a property file describing the behaviour of the + library and other nar files available. For a description see {{{nar-dependencies.html} + nar-dependencies}}. + + * \<Artifact\>-\<version\>-noarch.nar, a compressed jar file containing non machine + specific parts of the distribution, such as the include directories. + + * \<Artifact\>-\<version\>-\<aol\>-\<type\>.nar, a compressed jar file containing machine + specific parts of the distribution, such as the libraries. This file is specific to a particular + Architecture-OS-Linker (AOL) combination <<TBD and is not generated if freehep.nar.includefilesonly + is set>>. Type specifies if this nar is either of type shared, static or jni. + + [] + +* {nar-integration-test} + + This goal runs tests against the packaged jar and nar files. Currently this is useful only to +test a jni library. The jni library is added to the java.library.path and the tests are forked to +pick up this path. + + To use this goal you need to put the test sources in the regular test directories but disable +the running of the tests by the maven-surefire-plugin. + + <<TBD integration tests for other types of libraries than jni>> + +* {install} + + This goal installs the produced artifacts in your local repository. The unpacking is done in the +unpack goal of a dependent artifact upon first usage. + + +* {deploy} + + This goal deploys the produced artifacts on a maven (web) server. The jar and nar files only consists +in their full form on the server and are never unpacked on the server. + diff --git a/src/site/apt/lifecycle.apt b/src/site/apt/lifecycle.apt new file mode 100644 index 0000000..3fd11cd --- /dev/null +++ b/src/site/apt/lifecycle.apt @@ -0,0 +1,48 @@ + --- +FreeHEP NAR Plugin + --- + --- +Mark Donszelmann + --- + +NAR Lifecycle + + The NAR lifecycle copies the default Maven lifecycle and adds native goals to its phases. +The table below shows the different phases of the NAR Lifecycle and the goals (including +standard maven goals) attached to them. The order is left to right, top to bottom. + +*------------------------+-------------------------------------------+ +| <Phase> | <Goals (NAR Goals in bold)> | +*------------------------+-------------------------------------------+ +| generate-sources | <<nar-download>>, <<nar-system-generate>> | +*------------------------+-------------------------------------------+ +| process-sources | <<nar-unpack>> | +*------------------------+-------------------------------------------+ +| process-resources | resources, <<nar-resources>> | +*------------------------+-------------------------------------------+ +| compile | compile, <<nar-javah>> | +*------------------------+-------------------------------------------+ +| process-classes | <<nar-compile>> | +*------------------------+-------------------------------------------+ +| process-test-resources | testResources | +*------------------------+-------------------------------------------+ +| test-compile | testCompile, <<nar-testCompile>> | +*------------------------+-------------------------------------------+ +| test | test, <<nar-test>> | +*------------------------+-------------------------------------------+ +| package | <<nar-package>>, jar | +*------------------------+-------------------------------------------+ +| integration-test | <<nar-integration-test>> | +*------------------------+-------------------------------------------+ +| install | install | +*------------------------+-------------------------------------------+ +| deploy | deploy | +*------------------------+-------------------------------------------+ + + + The NAR plugin attaches the nar files it produces to the main artifact (jar) so the standard +install and deploy plugins of maven do their job. + + The nar-assembly goal is not part of the lifestyle and should be called independently. + +
\ No newline at end of file diff --git a/src/site/apt/narDependencies.apt b/src/site/apt/narDependencies.apt new file mode 100644 index 0000000..526bc7c --- /dev/null +++ b/src/site/apt/narDependencies.apt @@ -0,0 +1,54 @@ + --- +FreeHEP NAR Plugin + --- + --- +Mark Donszelmann + --- + +NAR Dependencies + + Dependencies on other NARs are handled by the standard maven dependency mechanism. +The type for NAR files is <<<nar>>>, however to ease the inclusion of Java code and +lookup of properties any nar file is always published as an attached artifact +to a jar artifact. A nar dependency therefore becomes a jar dependency and is +declared in the following way: + ++-- +<project> + ... + <dependencies> + <dependency> + <groupId>dependent-group</groupId> + <artifactId>dependent-artifact</artifactId> + <version>dependent-version</version> + </dependency> + </dependencies> +</project> ++-- + + as is any other jar dependency. Maven will automatically download this jar file +for any goal that requires it. + + The NAR plugin knows this is a nar dependency +by looking inside the jar file for a properties file with the following name: + ++-- +META-INF/nar/groupId/artifactId/nar.properties ++-- + + This file is normally generated in the nar-package goal for pickup by +the standard package goal to be included in the jar file. +<<TBD there is no way to include a hand-written file>>. + + The file may contain the following properties: + +*---------------------------+--------------------+---------------------------------------+ +| <<Property>> | <<Default-Value>> | <<Description>> | +*---------------------------+--------------------+---------------------------------------+ +| nar.noarch | | Comma separated list of architecture independent nars to download. Each entry consists of groupId:artifactId:type:classifier, for example: ch.cern:cernlib:nar:noarch | +*---------------------------+--------------------+---------------------------------------+ +| nar.static | | Comma separated list of static nar files to download. Each entry consists of groupId:artifactId:type:classifier. $\{aol\} can be used to be replaced by the current aol value, for example: ch.cern:cernlib:nar:$\{aol\}-static | +*---------------------------+--------------------+---------------------------------------+ + + + <<TBD more values are possible >> diff --git a/src/site/apt/narLibrary.apt b/src/site/apt/narLibrary.apt new file mode 100644 index 0000000..98d4a11 --- /dev/null +++ b/src/site/apt/narLibrary.apt @@ -0,0 +1,109 @@ + --- +FreeHEP NAR Plugin + --- + --- +Mark Donszelmann + --- + +NAR Library + + Other plugins may need to use some of the functionality of the NAR Plugin, +such as downloading and unpacking. The NAR Plugin therefore groups most of +its functionality into the NAR Manager and allows other plugins and the NAR +Plugin itself to call on the NAR Manager. + + The {{{http://java.freehep.org/freehep-swig-plugin}SWIG Plugin}} which needs +the swig native executable uses the NAR Manager to download, unpack and call +the executable. + + To use the NAR Manager, see the {{{apidocs/index.html}API Docs}}, add the +following to your POM file: + ++-- +<project> + ... + <dependencies> + ... + <dependency> + <groupId>org.freehep</groupId> + <artifactId>freehep-nar-plugin</artifactId> + <version>2.0-alpha-2-SNAPSHOT</version> + </dependency> + </dependencies> +</project> ++-- + + and use the code with the following snippet: + ++-- +import org.apache.maven.artifact.repository.ArtifactRepository; +import org.apache.maven.plugin.AbstractMojo; +import org.apache.maven.plugin.MojoExecutionException; +import org.apache.maven.plugin.MojoFailureException; +import org.apache.maven.project.MavenProject; +import org.freehep.maven.nar.Linker; +import org.freehep.maven.nar.NarManager; +import org.freehep.maven.nar.NarUtil; + +/** + * Description... + * + * @goal your-goal + * @phase your-phase + * @requiresDependencyResolution compile + */ +public class YourMojo extends AbstractMojo { + + /** + * Level of logging messages, 0 is minimum. + * + * @parameter expression="${logLevel}" default-value="0" + */ + private int logLevel; + + /** + * @parameter expression="${localRepository}" + * @required + * @readonly + */ + private ArtifactRepository localRepository; + + /** + * @parameter expression="${project}" + * @required + * @readonly + */ + private MavenProject project; + + /** + * The Architecture for picking up swig, Some choices are: "x86", "i386", + * "amd64", "ppc", "sparc", ... Defaults to ${os.arch} + * + * @parameter expression="${os.arch}" + * @required + */ + private String architecture; + + /** + * The Operating System for picking up swig. Some choices are: "Windows", + * "Linux", "MacOSX", "SunOS", ... Defaults to a derived value from + * ${os.name} + * + * @parameter expression="" + */ + private String os; + + private NarManager narManager; + + public void execute() throws MojoExecutionException, MojoFailureException { + + os = NarUtil.getOS(os); + // FIXME, should have some function in NarUtil + Linker linker = new Linker("g++"); + narManager = new NarManager(getLog(), logLevel, localRepository, project, + architecture, os, linker); + + ... DO WHATEVER YOU NEED WITH THE NarManager + } +} ++-- 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. 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> ++-- + diff --git a/src/site/resources/NARPlugin.ppt b/src/site/resources/NARPlugin.ppt Binary files differnew file mode 100644 index 0000000..4ac2ae5 --- /dev/null +++ b/src/site/resources/NARPlugin.ppt diff --git a/src/site/site.xml b/src/site/site.xml new file mode 100644 index 0000000..c2b6814 --- /dev/null +++ b/src/site/site.xml @@ -0,0 +1,59 @@ +<project name="freehep"> + <bannerLeft> + <name>FreeHEP NAR Plugin</name> +<!-- <src>http://maven.apache.org/images/apache-maven-project.png</src> --> +<!-- FIXME, should this be substituted by some properties --> + <href>http://java.freehep.org/freehep-nar-plugin</href> + </bannerLeft> + + <bannerRight> + <name>FreeHEP</name> + <src>http://java.freehep.org/images/sm-freehep.gif</src> + <href>http://java.freehep.org</href> + </bannerRight> + + <body> + <links> + <item name="NAR Plugin for Maven1" href="http://java.freehep.org/maven1.x/freehep-nar-plugin"/> + <item name="FreeHEP 1.x" href="http://java.freehep.org/freehep1.x"/> + <item name="FreeHEP 2.x" href="http://java.freehep.org/"/> + <item name="Maven 2" href="http://maven.apache.org/maven2/"/> + </links> + + <menu name="Overview"> + <item name="Introduction" href="intro.html"/> + <item name="Philosophy" href="philosophy.html"/> + <item name="Presentation (pdf)" href="NARPlugin.pdf"/> + <item name="Presentation (ppt)" href="NARPlugin.ppt"/> + </menu> + + <menu name="User Info"> + <item name="Goals" href="plugin-info.html"/> + <item name="Usage" href="usage.html"/> + <item name="Lifecycle" href="lifecycle.html"/> + <item name="Configuration" href="configuration.html"/> + <item name="FAQ" href="faq.html"/> + <item name="AOL Properties" href="aol.html"/> + </menu> + + <menu name="Developer Info"> + <item name="NAR Dependencies" href="narDependencies.html"/> + <item name="Bug Reports" href="http://bugs.freehep.org/browse/NARPLUGIN"/> + <item name="Forum" href="http://forum.freehep.org/index.php?t=threadt&frm_id=14&rid=4"/> + <item name="APIDocs" href="apidocs/index.html"/> + <item name="NAR Library" href="narLibrary.html"/> + <item name="CPPTasks" href="cpptasks.html"/> + <item name="SVN Browse" href="http://java.freehep.org/svn/repobrowser.svn?path=%2ffreehep%2ftrunk%2fmaven-plugins%2ffreehep-nar-plugin/&revision=HEAD"/> + <item name="SVN Repository" href="source-repository.html"/> + </menu> + <menu name="Examples"> + <item name="HelloWorld" href="HelloWorld.html"/> + </menu> + <menu name="Other Information"> + <item name="Maven and other languages" href="http://docs.codehaus.org/display/MAVEN/Support+for+other+languages"/> + </menu> + + ${reports} + + </body> +</project> |