This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-archiver.git
The following commit(s) were added to refs/heads/master by this push:
new 34adf54 Convert to MARKDOWN with doxia-converter
34adf54 is described below
commit 34adf545f339b5e512cd59ff55c78220e5c309da
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Dec 20 12:37:32 2025 +0100
Convert to MARKDOWN with doxia-converter
---
src/site/apt/examples/classpath.apt | 399 -------------------------
src/site/apt/examples/manifest.apt | 95 ------
src/site/apt/examples/manifestEntries.apt | 79 -----
src/site/apt/examples/manifestFile.apt | 61 ----
src/site/apt/examples/manifestSections.apt | 85 ------
src/site/markdown/examples/classpath.md | 348 +++++++++++++++++++++
src/site/markdown/examples/manifest.md | 85 ++++++
src/site/markdown/examples/manifestEntries.md | 70 +++++
src/site/markdown/examples/manifestFile.md | 53 ++++
src/site/markdown/examples/manifestSections.md | 81 +++++
10 files changed, 637 insertions(+), 719 deletions(-)
diff --git a/src/site/apt/examples/classpath.apt
b/src/site/apt/examples/classpath.apt
deleted file mode 100644
index 96a8d2e..0000000
--- a/src/site/apt/examples/classpath.apt
+++ /dev/null
@@ -1,399 +0,0 @@
- ------
- 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
-
-* {Contents}
-
- * {{{Add}Add A Class-Path Entry To The Manifest}}
-
- * {{{Make}Make The Jar Executable}}
-
- * {{{Prefix}Altering The Classpath: Defining a Classpath Directory Prefix}}
-
- * {{{Repository}Altering The Classpath: Using a Maven Repository-Style
Classpath}}
-
- * {{{Custom}Altering The Classpath: Using a Custom Classpath Format}}
-
- * {{{Snapshot}Handling Snapshot Versions}}
-
- []
-
-* {Add} A Class-Path Entry To The Manifest
-
- \[{{{Contents}Top}}\]
-
- 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
-Created-By: Apache Maven ${maven.version}
-Build-Jdk: ${java.version}
-Class-Path: plexus-utils-1.1.jar commons-lang-2.1.jar
-+-----+
-
-
-* {Make} The Jar Executable
-
- \[{{{Contents}Top}}\]
-
- 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
-Created-By: Apache Maven ${maven.version}
-Build-Jdk: ${java.version}
-Main-Class: fully.qualified.MainClass
-Class-Path: plexus-utils-1.1.jar commons-lang-2.1.jar
-+-----+
-
-
-* Altering The Classpath: Defining a Classpath Directory {Prefix}
-
- \[{{{Contents}Top}}\]
-
- Sometimes it is useful to be able to alter the classpath, for example when
- {{{/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 classpath produced using the above configuration would look like
this:
-
-+-----+
-Class-Path: lib/plexus-utils-1.1.jar lib/commons-lang-2.1.jar
-+-----+
-
-* Altering The Classpath: Using a Maven {Repository}-Style Classpath
-
- \[{{{Contents}Top}}\]
-
- <(Since: 2.3, see below)>
-
- Occasionally, you may want to include a Maven repository-style directory
structure in your
- archive. If you wish to reference the dependency archives within those
directories in your
- manifest classpath, try using the <<<\<classpathLayoutType\>>>> element with
a value of
- <<<'repository'>>>, like this:
-
-+-----+
-<project>
- ...
- <build>
- <plugins>
- <plugin>
- <artifactId>maven-jar-plugin</artifactId>
- <version>2.3</version>
- <configuration>
- <archive>
- <manifest>
- <addClasspath>true</addClasspath>
- <classpathPrefix>lib/</classpathPrefix>
- <classpathLayoutType>repository</classpathLayoutType>
- </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 classpath produced using the above configuration would look like
this:
-
-+-----+
-Class-Path: lib/org/codehaus/plexus/plexus-utils/1.1/plexus-utils-1.1.jar
lib/commons-lang/commons-lang/2.1/commons-lang-2.1.jar
-+-----+
-
-* Altering The Classpath: Using a {Custom} Classpath Format
-
- \[{{{Contents}Top}}\]
-
- <(Since: 2.4)>
-
- At times, you may have dependency archives in a custom format within your
own archive, one that doesn't
- conform to any of the above classpath layouts. If you wish to define a
custom layout for dependency archives
- within your archive's manifest classpath, try using the
<<<\<classpathLayoutType\>>>> element with a value of
- <<<'custom'>>>, along with the <<<\<customClasspathLayout\>>>> element, like
this:
-
-+-----+
-<project>
- ...
- <build>
- <plugins>
- <plugin>
- <artifactId>maven-war-plugin</artifactId>
- <configuration>
- <archive>
- <manifest>
- <addClasspath>true</addClasspath>
- <classpathLayoutType>custom</classpathLayoutType>
-
<customClasspathLayout>WEB-INF/lib/$${artifact.groupIdPath}/$${artifact.artifactId}-$${artifact.version}$${dashClassifier?}.$${artifact.extension}</customClasspathLayout>
- </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>
-+-----+
-
- This classpath layout is a little more involved than the previous examples.
- To understand how the value of the <<<\<customClasspathLayout\>>>>
configuration
- is interpreted, it's useful to understand the rules applied when resolving
- expressions within the value:
-
- [[1]] If present, trim off the prefix 'artifact.' from the expression.
-
- [[2]] Attempt to resolve the expression as a reference to the Artifact using
- reflection (eg. <<<'artifactId'>>> becomes a reference to the method
- <<<'getArtifactId()'>>>).
-
- [[3]] Attempt to resolve the expression as a reference to the
ArtifactHandler of
- the current Artifact, again using reflection (eg. <<<'extension'>>>
becomes a reference
- to the method <<<'getExtension()'>>>).
-
- [[4]] Attempt to resolve the expression as a key in the special-case
Properties instance,
- which contains the following mappings:
-
- * <<<'dashClassifier'>>>: If the Artifact has a classifier, this will
be
- <<<'-${artifact.classifier}'>>>, otherwise
this
- is an empty string.
-
- * <<<'dashClassifier?'>>>: This is a synonym of <<<'dashClassifier'>>>.
-
- * <<<'groupIdPath'>>>: This is the equivalent of
<<<'${artifact.groupId}'>>>,
- with all <<<'.'>>> characters replaced by
<<<'/'>>>.
-
- []
-
- []
-
- The manifest classpath produced using the above configuration would look like
this:
-
-+-----+
-Class-Path: WEB-INF/lib/org/codehaus/plexus/plexus-utils-1.1.jar
WEB-INF/lib/commons-lang/commons-lang-2.1.jar
-+-----+
-
-
-* Handling {Snapshot} Versions
-
- \[{{{Contents}Top}}\]
-
- <(Since 2.4)>
-
- Depending on how you construct your archive, you may have the ability to
specify whether
- snapshot dependency archives are included with the version suffix
<<<'-SNAPSHOT'>>>, or
- whether the unique timestamp and build-number for that archive is used. For
instance,
- the {{{/plugins/maven-assembly-plugin}Assembly Plugin}} allows
- you to make this decision in the <<<\<outputFileNameMapping\>>>> element of
its
- <<<\<dependencySet>>>> descriptor section.
-
-** Forcing the use of -SNAPSHOT versions when using the simple (default) or
repository classpath layout
-
- To force the use of <<<'-SNAPSHOT'>>> version naming, simply disable the
<<<\<useUniqueVersions\>>>>
- configuration element, like this:
-
-+-----+
-<useUniqueVersions>false</useUniqueVersions>
-+-----+
-
-** Forcing the use of -SNAPSHOT versions with custom layouts
-
- To force the use of <<<'-SNAPSHOT'>>> version naming, simply replace
<<<'${artifact.version}'>>>
- with <<<'${artifact.baseVersion}'>>> in the custom layout example above, so
it looks like this:
-
-+-----+
-<customClasspathLayout>WEB-INF/lib/${artifact.groupIdPath}/${artifact.artifactId}-${artifact.baseVersion}${dashClassifier?}.${artifact.extension}</customClasspathLayout>
-+-----+
-
- The full example configuration would look like this:
-
-+-----+
-<project>
- ...
- <build>
- <plugins>
- <plugin>
- <artifactId>maven-war-plugin</artifactId>
- <configuration>
- <archive>
- <manifest>
- <addClasspath>true</addClasspath>
- <classpathLayoutType>custom</classpathLayoutType>
-
<customClasspathLayout>WEB-INF/lib/${artifact.groupIdPath}/${artifact.artifactId}-${artifact.version}${dashClassifier?}.${artifact.extension}</customClasspathLayout>
- </manifest>
- </archive>
- </configuration>
- </plugin>
- </plugins>
- </build>
- ...
-</project>
-+-----+
diff --git a/src/site/apt/examples/manifest.apt
b/src/site/apt/examples/manifest.apt
deleted file mode 100644
index ef2f1cd..0000000
--- a/src/site/apt/examples/manifest.apt
+++ /dev/null
@@ -1,95 +0,0 @@
- ------
- 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
-Created-By: Apache Maven ${maven.version}
-Build-Jdk: ${java.version}
-+-----+
-
- <<Note:>> The <<<Build-Jdk>>> does not take toolchains configuration into
account. It is the same
- JDK version as running the Maven instance.
-
-* 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
-Created-By: Apache Maven ${maven.version}
-Build-Jdk: ${java.version}
-Specification-Title: ${project.name}
-Specification-Version:
${project.artifact.selectedVersion.majorVersion}.${project.artifact.selectedVersion.minorVersion}
-Specification-Vendor: ${project.organization.name}
-Implementation-Title: ${project.name}
-Implementation-Version: ${project.version}
-Implementation-Vendor: ${project.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.
diff --git a/src/site/apt/examples/manifestEntries.apt
b/src/site/apt/examples/manifestEntries.apt
deleted file mode 100644
index fe28c61..0000000
--- a/src/site/apt/examples/manifestEntries.apt
+++ /dev/null
@@ -1,79 +0,0 @@
- ------
- 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>${project.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 created jar:
-
-+-----+
-Manifest-Version: 1.0
-Created-By: Apache Maven ${maven.version}
-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.
diff --git a/src/site/apt/examples/manifestFile.apt
b/src/site/apt/examples/manifestFile.apt
deleted file mode 100644
index 1fcaa53..0000000
--- a/src/site/apt/examples/manifestFile.apt
+++ /dev/null
@@ -1,61 +0,0 @@
- ------
- 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 creates 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
- created by Maven Archiver. If you specify an entry in your own manifest file
- it will override the value created 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>
-+-----+
diff --git a/src/site/apt/examples/manifestSections.apt
b/src/site/apt/examples/manifestSections.apt
deleted file mode 100644
index 0f335d6..0000000
--- a/src/site/apt/examples/manifestSections.apt
+++ /dev/null
@@ -1,85 +0,0 @@
- ------
- Manifest Sections
- ------
- Olivier Lamy
- 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 Sections
-
- The <<<\<manifestSections\>>>> element provides a way to add custom manifest
- sections. It contains a list of
- <<<\<{{{../index.html#class_manifestSection}manifestSection}}\>>>> elements.
-
- <<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.
-
- Given this configuration:
-
-+-----+
-<project>
- ...
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-jar-plugin</artifactId>
- ...
- <configuration>
- <archive>
- <manifestSections>
- <manifestSection>
- <name>foo</name>
- <manifestEntries>
- <id>nice foo</id>
- </manifestEntries>
- </manifestSection>
- <manifestSection>
- <name>bar</name>
- <manifestEntries>
- <id>nice bar</id>
- </manifestEntries>
- </manifestSection>
- </manifestSections>
- </archive>
- </configuration>
- ...
- </plugin>
- </plugins>
- </build>
- ...
-</project>
-+-----+
-
- The following content will end up in the manifest:
-
-+-----+
-Manifest-Version: 1.0
-Created-By: Apache Maven ${maven.version}
-Build-Jdk: ${java.version}
-
-Name: foo
-id: nice foo
-
-Name: bar
-id: nice bar
-+-----+
diff --git a/src/site/markdown/examples/classpath.md
b/src/site/markdown/examples/classpath.md
new file mode 100644
index 0000000..3d1cf2c
--- /dev/null
+++ b/src/site/markdown/examples/classpath.md
@@ -0,0 +1,348 @@
+---
+title: Set Up The Classpath
+author:
+ - Dennis Lundberg
+date: 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
+
+## <a id="Contents">Contents</a>
+
+- [Add A Class-Path Entry To The Manifest](#Add)
+- [Make The Jar Executable](#Make)
+- [Altering The Classpath: Defining a Classpath Directory Prefix](#Prefix)
+- [Altering The Classpath: Using a Maven Repository-Style
Classpath](#Repository)
+- [Altering The Classpath: Using a Custom Classpath Format](#Custom)
+- [Handling Snapshot Versions](#Snapshot)
+
+## <a id="Add">Add A Class-Path Entry To The Manifest</a>
+
+[[Top](#Contents)]
+
+Maven Archiver can add the classpath of your project to the manifest. This is
done with the `<addClasspath>` configuration element.
+
+```xml
+<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
+Created-By: Apache Maven ${maven.version}
+Build-Jdk: ${java.version}
+Class-Path: plexus-utils-1.1.jar commons-lang-2.1.jar
+```
+
+## <a id="Make">Make The Jar Executable</a>
+
+[[Top](#Contents)]
+
+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:
+
+```xml
+<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
+Created-By: Apache Maven ${maven.version}
+Build-Jdk: ${java.version}
+Main-Class: fully.qualified.MainClass
+Class-Path: plexus-utils-1.1.jar commons-lang-2.1.jar
+```
+
+## <a id="Prefix">Altering The Classpath: Defining a Classpath Directory
Prefix</a>
+
+[[Top](#Contents)]
+
+Sometimes it is useful to be able to alter the classpath, for example when
[creating skinny
war-files](/plugins/maven-war-plugin/examples/skinny-wars.html). This can be
achieved with the `<classpathPrefix>` configuration element.
+
+```xml
+<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 classpath produced using the above configuration would look like
this:
+
+```
+Class-Path: lib/plexus-utils-1.1.jar lib/commons-lang-2.1.jar
+```
+
+## <a id="Repository">Altering The Classpath: Using a Maven Repository-Style
Classpath</a>
+
+[[Top](#Contents)]
+
+_(Since: 2.3, see below)_
+
+Occasionally, you may want to include a Maven repository-style directory
structure in your archive. If you wish to reference the dependency archives
within those directories in your manifest classpath, try using the
`<classpathLayoutType>` element with a value of `'repository'`, like this:
+
+```xml
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <artifactId>maven-jar-plugin</artifactId>
+ <version>2.3</version>
+ <configuration>
+ <archive>
+ <manifest>
+ <addClasspath>true</addClasspath>
+ <classpathPrefix>lib/</classpathPrefix>
+ <classpathLayoutType>repository</classpathLayoutType>
+ </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 classpath produced using the above configuration would look like
this:
+
+```
+Class-Path: lib/org/codehaus/plexus/plexus-utils/1.1/plexus-utils-1.1.jar
lib/commons-lang/commons-lang/2.1/commons-lang-2.1.jar
+```
+
+## <a id="Custom">Altering The Classpath: Using a Custom Classpath Format</a>
+
+[[Top](#Contents)]
+
+_(Since: 2.4)_
+
+At times, you may have dependency archives in a custom format within your own
archive, one that doesn't conform to any of the above classpath layouts. If you
wish to define a custom layout for dependency archives within your archive's
manifest classpath, try using the `<classpathLayoutType>` element with a value
of `'custom'`, along with the `<customClasspathLayout>` element, like this:
+
+```xml
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <artifactId>maven-war-plugin</artifactId>
+ <configuration>
+ <archive>
+ <manifest>
+ <addClasspath>true</addClasspath>
+ <classpathLayoutType>custom</classpathLayoutType>
+
<customClasspathLayout>WEB-INF/lib/$${artifact.groupIdPath}/$${artifact.artifactId}-$${artifact.version}$${dashClassifier?}.$${artifact.extension}</customClasspathLayout>
+ </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>
+```
+
+This classpath layout is a little more involved than the previous examples. To
understand how the value of the `<customClasspathLayout>` configuration is
interpreted, it's useful to understand the rules applied when resolving
expressions within the value:
+
+1. If present, trim off the prefix 'artifact.' from the expression.
+1. Attempt to resolve the expression as a reference to the Artifact using
reflection (eg. `'artifactId'` becomes a reference to the method
`'getArtifactId()'`).
+1. Attempt to resolve the expression as a reference to the ArtifactHandler of
the current Artifact, again using reflection (eg. `'extension'` becomes a
reference to the method `'getExtension()'`).
+1. Attempt to resolve the expression as a key in the special-case Properties
instance, which contains the following mappings:
+ - `'dashClassifier'`: If the Artifact has a classifier, this will be
`'-$artifact.classifier'`, otherwise this is an empty string.
+ - `'dashClassifier?'`: This is a synonym of `'dashClassifier'`.
+ - `'groupIdPath'`: This is the equivalent of `'$artifact.groupId'`, with
all `'.'` characters replaced by `'/'`.
+
+The manifest classpath produced using the above configuration would look like
this:
+
+```
+Class-Path: WEB-INF/lib/org/codehaus/plexus/plexus-utils-1.1.jar
WEB-INF/lib/commons-lang/commons-lang-2.1.jar
+```
+
+## <a id="Snapshot">Handling Snapshot Versions</a>
+
+[[Top](#Contents)]
+
+_(Since 2.4)_
+
+Depending on how you construct your archive, you may have the ability to
specify whether snapshot dependency archives are included with the version
suffix `'-SNAPSHOT'`, or whether the unique timestamp and build-number for that
archive is used. For instance, the [Assembly
Plugin](/plugins/maven-assembly-plugin) allows you to make this decision in the
`<outputFileNameMapping>` element of its `<dependencySet>` descriptor section.
+
+### Forcing the use of -SNAPSHOT versions when using the simple (default) or
repository classpath layout
+
+To force the use of `'-SNAPSHOT'` version naming, simply disable the
`<useUniqueVersions>` configuration element, like this:
+
+```xml
+<useUniqueVersions>false</useUniqueVersions>
+```
+
+### Forcing the use of -SNAPSHOT versions with custom layouts
+
+To force the use of `'-SNAPSHOT'` version naming, simply replace
`'$artifact.version'` with `'$artifact.baseVersion'` in the custom layout
example above, so it looks like this:
+
+```xml
+<customClasspathLayout>WEB-INF/lib/${artifact.groupIdPath}/${artifact.artifactId}-${artifact.baseVersion}${dashClassifier?}.${artifact.extension}</customClasspathLayout>
+```
+
+The full example configuration would look like this:
+
+```xml
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <artifactId>maven-war-plugin</artifactId>
+ <configuration>
+ <archive>
+ <manifest>
+ <addClasspath>true</addClasspath>
+ <classpathLayoutType>custom</classpathLayoutType>
+
<customClasspathLayout>WEB-INF/lib/${artifact.groupIdPath}/${artifact.artifactId}-${artifact.version}${dashClassifier?}.${artifact.extension}</customClasspathLayout>
+ </manifest>
+ </archive>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
+```
diff --git a/src/site/markdown/examples/manifest.md
b/src/site/markdown/examples/manifest.md
new file mode 100644
index 0000000..2939689
--- /dev/null
+++ b/src/site/markdown/examples/manifest.md
@@ -0,0 +1,85 @@
+---
+title: Manifest
+author:
+ - Dennis Lundberg
+date: 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
+Created-By: Apache Maven ${maven.version}
+Build-Jdk: ${java.version}
+```
+
+**Note:** The `Build-Jdk` does not take toolchains configuration into account.
It is the same JDK version as running the Maven instance.
+
+## 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.
+
+```xml
+<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:
+
+```properties
+Manifest-Version: 1.0
+Created-By: Apache Maven ${maven.version}
+Build-Jdk: ${java.version}
+Specification-Title: ${project.name}
+Specification-Version:
${project.artifact.selectedVersion.majorVersion}.${project.artifact.selectedVersion.minorVersion}
+Specification-Vendor: ${project.organization.name}
+Implementation-Title: ${project.name}
+Implementation-Version: ${project.version}
+Implementation-Vendor: ${project.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.
diff --git a/src/site/markdown/examples/manifestEntries.md
b/src/site/markdown/examples/manifestEntries.md
new file mode 100644
index 0000000..15767e2
--- /dev/null
+++ b/src/site/markdown/examples/manifestEntries.md
@@ -0,0 +1,70 @@
+---
+title: Manifest Entries
+author:
+ - Dennis Lundberg
+date: 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.
+
+```xml
+<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>${project.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 created jar:
+
+```properties
+Manifest-Version: 1.0
+Created-By: Apache Maven ${maven.version}
+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.
+
diff --git a/src/site/markdown/examples/manifestFile.md
b/src/site/markdown/examples/manifestFile.md
new file mode 100644
index 0000000..87f746c
--- /dev/null
+++ b/src/site/markdown/examples/manifestFile.md
@@ -0,0 +1,53 @@
+---
+title: Use Your Own Manifest File
+author:
+ - Dennis Lundberg
+date: 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 creates 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 created
by Maven Archiver. If you specify an entry in your own manifest file it will
override the value created 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.
+
+```xml
+<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>
+```
diff --git a/src/site/markdown/examples/manifestSections.md
b/src/site/markdown/examples/manifestSections.md
new file mode 100644
index 0000000..3179b15
--- /dev/null
+++ b/src/site/markdown/examples/manifestSections.md
@@ -0,0 +1,81 @@
+---
+title: Manifest Sections
+author:
+ - Olivier Lamy
+ - Dennis Lundberg
+date: 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 Sections
+
+The `<manifestSections>` element provides a way to add custom manifest
sections. It contains a list of
[`<manifestSection>`](../index.html#class_manifestSection) elements.
+
+**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.
+
+Given this configuration:
+
+```xml
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ ...
+ <configuration>
+ <archive>
+ <manifestSections>
+ <manifestSection>
+ <name>foo</name>
+ <manifestEntries>
+ <id>nice foo</id>
+ </manifestEntries>
+ </manifestSection>
+ <manifestSection>
+ <name>bar</name>
+ <manifestEntries>
+ <id>nice bar</id>
+ </manifestEntries>
+ </manifestSection>
+ </manifestSections>
+ </archive>
+ </configuration>
+ ...
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
+```
+
+The following content will end up in the manifest:
+
+```
+Manifest-Version: 1.0
+Created-By: Apache Maven ${maven.version}
+Build-Jdk: ${java.version}
+
+Name: foo
+id: nice foo
+
+Name: bar
+id: nice bar
+```
