From fb8d039ebe7801921fd315d6ce93b3c2384761f5 Mon Sep 17 00:00:00 2001 From: Mark Donszelmann Date: Mon, 12 Oct 2009 14:13:02 +0200 Subject: Fixed NAR-7 --- src/site/apt/index.apt | 243 +++++++++++++++++++++++++++++++++++++++++++++++++ src/site/apt/intro.apt | 243 ------------------------------------------------- src/site/site.xml | 2 +- 3 files changed, 244 insertions(+), 244 deletions(-) create mode 100644 src/site/apt/index.apt delete mode 100644 src/site/apt/intro.apt diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt new file mode 100644 index 0000000..1c62bd9 --- /dev/null +++ b/src/site/apt/index.apt @@ -0,0 +1,243 @@ + --- +Maven NAR Plugin + --- + --- +Mark Donszelmann + --- + +Introduction + + NOTE: <> print is <>. + + 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 +<<>> 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 <<>> +and <<>> 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 <<>> (this means the subtag \ of the \ 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 as subtag of . 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. <> + +* {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 <<>> 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 +<<>> and all depencies' classpaths, unless you specify a list in <<>>. +You can also set a boot classpath using <<>>. + + 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 <<>>. +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 <<>>, +<<>> and <<>>, 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 <<>>, where COMPILER is c, cpp or fortran. + + * the <<>>. + + * only if <<>> is true or if <<>> + exists we add one of the following, relative to the java home directory: + + * <<>> if set, + + * otherwise the <<>> 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 <<>>, where COMPILER is c, cpp or fortran. + + [] + + The static or dynamic library is linked against: + + * the list of libraries set in <<>>. Using nar dependencies is preferred though. + + * the libraries of any of the nar type dependencies. + + * the java virtual machine if you set + <<>> to true. The location of the runtime can be overridden in <<>>. + + [] + + All include files from <<>> are copied to be included +in the noarch nar file. + + << TBD If you set maven.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 <<>>, +<<>> and <<>>, where AOL is a dotted qualifier of the architecture, +os and linker (x86.Windows.msvc for example). + + <> + + +* {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: + + * \-\.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}}. + + * \-\-noarch.nar, a compressed jar file containing non machine + specific parts of the distribution, such as the include directories. + + * \-\-\-\.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 <>. 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. + + <> + +* {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/intro.apt b/src/site/apt/intro.apt deleted file mode 100644 index 1c62bd9..0000000 --- a/src/site/apt/intro.apt +++ /dev/null @@ -1,243 +0,0 @@ - --- -Maven NAR Plugin - --- - --- -Mark Donszelmann - --- - -Introduction - - NOTE: <> print is <>. - - 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 -<<>> 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 <<>> -and <<>> 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 <<>> (this means the subtag \ of the \ 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 as subtag of . 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. <> - -* {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 <<>> 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 -<<>> and all depencies' classpaths, unless you specify a list in <<>>. -You can also set a boot classpath using <<>>. - - 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 <<>>. -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 <<>>, -<<>> and <<>>, 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 <<>>, where COMPILER is c, cpp or fortran. - - * the <<>>. - - * only if <<>> is true or if <<>> - exists we add one of the following, relative to the java home directory: - - * <<>> if set, - - * otherwise the <<>> 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 <<>>, where COMPILER is c, cpp or fortran. - - [] - - The static or dynamic library is linked against: - - * the list of libraries set in <<>>. Using nar dependencies is preferred though. - - * the libraries of any of the nar type dependencies. - - * the java virtual machine if you set - <<>> to true. The location of the runtime can be overridden in <<>>. - - [] - - All include files from <<>> are copied to be included -in the noarch nar file. - - << TBD If you set maven.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 <<>>, -<<>> and <<>>, where AOL is a dotted qualifier of the architecture, -os and linker (x86.Windows.msvc for example). - - <> - - -* {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: - - * \-\.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}}. - - * \-\-noarch.nar, a compressed jar file containing non machine - specific parts of the distribution, such as the include directories. - - * \-\-\-\.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 <>. 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. - - <> - -* {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/site.xml b/src/site/site.xml index bb92917..39b2220 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -31,7 +31,7 @@ under the License. - + -- cgit v1.2.3