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-site.git
commit 69bf46c79ddf947909eac6c76a3fee20b53f5830 Author: Sylwester Lachiewicz <[email protected]> AuthorDate: Sat Oct 31 19:58:15 2026 +0000 Move Maven Archiver manifest examples into the manifest guide --- content/filtered-resources/.htaccess | 6 + content/markdown/guides/mini/guide-manifest.md | 283 ++++++++++++++++++++++++- 2 files changed, 280 insertions(+), 9 deletions(-) diff --git a/content/filtered-resources/.htaccess b/content/filtered-resources/.htaccess index fea0a5d3..db49b5bc 100644 --- a/content/filtered-resources/.htaccess +++ b/content/filtered-resources/.htaccess @@ -27,6 +27,12 @@ Redirect Permanent /plugins/maven-checkstyle-plugin/customize.html /plugins/mave Redirect Permanent /plugins/maven-checkstyle-plugin/howto.html /plugins/maven-checkstyle-plugin/usage.html Redirect Permanent /plugins/maven-checkstyle-plugin/tips.html /plugins/maven-checkstyle-plugin/examples/multi-module-config.html +Redirect Permanent /shared/maven-archiver/examples/classpath.html /guides/mini/guide-manifest.html#Setting_Up_the_Classpath +Redirect Permanent /shared/maven-archiver/examples/manifest.html /guides/mini/guide-manifest.html#Default_Manifest +Redirect Permanent /shared/maven-archiver/examples/manifestEntries.html /guides/mini/guide-manifest.html#Manifest_Entries +Redirect Permanent /shared/maven-archiver/examples/manifestFile.html /guides/mini/guide-manifest.html#Using_Your_Own_Manifest_File +Redirect Permanent /shared/maven-archiver/examples/manifestSections.html /guides/mini/guide-manifest.html#Manifest_Sections + RedirectMatch ^/maven2/(.*)$ /$1 RedirectMatch ^/reference/(.*)$ /archives/maven-1.x/reference/$1 RedirectMatch ^/maven-1.x/reference/plugins/(.*)$ /archives/maven-1.x/plugins/$1 diff --git a/content/markdown/guides/mini/guide-manifest.md b/content/markdown/guides/mini/guide-manifest.md index 374d7439..9e9548c6 100644 --- a/content/markdown/guides/mini/guide-manifest.md +++ b/content/markdown/guides/mini/guide-manifest.md @@ -19,12 +19,277 @@ under the License. # Guide to Working with Manifests -In order to modify the manifest of the archive produced by the packaging plug-ins you need to create a configuration for it. The definitive guide for this is [the site for the Maven Archiver shared component](/shared/maven-archiver/index.html). This component is used by all our packaging plugins. - -<!-- suggestion by jorg--> -<!-- it would be nice if the Specification-Version could be easily generated to be major.minor of pom.currentVersion i.e. that--> -<!----> -<!-- 1.2 ==> 1.2--> -<!-- 1.2.1 ==> 1.2--> -<!-- 1.2-SNAPSHOT ==> 1.2--> -<!-- for the javaapp-plugin I did something like this in Jelly ...--> +The archive-producing plugins (`jar`, `war`, `ejb`, `ear` and others) build the manifest of their archive with [Maven Archiver](/shared/maven-archiver/index.html). You adjust it in the `archive` element of the plugin configuration, see [Guide to Configuring Archive Plugins](./guide-archive-configuration.html). The examples below use `maven-jar-plugin`, but they work in every plugin that uses Maven Archiver. The [Maven Archiver reference](/shared/maven-archiver/index.html) lists every `ar [...] + +## Default Manifest + +Without any configuration the manifest contains these entries: + +``` +Manifest-Version: 1.0 +Created-By: Maven JAR Plugin 3.5.1 +Java-Version: 17 +Build-Jdk-Spec: 21 +``` + +- `Created-By` names the plugin that built the archive, with its version. +- `Java-Version` is the `release` (or else `target`) of `maven-compiler-plugin`, such as the `maven.compiler.release` property. It is left out when neither is set. +- `Build-Jdk-Spec` is the specification version of the JDK running Maven, here 21. It does not take [toolchains](./guide-using-toolchains.html) into account. + +Set `<addDefaultEntries>false</addDefaultEntries>` in `<manifest>` to leave out `Created-By`, `Java-Version` and `Build-Jdk-Spec`. + +## Adding Implementation And Specification Details + +Implementation and specification entries are not added by default. Ask for them in the `manifest` element: + +```xml +<plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-jar-plugin</artifactId> + <version>3.5.1</version> + <configuration> + <archive> + <manifest> + <addDefaultImplementationEntries>true</addDefaultImplementationEntries> + <addDefaultSpecificationEntries>true</addDefaultSpecificationEntries> + </manifest> + </archive> + </configuration> +</plugin> +``` + +For a project named `Demo`, version `1.2.3`, whose `<organization>` is named `Acme`, the manifest gets these entries on top of the default ones: + +``` +Specification-Title: Demo +Specification-Version: 1.2 +Specification-Vendor: Acme +Implementation-Title: Demo +Implementation-Version: 1.2.3 +Implementation-Vendor: Acme +``` + +`Specification-Version` is the major and minor version of the project. If the POM has no `<organization>`/`<name>`, the two `Vendor` entries are left out. + +To record the build environment, add `<addBuildEnvironmentEntries>true</addBuildEnvironmentEntries>` to `<manifest>`. It adds `Build-Tool` (the Maven version), `Build-Jdk` (JDK version and vendor) and `Build-Os` (operating system name, version and architecture). Those values differ between machines, so they make a [reproducible build](./guide-reproducible-builds.html) harder to achieve. + +## Manifest Entries + +If the other options do not cover what you need, add your own entries with `<manifestEntries>`. Values can be literals or POM expressions: + +```xml +<project> + <url>http://some.url.org/</url> + ... + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-jar-plugin</artifactId> + <version>3.5.1</version> + <configuration> + <archive> + <manifestEntries> + <mode>development</mode> + <url>${project.url}</url> + </manifestEntries> + </archive> + </configuration> + </plugin> + </plugins> + </build> +</project> +``` + +The manifest then contains: + +``` +mode: development +url: http://some.url.org/ +``` + +If the POM has no `<url>`, the expression cannot be resolved and the `url` entry is left out. + +## Manifest Sections + +`<manifestSections>` adds named sections to the manifest. Each `<manifestSection>` has a `<name>` and its own `<manifestEntries>`: + +```xml +<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> +``` + +Each section follows the main section after a blank line: + +``` +Name: foo +id: nice foo + +Name: bar +id: nice bar +``` + +## Using Your Own Manifest File + +To start from a hand-written manifest, point `<manifestFile>` at it: + +```xml +<archive> + <manifestFile>src/main/resources/META-INF/MANIFEST.MF</manifestFile> +</archive> +``` + +The entries of your file are merged with the ones Maven Archiver creates, and an entry in your file overrides the generated one with the same name. + +## Setting Up the Classpath + +The examples in this section assume a project with these dependencies: + +```xml +<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> +``` + +The manifest excerpts show only the entries that the example adds. In the file itself, lines are wrapped at 72 bytes. + +### Adding a Class-Path Entry + +`<addClasspath>` adds the runtime dependencies of the project to the manifest: + +```xml +<archive> + <manifest> + <addClasspath>true</addClasspath> + </manifest> +</archive> +``` + +``` +Class-Path: commons-lang-2.1.jar plexus-utils-1.1.jar +``` + +### Making the Jar Executable + +An executable jar also needs the main class, set with `<mainClass>`: + +```xml +<archive> + <manifest> + <addClasspath>true</addClasspath> + <mainClass>fully.qualified.MainClass</mainClass> + </manifest> +</archive> +``` + +``` +Class-Path: commons-lang-2.1.jar plexus-utils-1.1.jar +Main-Class: fully.qualified.MainClass +``` + +### Defining a Classpath Directory Prefix + +When the dependencies live in a directory next to the archive, for example in a [skinny war](/plugins/maven-ear-plugin/examples/skinny-wars.html), add a `<classpathPrefix>`: + +```xml +<archive> + <manifest> + <addClasspath>true</addClasspath> + <classpathPrefix>lib/</classpathPrefix> + </manifest> +</archive> +``` + +``` +Class-Path: lib/commons-lang-2.1.jar lib/plexus-utils-1.1.jar +``` + +### Using a Maven Repository-Style Classpath + +If the archive holds a Maven repository-style directory tree, set `<classpathLayoutType>` to `repository`: + +```xml +<archive> + <manifest> + <addClasspath>true</addClasspath> + <classpathPrefix>lib/</classpathPrefix> + <classpathLayoutType>repository</classpathLayoutType> + </manifest> +</archive> +``` + +``` +Class-Path: lib/commons-lang/commons-lang/2.1/commons-lang-2.1.jar lib/org/codehaus/plexus/plexus-utils/1.1/plexus-utils-1.1.jar +``` + +### Using a Custom Classpath Format + +For any other layout, set `<classpathLayoutType>` to `custom` and describe the layout in `<customClasspathLayout>`: + +```xml +<archive> + <manifest> + <addClasspath>true</addClasspath> + <classpathLayoutType>custom</classpathLayoutType> + <customClasspathLayout>WEB-INF/lib/${artifact.groupIdPath}/${artifact.artifactId}-${artifact.version}${dashClassifier?}.${artifact.extension}</customClasspathLayout> + </manifest> +</archive> +``` + +``` +Class-Path: WEB-INF/lib/commons-lang/commons-lang-2.1.jar WEB-INF/lib/org/codehaus/plexus/plexus-utils-1.1.jar +``` + +Maven Archiver resolves each expression in the layout like this: + +1. If present, it trims the prefix `artifact.` from the expression. +2. It tries the expression as a property of the artifact (`artifactId` calls `getArtifactId()`). +3. It tries the expression as a property of the artifact's `ArtifactHandler` (`extension` calls `getExtension()`). +4. It tries the expression as a key of a special set of properties: + - `dashClassifier`: `-` followed by the classifier if the artifact has one, otherwise an empty string. + - `dashClassifier?`: a synonym of `dashClassifier`. + - `groupIdPath`: the group ID with each `.` replaced by `/`. + +### Handling Snapshot Versions + +By default, a snapshot dependency appears in the `Class-Path` with its timestamped version, such as `foo-1.0-20260101.120000-1.jar`. Which name your archive actually contains depends on how you assemble it. For example, the [Assembly Plugin](/plugins/maven-assembly-plugin/) decides this in the `<outputFileNameMapping>` of a `<dependencySet>`. + +To use the `-SNAPSHOT` name with the simple or repository layout, disable `<useUniqueVersions>`: + +```xml +<archive> + <manifest> + <addClasspath>true</addClasspath> + <useUniqueVersions>false</useUniqueVersions> + </manifest> +</archive> +``` + +With the custom layout, use `${artifact.baseVersion}` instead of `${artifact.version}`: + +```xml +<customClasspathLayout>WEB-INF/lib/${artifact.groupIdPath}/${artifact.artifactId}-${artifact.baseVersion}${dashClassifier?}.${artifact.extension}</customClasspathLayout> +```
