Fixed doc on NAR-121

4 files changed, 33 insertions, 74 deletions

diff --git a/src/site/apt/compatibility.apt b/src/site/apt/compatibility.apt
index ce25282..19114a5 100644
--- a/src/site/apt/compatibility.apt
+++ b/src/site/apt/compatibility.apt
@@ -27,6 +27,11 @@ locally in a multi-module build.
 	* The main artifact is a jar file, where the NAR plugin attaches a -noarch nar file and some 
 platform specific nar files. When installed and or deployed the main jar file is renamed to a nar file,
 hence the dependecy type change from jar to nar. 
+
+	* The unpacking of nar files used to take place in a subdirectory of the local repositories 
+directory of that artifact. As of 2.1.x we unpack in a subdirectory of the target directory. This 
+used more diskspace (and a little time), however it avoids concurrent access to possibly half unpacked
+nar files when 2 or more maven invocations are running in parallel.
 	
 	[]
  
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
index 15ad924..1eb2b74 100644
--- a/src/site/apt/index.apt
+++ b/src/site/apt/index.apt
@@ -93,17 +93,16 @@ found on the path.
 * {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}
+declaration in the POM is used to describe such dependencies of type "nar", 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. 
+all dependent jar and nar 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-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.>>
+the "nar/dependencies" subdirectory of the target directory.
         
 * {nar-gnu-configure} 
 
@@ -241,7 +240,7 @@ 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}}.
+    nar-dependencies}}. This jar file is renamed to nar when installed or deployed.
     
     * \<Artifact\>-\<version\>-noarch.nar, a compressed jar file containing non machine
     specific parts of the distribution, such as the include directories.
diff --git a/src/site/apt/narDependencies.apt b/src/site/apt/narDependencies.apt
index e4150b5..2012d79 100644
--- a/src/site/apt/narDependencies.apt
+++ b/src/site/apt/narDependencies.apt
@@ -8,10 +8,10 @@ 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:
+The type for NAR files is <<<nar>>>.
+The main nar file is equivalent to a jar file, but with some nar specific information in it. 
+The other nar files are always published as attached artifacts
+to the main nar artifact. A nar dependency is declared in the following way:
 
 +--
 <project>
@@ -21,23 +21,23 @@ declared in the following way:
       <groupId>dependent-group</groupId>
       <artifactId>dependent-artifact</artifactId>
       <version>dependent-version</version>
+      <type>nar</type>
     </dependency>
   </dependencies>
 </project>
 +--
         
-	as is any other jar dependency. Maven will automatically download this jar file
-for any goal that requires it.
+	As of version 2.1.x the type needs to be declared as "nar". 
+Maven will automatically download this nar 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:
+	The NAR plugin knows this is a true nar dependency
+by looking inside the nar 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.
+	This file is normally generated in the nar-package goal.
 <<TBD there is no way to include a hand-written file>>.
 
 	The file may contain the following properties:
diff --git a/src/site/apt/philosophy.apt b/src/site/apt/philosophy.apt
index a2902bd..5d8fc17 100644
--- a/src/site/apt/philosophy.apt
+++ b/src/site/apt/philosophy.apt
@@ -71,7 +71,7 @@ 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 
+	Maven produces one primary output (jar, war, ...) 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:
@@ -91,10 +91,10 @@ primary outputs:
          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.
+         artifact to the primary nar file.
 
     * When depending on a native library the user should just specify
-         the artifactId, groupId and version, and <<not>> the architecture,
+         the artifactId, groupId, version and type, but <<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 
@@ -145,7 +145,7 @@ platform the NAR Plugin is running on. An example is below:
 
 	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
+build java and native files into 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 
@@ -186,6 +186,7 @@ shared library, which depends on a native math library (nmath).
       <groupId>org.freehep</groupId>
       <artifactId>nmath</artifactId>
       <version>4.5.1</version>
+      <type>nar</type>
     </dependency>
   </dependencies>
 </project>
@@ -220,10 +221,8 @@ 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
+When a user executes
+install or deploy on a NAR project the main nar 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
@@ -252,58 +251,14 @@ remoterepo/
                                    ...
 +--
 
-	When a NAR dependency is encountered the jar file is already downloaded into
+	When a NAR dependency is encountered the main nar 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
+attached NAR artifacts into the local repository and store them alongside the main
+nar file and the POM. Note that for these main nar and attached 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.
+	Now that the POM, main nar and attached nar files are all in the local repository, the 
+nar-unpack goal unpacks the nar files in an area in the target directory of the project. 
+This is necessary because none of the native compiler/linker tools understands nar files. 
+Compilation and linking can thus search the local target area.