You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by hb...@apache.org on 2021/01/03 23:03:06 UTC
[maven-artifact-plugin] branch master updated: add documentation
This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-artifact-plugin.git
The following commit(s) were added to refs/heads/master by this push:
new 7a7ec06 add documentation
7a7ec06 is described below
commit 7a7ec06a2300c5e9656f1fd77f748f2c09717d17
Author: Hervé Boutemy <hb...@apache.org>
AuthorDate: Mon Jan 4 00:02:43 2021 +0100
add documentation
---
src/site/apt/index.apt.vm | 5 +-
src/site/apt/reproducible.apt.vm | 120 +++++++++++++++++++++++++++++++++++++++
src/site/apt/usage.apt.vm | 45 +++++++++++++++
src/site/fml/faq.fml | 16 ++++--
src/site/site.xml | 4 ++
5 files changed, 182 insertions(+), 8 deletions(-)
diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm
index 96b237f..e71afe3 100644
--- a/src/site/apt/index.apt.vm
+++ b/src/site/apt/index.apt.vm
@@ -34,7 +34,8 @@ ${project.name}
The Artifact Plugin only has one goal currently.
- * {{{./buildinfo-mojo.html}artifact:buildinfo}} .
+ * {{{./buildinfo-mojo.html}artifact:buildinfo}} records current build results in {{{https://reproducible-builds.org/docs/jvm/}Reproducible Builds buildinfo}} file
+ and eventually compares against reference build previously published.
* Usage
@@ -59,6 +60,6 @@ ${project.name}
To provide you with better understanding on some usages of the Artifact Plugin,
you can take a look into the following examples:
- * {{{./examples/skipping-clean.html}How to skipping clean execution?}}
+ * {{{./reproducible.html}How to diagnose issues with Reproducible Builds?}}
[]
diff --git a/src/site/apt/reproducible.apt.vm b/src/site/apt/reproducible.apt.vm
new file mode 100644
index 0000000..f785068
--- /dev/null
+++ b/src/site/apt/reproducible.apt.vm
@@ -0,0 +1,120 @@
+ ------
+ Diagnosing Reproducible Build Issue
+ ------
+ Hervé Boutemy
+ ------
+ 2020-06-20
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Diagnosing Reproducible Build Issues
+
+ When checking Reproducible Build, you may find that the current build output is not the same as the reference:
+
+-------
+$ mvn -Papache-release clean verify -Dgpg.skip artifact:buildinfo -Dreference.repo=central
+[INFO] Scanning for projects...
+...
+[INFO] --- maven-artifact-plugin:${project.version}:buildinfo (default-cli) @ doxia-module-markdown ---
+[INFO] Saved aggregate info on build to /tmp/doxia-1.9.1/doxia-modules/doxia-module-markdown/target/doxia-module-markdown-1.9.1.buildinfo
+[INFO] Checking against reference build from central...
+Downloading from central: https://repo.maven.apache.org/maven2/org/apache/maven/doxia/doxia-module-markdown/1.9.1/doxia-module-markdown-1.9.1.buildinfo
+[WARNING] Reference buildinfo file not found: it will be generated from downloaded reference artifacts
+[INFO] Reference build java.version: 1.8 (from MANIFEST.MF Build-Jdk-Spec)
+[INFO] Reference build os.name: Unix (from pom.properties newline)
+[INFO] Minimal buildinfo generated from downloaded artifacts: /tmp/doxia-1.9.1/target/reference/doxia-module-markdown-1.9.1.buildinfo
+[WARNING] size mismatch doxia-logging-api-1.9.1.jar: investigate with diffoscope target/reference/doxia-logging-api-1.9.1.jar doxia-logging-api/target/doxia-logging-api-1.9.1.jar
+[WARNING] size mismatch doxia-sink-api-1.9.1.jar: investigate with diffoscope target/reference/doxia-sink-api-1.9.1.jar doxia-sink-api/target/doxia-sink-api-1.9.1.jar
+[WARNING] sha512 mismatch doxia-test-docs-1.9.1.jar: investigate with diffoscope target/reference/doxia-test-docs-1.9.1.jar doxia-test-docs/target/doxia-test-docs-1.9.1.jar
+...
+[WARNING] Reproducible Build output summary: 20 files ok, 18 different
+[WARNING] see diff target/reference/doxia-module-markdown-1.9.1.buildinfo doxia-modules/doxia-module-markdown/target/doxia-module-markdown-1.9.1.buildinfo
+[WARNING] see also https://maven.apache.org/guides/mini/guide-reproducible-builds.html
+...
+-------
+
+ Multiple interesting parts are available:
+
+ * the summary: <<<[WARNING] Reproducible Build output summary: 20 files ok, 18 different>>>
+
+ * key information on reference build environment:\
+ <<<[INFO] Reference build java.version: 1.8 (from MANIFEST.MF Build-Jdk-Spec)>>>\
+ <<<[INFO] Reference build os.name: Unix (from pom.properties newline)>>>\
+ which are the key requirements (JDK major version and Operating System) for the build environment to reproduce the reference build
+
+ * on each artifact different from reference, a command is provided to investigate differences using {{{https://diffoscope.org/}diffoscope tool}}, a diff tool working inside archives (jar, zip, tar, ...):\
+ simply copy paste provided command like <<<diffoscope target/reference/doxia-logging-api-1.9.1.jar doxia-logging-api/target/doxia-logging-api-1.9.1.jar>>> and you'll see where differences are:
+
++----------
+$ diffoscope target/reference/doxia-logging-api-1.9.1.jar doxia-logging-api/target/doxia-logging-api-1.9.1.jar
+--- target/reference/doxia-logging-api-1.9.1.jar
++++ doxia-logging-api/target/doxia-logging-api-1.9.1.jar
+├── zipinfo /dev/stdin
+│ @@ -1,8 +1,8 @@
+│ -Zip file size: 11516 bytes, number of entries: 19
+│ +Zip file size: 11497 bytes, number of entries: 19
+│ -rw-r--r-- 2.0 unx 337 b- defN 20-Feb-13 21:11 META-INF/MANIFEST.MF
+│ drwxr-xr-x 2.0 unx 0 b- stor 20-Feb-13 21:11 META-INF/
+│ drwxr-xr-x 2.0 unx 0 b- stor 20-Feb-13 21:11 org/
+│ drwxr-xr-x 2.0 unx 0 b- stor 20-Feb-13 21:11 org/apache/
+│ drwxr-xr-x 2.0 unx 0 b- stor 20-Feb-13 21:11 org/apache/maven/
+│ drwxr-xr-x 2.0 unx 0 b- stor 20-Feb-13 21:11 org/apache/maven/doxia/
+│ drwxr-xr-x 2.0 unx 0 b- stor 20-Feb-13 21:11 org/apache/maven/doxia/logging/
+│ @@ -11,11 +11,11 @@
+│ drwxr-xr-x 2.0 unx 0 b- stor 20-Feb-13 21:11 META-INF/maven/org.apache.maven.doxia/doxia-logging-api/
+│ -rw-r--r-- 2.0 unx 1641 b- defN 20-Feb-13 21:11 META-INF/DEPENDENCIES
+│ -rw-r--r-- 2.0 unx 11358 b- defN 20-Feb-13 21:11 META-INF/LICENSE
+│ -rw-r--r-- 2.0 unx 177 b- defN 20-Feb-13 21:11 META-INF/NOTICE
+│ -rw-r--r-- 2.0 unx 716 b- defN 20-Feb-13 21:11 org/apache/maven/doxia/logging/Log.class
+│ -rw-r--r-- 2.0 unx 198 b- defN 20-Feb-13 21:11 org/apache/maven/doxia/logging/LogEnabled.class
+│ -rw-r--r-- 2.0 unx 2840 b- defN 20-Feb-13 21:11 org/apache/maven/doxia/logging/PlexusLoggerWrapper.class
+│ --rw-r--r-- 2.0 unx 4208 b- defN 20-Feb-13 21:11 org/apache/maven/doxia/logging/SystemStreamLog.class
+│ +-rw-r--r-- 2.0 unx 4192 b- defN 20-Feb-13 21:11 org/apache/maven/doxia/logging/SystemStreamLog.class
+│ -rw-r--r-- 2.0 unx 1539 b- defN 20-Feb-13 21:11 META-INF/maven/org.apache.maven.doxia/doxia-logging-api/pom.xml
+│ -rw-r--r-- 2.0 unx 74 b- defN 20-Feb-13 21:11 META-INF/maven/org.apache.maven.doxia/doxia-logging-api/pom.properties
+│ -19 files, 23088 bytes uncompressed, 8842 bytes compressed: 61.7%
+│ +19 files, 23072 bytes uncompressed, 8823 bytes compressed: 61.8%
+├── META-INF/MANIFEST.MF
+│ @@ -1,10 +1,10 @@
+│ Manifest-Version: 1.0
+│ +Implementation-Vendor: The Apache Software Foundation
+│ Implementation-Title: Doxia :: Logging API
+│ Implementation-Version: 1.9.1
+│ +Build-Jdk-Spec: 1.7
+│ Specification-Vendor: The Apache Software Foundation
+│ -Specification-Title: Doxia :: Logging API
+│ -Build-Jdk-Spec: 1.8
+│ Created-By: Maven Jar Plugin 3.2.0
+│ +Specification-Title: Doxia :: Logging API
+│ Specification-Version: 1.9
+│ -Implementation-Vendor: The Apache Software Foundation
+├── org/apache/maven/doxia/logging/PlexusLoggerWrapper.class
+...
++----------
+
+ []
+
+ In this example, reference build was done with JDK 8 (see <<<│ -Build-Jdk-Spec: 1.8>>>), but the current build was done with JDK 7 (see <<<│ +Build-Jdk-Spec: 1.7>>>): this explains both
+ difference in content of <<<META-INF/MANIFEST.MF>>> of every .jar file, but also of some bytecode in <<<.class>>> files.
+
+ When general environment issues have been fixed, for each remaining issue, you'll have to find which Maven plugin generated the content and see if there is an update of the plugin
+ that generates reproducible output: see the plugins table of the {{{Configuring for Reproducible Builds guide}/guides/mini/guide-reproducible-builds.html}} for an initial list.
diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm
index e1523c9..2b1c0a9 100644
--- a/src/site/apt/usage.apt.vm
+++ b/src/site/apt/usage.apt.vm
@@ -29,3 +29,48 @@
Usage
The Maven Artifact Plugin...
+
+* Recording <<<.buildinfo>>> File
+
+ Recording build result into a <<<.buildinfo>>> file is typically done on command line by calling <<<artifact:buildinfo>>> goal after the normal build:
+
+-------
+$ mvn clean verify artifact:buildinfo
+[INFO] Scanning for projects...
+[INFO]
+[INFO] ----------------< org.apache.maven.sample:test-project >----------------
+[INFO] Building Test Project 1.0-SNAPSHOT
+[INFO] --------------------------------[ jar ]---------------------------------
+...
+[INFO] --- maven-artifact-plugin:${project.version}:buildinfo (default-cli) @ test-project ---
+[INFO] Saved info on build to /tmp/test-project/target/test-project-1.0-SNAPSHOT.buildinfo
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+-------
+
+ This records data on the current build results into a <<<.buildinfo>>> file using {{{https://reproducible-builds.org/docs/jvm/}Reproducible Builds <<<.buildinfo>>> for the JVM}} format.
+
+ Notice that if the build is multi-module, only 1 <<<.buildinfo>>> file is generated, in the last module of the reactor, that will record aggregated results for all the modules.
+
+* Checking Reproducible Build: Comparing Current Build Against Previous One
+
+ When the <<<artifact:buildinfo>>> goal is used with <<<reference.repo>>> command-line parameter, it uses the parameter value as a reference of a remote repository
+ (either its id like <<<central>>> or an url like <<<https://repository.apache.org/content/repositories/maven-1619>>>)
+ to get reference artifacts from it, then compares reference artifacts against current build output to display <<Reproducible Build output summary>>:
+
+-------
+$ mvn -Papache-release clean verify -Dgpg.skip artifact:buildinfo -Dreference.repo=central
+[INFO] Scanning for projects...
+...
+[INFO] --- maven-artifact-plugin:${project.version}:buildinfo (default-cli) @ doxia-module-markdown ---
+[INFO] Saved aggregate info on build to /tmp/doxia-1.9.1/doxia-modules/doxia-module-markdown/target/doxia-module-markdown-1.9.1.buildinfo
+[INFO] Checking against reference build from central...
+Downloading from central: https://repo.maven.apache.org/maven2/org/apache/maven/doxia/doxia-module-markdown/1.9.1/doxia-module-markdown-1.9.1.buildinfo
+[WARNING] Reference buildinfo file not found: it will be generated from downloaded reference artifacts
+[INFO] Reference build java.version: 1.8 (from MANIFEST.MF Build-Jdk-Spec)
+[INFO] Reference build os.name: Unix (from pom.properties newline)
+[INFO] Minimal buildinfo generated from downloaded artifacts: /tmp/doxia-1.9.1/target/reference/doxia-module-markdown-1.9.1.buildinfo
+[INFO] Reproducible Build output summary: 38 files ok
+...
+-------
diff --git a/src/site/fml/faq.fml b/src/site/fml/faq.fml
index d03d05e..0f95fa6 100644
--- a/src/site/fml/faq.fml
+++ b/src/site/fml/faq.fml
@@ -19,11 +19,15 @@ specific language governing permissions and limitations
under the License.
-->
-
-<faqs xmlns="http://maven.apache.org/FML/1.0.1"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd"
+<faqs xmlns="http://maven.apache.org/FML/1.0.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 https://maven.apache.org/xsd/fml-1.0.1.xsd"
id="FAQ" title="Frequently Asked Questions">
<part id="General">
- </part>
-</faqs>
\ No newline at end of file
+ <faq id="Configure Reproducible Builds">
+ <question>How to configure my Maven build for Reproducible Builds?</question>
+ <answer>
+ <p>See the <a href="/guides/mini/guide-reproducible-builds.html">Configuring for Reproducible Builds guide</a>.</p>
+ </answer>
+ </faq>
+ </part>
+</faqs>
diff --git a/src/site/site.xml b/src/site/site.xml
index 064eb2f..39b3c54 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -32,5 +32,9 @@ under the License.
<item name="License" href="http://www.apache.org/licenses/"/>
<item name="Download" href="download.html"/>
</menu>
+
+ <menu name="Examples">
+ <item name="Diagnosing Reproducible Build Issues" href="reproducible.html"/>
+ </menu>
</body>
</project>