You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by de...@apache.org on 2008/01/01 15:02:54 UTC
svn commit: r607846 - in /maven/shared/trunk/maven-archiver/src/site:
apt/examples/classpath.apt apt/examples/manifest.apt
apt/examples/manifestEntries.apt apt/examples/manifestFile.apt
apt/examples/manifestSections.apt site.xml xdoc/index.xml
Author: dennisl
Date: Tue Jan 1 06:02:52 2008
New Revision: 607846
URL: http://svn.apache.org/viewvc?rev=607846&view=rev
Log:
[MNG-3329] Improve the documentation concerning the archiver configuration
o Copy documents from jar-plugin and elsewhere and rewrite them to be independent of jar-plugin.
O Integrate them with the rest of the site.
Added:
maven/shared/trunk/maven-archiver/src/site/apt/examples/classpath.apt (with props)
maven/shared/trunk/maven-archiver/src/site/apt/examples/manifest.apt (with props)
maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestEntries.apt (with props)
maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestFile.apt (with props)
Modified:
maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestSections.apt
maven/shared/trunk/maven-archiver/src/site/site.xml
maven/shared/trunk/maven-archiver/src/site/xdoc/index.xml
Added: maven/shared/trunk/maven-archiver/src/site/apt/examples/classpath.apt
URL: http://svn.apache.org/viewvc/maven/shared/trunk/maven-archiver/src/site/apt/examples/classpath.apt?rev=607846&view=auto
==============================================================================
--- maven/shared/trunk/maven-archiver/src/site/apt/examples/classpath.apt (added)
+++ maven/shared/trunk/maven-archiver/src/site/apt/examples/classpath.apt Tue Jan 1 06:02:52 2008
@@ -0,0 +1,192 @@
+ ------
+ Set Up The Classpath
+ ------
+ Dennis Lundberg
+ ------
+ 2008-01-01
+ ------
+
+ ~~ Licensed to the Apache Software Foundation (ASF) under one
+ ~~ or more contributor license agreements. See the NOTICE file
+ ~~ distributed with this work for additional information
+ ~~ regarding copyright ownership. The ASF licenses this file
+ ~~ to you under the Apache License, Version 2.0 (the
+ ~~ "License"); you may not use this file except in compliance
+ ~~ with the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing,
+ ~~ software distributed under the License is distributed on an
+ ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~~ KIND, either express or implied. See the License for the
+ ~~ specific language governing permissions and limitations
+ ~~ under the License.
+
+Set Up The Classpath
+
+
+* Add A Class-Path Entry To The Manifest
+
+ Maven Archiver can add the classpath of your project to the manifest. This is
+ done with the <<<\<addClasspath\>>>> configuration element.
+
++-----+
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ ...
+ <configuration>
+ <archive>
+ <manifest>
+ <addClasspath>true</addClasspath>
+ </manifest>
+ </archive>
+ </configuration>
+ ...
+ </plugin>
+ </plugins>
+ </build>
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>commons-lang</groupId>
+ <artifactId>commons-lang</artifactId>
+ <version>2.1</version>
+ </dependency>
+ <dependency>
+ <groupId>org.codehaus.plexus</groupId>
+ <artifactId>plexus-utils</artifactId>
+ <version>1.1</version>
+ </dependency>
+ </dependencies>
+ ...
+</project>
++-----+
+
+ The manifest produced using the above configuration would look like this:
+
++-----+
+Manifest-Version: 1.0
+Archiver-Version: Plexus Archiver
+Created-By: Apache Maven
+Built-By: ${user.name}
+Build-Jdk: ${java.version}
+Class-Path: plexus-utils-1.1.jar commons-lang-2.1.jar
++-----+
+
+
+* Make The Jar Executable
+
+ If you want to create an executable jar file, you need to configure Maven
+ Archiver accordingly. You need to tell it which main class to use. This is
+ done with the <<<\<mainClass\>>>> configuration element. Here is a sample
+ <<<pom.xml>>> configured to add the classpath and use the class
+ <<<fully.qualified.MainClass>>> as the main class:
+
++-----+
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ ...
+ <configuration>
+ <archive>
+ <manifest>
+ <addClasspath>true</addClasspath>
+ <mainClass>fully.qualified.MainClass</mainClass>
+ </manifest>
+ </archive>
+ </configuration>
+ ...
+ </plugin>
+ </plugins>
+ </build>
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>commons-lang</groupId>
+ <artifactId>commons-lang</artifactId>
+ <version>2.1</version>
+ </dependency>
+ <dependency>
+ <groupId>org.codehaus.plexus</groupId>
+ <artifactId>plexus-utils</artifactId>
+ <version>1.1</version>
+ </dependency>
+ </dependencies>
+ ...
+</project>
++-----+
+
+ The manifest produced using the above configuration would look like this:
+
++-----+
+Manifest-Version: 1.0
+Archiver-Version: Plexus Archiver
+Created-By: Apache Maven
+Built-By: ${user.name}
+Build-Jdk: ${java.version}
+Main-Class: fully.qualified.MainClass
+Class-Path: plexus-utils-1.1.jar commons-lang-2.1.jar
++-----+
+
+
+* Altering The Classpath
+
+ Sometimes it is useful to be able to alter the classpath, for example when
+ {{{http://maven.apache.org/plugins/maven-war-plugin/examples/skinny-wars.html}creating skinny war-files}}.
+ This can be achieved with the <<<\<classpathPrefix\>>>> configuration element.
+
++-----+
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <artifactId>maven-war-plugin</artifactId>
+ <configuration>
+ <archive>
+ <manifest>
+ <addClasspath>true</addClasspath>
+ <classpathPrefix>lib/</classpathPrefix>
+ </manifest>
+ </archive>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>commons-lang</groupId>
+ <artifactId>commons-lang</artifactId>
+ <version>2.1</version>
+ </dependency>
+ <dependency>
+ <groupId>org.codehaus.plexus</groupId>
+ <artifactId>plexus-utils</artifactId>
+ <version>1.1</version>
+ </dependency>
+ </dependencies>
+ ...
+</project>
++-----+
+
+ The manifest produced using the above configuration would look like this:
+
++-----+
+Manifest-Version: 1.0
+Archiver-Version: Plexus Archiver
+Created-By: Apache Maven
+Built-By: ${user.name}
+Build-Jdk: ${java.version}
+Class-Path: lib/plexus-utils-1.1.jar lib/commons-lang-2.1.jar
++-----+
Propchange: maven/shared/trunk/maven-archiver/src/site/apt/examples/classpath.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/shared/trunk/maven-archiver/src/site/apt/examples/classpath.apt
------------------------------------------------------------------------------
svn:keywords = Date Revision Author Id
Added: maven/shared/trunk/maven-archiver/src/site/apt/examples/manifest.apt
URL: http://svn.apache.org/viewvc/maven/shared/trunk/maven-archiver/src/site/apt/examples/manifest.apt?rev=607846&view=auto
==============================================================================
--- maven/shared/trunk/maven-archiver/src/site/apt/examples/manifest.apt (added)
+++ maven/shared/trunk/maven-archiver/src/site/apt/examples/manifest.apt Tue Jan 1 06:02:52 2008
@@ -0,0 +1,101 @@
+ ------
+ Manifest
+ ------
+ Dennis Lundberg
+ ------
+ 2008-01-01
+ ------
+
+ ~~ Licensed to the Apache Software Foundation (ASF) under one
+ ~~ or more contributor license agreements. See the NOTICE file
+ ~~ distributed with this work for additional information
+ ~~ regarding copyright ownership. The ASF licenses this file
+ ~~ to you under the Apache License, Version 2.0 (the
+ ~~ "License"); you may not use this file except in compliance
+ ~~ with the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing,
+ ~~ software distributed under the License is distributed on an
+ ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~~ KIND, either express or implied. See the License for the
+ ~~ specific language governing permissions and limitations
+ ~~ under the License.
+
+Manifest
+
+* Default Manifest
+
+ The default manifest created by Maven Archiver will contain the following
+ bits of information:
+
++-----+
+Manifest-Version: 1.0
+Archiver-Version: Plexus Archiver
+Created-By: Apache Maven
+Built-By: ${user.name}
+Build-Jdk: ${java.version}
++-----+
+
+* Adding Implementation And Specification Details
+
+ Starting with version 2.1, Maven Archiver no longer creates the
+ Implementation and Specification details in the manifest by default.
+ If you want them in your manifest you have to say so explicitly in your configuration.
+
+ <<Note:>> Because this is a recent change in Maven Archiver, different plugins
+ may or may not have started using it yet. Please check the documentation for
+ the plugin you want to use. In this example we use maven-jar-plugin 2.1 which
+ was the first version of that plugin to use this new feature.
+
++-----+
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ <version>2.1</version>
+ ...
+ <configuration>
+ <archive>
+ <manifest>
+ <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
+ <addDefaultSpecificationEntries>true</addDefaultSpecificationEntries>
+ </manifest>
+ </archive>
+ </configuration>
+ ...
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++-----+
+
+ The resulting manifest would contain these pieces of information:
+
++-----+
+Manifest-Version: 1.0
+Archiver-Version: Plexus Archiver
+Created-By: Apache Maven
+Built-By: ${user.name}
+Build-Jdk: ${java.version}
+Specification-Title: ${pom.name}
+Specification-Version: ${pom.version}
+Specification-Vendor: ${pom.organization.name}
+Implementation-Title: ${pom.name}
+Implementation-Version: ${pom.version}
+Implementation-Vendor-Id: ${pom.groupId}
+Implementation-Vendor: ${pom.organization.name}
++-----+
+
+ <<Note:>> If your pom.xml does not have an <<<\<organization\>>>>/<<<\<name\>>>>
+ element, then the <<<Specification-Vendor>>> and <<<Implementation-Vendor>>>
+ entries will <<not>> be in the manifest.
+
+ <<Note:>> If your pom.xml does not have a <<<\<name\>>>> element, then the
+ <<<Specification-Title>>> and <<<Implementation-Title>>> entries will have
+ "Unnamed - $\{pom.groupId\}:$\{pom.artifactId\}:$\{pom.version\}" as their value.
Propchange: maven/shared/trunk/maven-archiver/src/site/apt/examples/manifest.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/shared/trunk/maven-archiver/src/site/apt/examples/manifest.apt
------------------------------------------------------------------------------
svn:keywords = Date Revision Author Id
Added: maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestEntries.apt
URL: http://svn.apache.org/viewvc/maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestEntries.apt?rev=607846&view=auto
==============================================================================
--- maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestEntries.apt (added)
+++ maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestEntries.apt Tue Jan 1 06:02:52 2008
@@ -0,0 +1,81 @@
+ ------
+ Manifest Entries
+ ------
+ Dennis Lundberg
+ ------
+ 2008-01-01
+ ------
+
+ ~~ Licensed to the Apache Software Foundation (ASF) under one
+ ~~ or more contributor license agreements. See the NOTICE file
+ ~~ distributed with this work for additional information
+ ~~ regarding copyright ownership. The ASF licenses this file
+ ~~ to you under the Apache License, Version 2.0 (the
+ ~~ "License"); you may not use this file except in compliance
+ ~~ with the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing,
+ ~~ software distributed under the License is distributed on an
+ ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~~ KIND, either express or implied. See the License for the
+ ~~ specific language governing permissions and limitations
+ ~~ under the License.
+
+Manifest Entries
+
+ If you find that the other configuration options for Maven Archiver are not
+ enough for manipulating the manifest, you can add your own entries to it.
+ This is done with the <<<\<manifestEntries\>>>> configuration element.
+
+ In this example we'll add some entries to the manifest by specifying what we'd
+ like in the <<<\<configuration\>>>>/<<<\<archive\>>>> element of
+ maven-jar-plugin.
+
+ <<Note:>> As with all the examples here, this configuration can be used in all
+ plugins that use Maven Archiver, not just maven-jar-plugin as in this example.
+
++-----+
+<project>
+ <url>http://some.url.org/</url>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ ...
+ <configuration>
+ <archive>
+ <manifestEntries>
+ <mode>development</mode>
+ <url>${pom.url}</url>
+ </manifestEntries>
+ </archive>
+ </configuration>
+ ...
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++-----+
+
+ As you see above you can use literal values or you can have values from the
+ POM interpolated into literals or simply use straight POM expressions. So this
+ is what your resultant manifest will look like inside the generated jar:
+
++-----+
+Manifest-Version: 1.0
+Archiver-Version: Plexus Archiver
+Created-By: Apache Maven
+Built-By: ${user.name}
+Build-Jdk: ${java.version}
+mode: development
+url: http://some.url.org/
++-----+
+
+ <<Note:>> If your pom.xml does not have the <<<\<url\>>>> element, referenced
+ through interpolation, then the entry <<<url>>> will <<not>> be in the
+ manifest.
Propchange: maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestEntries.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestEntries.apt
------------------------------------------------------------------------------
svn:keywords = Date Revision Author Id
Added: maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestFile.apt
URL: http://svn.apache.org/viewvc/maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestFile.apt?rev=607846&view=auto
==============================================================================
--- maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestFile.apt (added)
+++ maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestFile.apt Tue Jan 1 06:02:52 2008
@@ -0,0 +1,61 @@
+ ------
+ Use Your Own Manifest File
+ ------
+ Dennis Lundberg
+ ------
+ 2008-01-01
+ ------
+
+ ~~ Licensed to the Apache Software Foundation (ASF) under one
+ ~~ or more contributor license agreements. See the NOTICE file
+ ~~ distributed with this work for additional information
+ ~~ regarding copyright ownership. The ASF licenses this file
+ ~~ to you under the Apache License, Version 2.0 (the
+ ~~ "License"); you may not use this file except in compliance
+ ~~ with the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing,
+ ~~ software distributed under the License is distributed on an
+ ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~~ KIND, either express or implied. See the License for the
+ ~~ specific language governing permissions and limitations
+ ~~ under the License.
+
+Use Your Own Manifest File
+
+ By default, Maven Archiver generates the manifest file for you. It is
+ sometimes useful to use your own hand crafted manifest file. Say that you
+ want to use the manifest file <<<src/main/resources/META-INF/MANIFEST.MF>>>.
+ This is done with the <<<\<manifestFile\>>>> configuration element by setting
+ the value to the location of your file.
+
+ The content of your own manifest file will be merged with the entries
+ generated by Maven Archiver. If you specify an entry in your own manifest file
+ it will override the value generated by Maven Archiver.
+
+ <<Note:>> As with all the examples here, this configuration can be used in all
+ plugins that use Maven Archiver, not just maven-jar-plugin as in this example.
+
++-----+
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ ...
+ <configuration>
+ <archive>
+ <manifestFile>src/main/resources/META-INF/MANIFEST.MF</manifestFile>
+ </archive>
+ </configuration>
+ ...
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++-----+
Propchange: maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestFile.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestFile.apt
------------------------------------------------------------------------------
svn:keywords = Date Revision Author Id
Modified: maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestSections.apt
URL: http://svn.apache.org/viewvc/maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestSections.apt?rev=607846&r1=607845&r2=607846&view=diff
==============================================================================
--- maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestSections.apt (original)
+++ maven/shared/trunk/maven-archiver/src/site/apt/examples/manifestSections.apt Tue Jan 1 06:02:52 2008
@@ -72,8 +72,6 @@
The following content will end up in the manifest:
-~~ TODO: Make this a full manifest!
-
+-----+
Manifest-Version: 1.0
Archiver-Version: Plexus Archiver
Modified: maven/shared/trunk/maven-archiver/src/site/site.xml
URL: http://svn.apache.org/viewvc/maven/shared/trunk/maven-archiver/src/site/site.xml?rev=607846&r1=607845&r2=607846&view=diff
==============================================================================
--- maven/shared/trunk/maven-archiver/src/site/site.xml (original)
+++ maven/shared/trunk/maven-archiver/src/site/site.xml Tue Jan 1 06:02:52 2008
@@ -39,7 +39,11 @@
<item name="Reference" href="index.html"/>
</menu>
<menu name="Examples">
+ <item name="Manifest" href="examples/manifest.html"/>
+ <item name="Manifest Entries" href="examples/manifestEntries.html"/>
<item name="Manifest Sections" href="examples/manifestSections.html"/>
+ <item name="Set Up The Classpath" href="examples/classpath.html"/>
+ <item name="Use Your Own Manifest File" href="examples/manifestFile.html"/>
</menu>
<!-- TODO: Link, head, reports should be inherited -->
<!-- TODO: use breadcrumbs more structure, links for links, and inherit subprojects as a menu or not at all -->
Modified: maven/shared/trunk/maven-archiver/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/maven/shared/trunk/maven-archiver/src/site/xdoc/index.xml?rev=607846&r1=607845&r2=607846&view=diff
==============================================================================
--- maven/shared/trunk/maven-archiver/src/site/xdoc/index.xml (original)
+++ maven/shared/trunk/maven-archiver/src/site/xdoc/index.xml Tue Jan 1 06:02:52 2008
@@ -204,6 +204,7 @@
<source>
Specification-Title: ${pom.name}
Specification-Version: ${pom.version}
+Specification-Vendor: ${pom.organization.name}
</source>
The default value is <code>false</code>.
</td>