diff options
Diffstat (limited to 'src/xdocs/nar-dependencies.xml')
| -rw-r--r-- | src/xdocs/nar-dependencies.xml | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/src/xdocs/nar-dependencies.xml b/src/xdocs/nar-dependencies.xml new file mode 100644 index 0000000..dd9ae8e --- /dev/null +++ b/src/xdocs/nar-dependencies.xml @@ -0,0 +1,152 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<document> + <properties> + <title> NAR Dependencies</title> + <author email="Mark.Donszelmann@slac.stanford.edu">Mark Donszelmann</author> + </properties> + <body> + <section name="Dependencies on other NARs"> + <p> + Dependencies on other NARs are handled by the maven dependency mechanism. + + The type for NAR files is <code>nar</code>. A NAR dependency is specified + in the following way: + </p> + + <source> +<dependency> + <groupId>DependentGroup</groupId> + <artifactId>DependentArtifact<b>-nar</b></artifactId> + <version>DependentVersion</version> + <type><b>nar</b></type> +</dependency> + </source> + + <p> + The artifactId needs to specify a <code><b>-nar</b></code> suffix since artifactIds need to be unique + and a jar file may exist with the same name. + </p> + + <p> + When a nar dependency is found in the POM, Maven will download the property file : + </p> + <source> +<i>DependentGroup</i>/<b>nar</b>s/<i>DependentArtifact</i><b>-nar</b>-<i>DependentVersion</i>.<b>nar</b> + </source> + <p> + This file is normally generated by the NAR plugin for the DependentArtifact and + may specify the following properties: + </p> + + <table> + <tr> + <th>Property</th> + <th>Description</th> + <th>Default Value</th> + </tr> + + <tr> + <td>freehep.nar.nars</td> + <td>Space separated list of other nar files to download. + </td> + <td> + <code><i>DependentArtifact</i><b>-nar</b>-<i>DependentVersion</i>.<b>noarch.nar</b> + <i>DependentArtifact</i><b>-nar</b>-<i>DependentVersion</i>.<b>${aol}.nar</b></code> + </td> + </tr> + </table> + <p> + The default files specified for download will have the common and machine-os specific parts in them + respectively. + </p> + + <p> + The NAR plugin will look in the project.properties file followed by the + <i>DependentArtifact</i><b>-nar</b>-<i>DependentVersion</i>.<b>nar</b> file for any of the + following properties: + </p> + <table> + <tr> + <th>Property</th> + <th>Description</th> + <th>Default Value</th> + </tr> + + <tr> + <td>[<i>arch.</i>[<i>os.</i>[<i>linker.</i>]<i>DependentArtifact</i>-nar.local</td> + <td>Specifies that the DependentArtifact is installed locally (in a different place than the local + repository. The property <code>freehep.nar.nars</code> will be ignored. + One would typically use this for standard libs such as zlib and others.</td> + <td>false</td> + </tr> + + <tr> + <td>[<i>arch.</i>[<i>os.</i>[<i>linker.</i>]<i>DependentArtifact</i>-nar.dir</td> + <td>Specify a local directory where the DependentArtifact libs can be found.</td> + <td></td> + </tr> + + <tr> + <td>[<i>arch.</i>[<i>os.</i>[<i>linker.</i>]<i>DependentArtifact</i>-nar.include</td> + <td>Specify a local directory where the DependentArtifact includes can be found.</td> + <td></td> + </tr> + + <tr> + <td>[<i>arch.</i>[<i>os.</i>[<i>linker.</i>]<i>DependentArtifact</i>-nar.libs</td> + <td>Specify the libs to use for linking</td> + <td><code>${DependentArtifact}-nar-${DependentVersion}</code></td> + </tr> + + <tr> + <td>[<i>arch.</i>[<i>os.</i>[<i>linker.</i>]<i>DependentArtifact</i>-nar.local.libs</td> + <td>Specify the libs to use for linking if the libs are local</td> + <td><code>${DependentArtifact}-nar.libs</code></td> + </tr> + + <tr> + <td>[<i>arch.</i>[<i>os.</i>[<i>linker.</i>]<i>DependentArtifact</i>-nar.type</td> + <td>Specify the type of linking</td> + <td><code>${freehep.nar.libs.type}</code></td> + </tr> + + <tr> + <td>[<i>arch.</i>[<i>os.</i>[<i>linker.</i>]<i>DependentArtifact</i>-nar.linkLibs</td> + <td>Specify if libraries should be linked with (there are distributions with only include files).</td> + <td>true</td> + </tr> + + <tr> + <td><i>DependentArtifact</i>-nar.<i>AOL</i></td> + <td>Converts one AOL into another. For example: YourLib-nar.i386-Linux-g++=i386-Linux-gcc will + make sure you can link from g++ as well as from gcc to YourLib. YourLib needs to be dsitributed + as a gcc linked lib in this case.</td> + <td>${freehep.nar.aol.name}</td> + </tr> + + </table> + + <p> + If the property <i>DependentArtifact</i>-nar.local is set to true, then no further files will be + downloaded or installed and the properties <i>DependentArtifact</i>-nar.dir and + <i>DependentArtifact</i>-nar.include will be used for compilation and linking with this <i>DependentArtifact</i>. + In the other case the files specified by freehep.nar.nars will be downloaded, installed in + the local repository, unpacked and used for compilation and linking. + Setting <i>DependentArtifact</i>-nar.local allows the user to avoid downloading a library + which is already installed as a non-NAR file somewhere else on his machine. + The other properties are used in both the local and the NAR case. + </p> + <p> + When generating a set of NAR files, the <i>Artifact</i>-nar-<i>Version</i>.nar file will be generated + for you. This file may contain any of the properties listed above. The NAR plugin generates the + properties freehep.nar.nars and <i>Artifact</i>-nar.linkLibs. Any other properties can be specified + in the nar.properties file in the artifact's top directory (alongside project.properties) and will + be concatenated to the generated nar file. + </p> + </section> + + + + </body> +</document>
\ No newline at end of file |