[Git][reproducible-builds/reproducible-website][issue-56/getting-started-guide] 3 commits: Restore commented-out admonitions/paragraphs
James Addison (@jayaddison)
gitlab at salsa.debian.org
Sun Oct 13 19:08:39 UTC 2024
James Addison pushed to branch issue-56/getting-started-guide at Reproducible Builds / reproducible-website
Commits:
44104179 by James Addison at 2024-10-13T20:08:10+01:00
Restore commented-out admonitions/paragraphs
- - - - -
b7dbdd1c by James Addison at 2024-10-13T20:08:10+01:00
Expand Troubleshooting section
- - - - -
6b5f8a6c by James Addison at 2024-10-13T20:08:10+01:00
Fixup: dedent list items
- - - - -
3 changed files:
- _docs/getting-started-troubleshooting.md
- _docs/getting-started-variations.md
- _docs/getting-started.md
Changes:
=====================================
_docs/getting-started-troubleshooting.md
=====================================
@@ -4,16 +4,25 @@ layout: docs
permalink: /docs/reproducibility-troubleshooting/
---
-A few hints:
+To identify the origin of non-deterministic build outputs:
- * Isolating individual outputs of the build process
+ * Try to isolate the build steps involved. For example: it may be possible to perform a partial rebuild of the affected files, and/or to temporarily comment-out irrelevant source code until the problem disappears.
- * Comparing the content that differs in the build outputs
+ * Smaller builds are generally quicker, and this is likely to allow you to experiment more rapidly.
+ * Removing irrelevant code allows you and collaborators to narrow the focus of your investigation.
+ * Minimal examples are often helpful as test cases and for communication purposes.
- * If the problem occurred after introducing a variation, then that also provides a hint about potentially-relevant causes
+ * Compare the differing output files, using a tool such as [diffoscope](https://diffoscope.org/).
+ * Sometimes the nature of the content difference itself will provide clues (see below).
+ * Context surrounding the difference may help you to locate relevant source code.
-Compare the differing output files, using a tool such as [diffoscope](https://diffoscope.org/).
+ * Try to pinpoint the [variance factor](/docs/adding-build-variance/) that causes the difference. Tools such as [reprotest](https://salsa.debian.org/reproducible-builds/reprotest) may be able to help.
+
+ * This will allow you to focus your experimentation on the relevant factor.
+ * Knowing the variance factor should also make it easier to consult relevant [documentation](https://reproducible-builds.org/docs/).
+
+With some luck and/or persistence, you should obtain an idea of the affected build step, the different values that appear, and the input factors that introduce them.
We now need to inspect the differences and to try to understand what could have caused each of them.
@@ -22,5 +31,4 @@ In some cases, the differences themselves may provide some hints about possible
| table of examples |
| before | after | seems to be a... | possible remedy |
| 2021-04-10 | 2026-09-01 | date | Configure [`SOURCE_DATE_EPOCH`](https://reproducible-builds.org/docs/source-date-epoch/) |
-
-<!-- https://gitlab.torproject.org/tpo/applications/tor-browser/-/wikis/Reproducible-Builds/Debugging-Android -->
+| APK file A | APK file B | Android build difference | [Unpack the APK and examine the contents](https://gitlab.torproject.org/tpo/applications/tor-browser/-/wikis/Reproducible-Builds/Debugging-Android) |
=====================================
_docs/getting-started-variations.md
=====================================
@@ -10,7 +10,7 @@ For example: a program that embeds the hostname of the build computer would not
Changing the compiler (and version) you use could also introduce differences. However, to achieve reproducible build results, it is generally acceptable to specify precise toolchain version(s) that other people should use when attempting to achieve an identical build.
-<!-- [explanation:factors] There are some conventions about factors that are acceptable to keep constant[hyperlink:L117] -- these include the compiler, compiler version, and the versions of other software that the software depends upon. In contrast, there are other variable factors that we do expect and should accommodate when the software is rebuilt in diverse environments[hyperlink:L97]. It is a good idea to confirm that your software builds reproducibly in those environments too. -->
+**Note**: There are some conventions about factors that are acceptable to keep constant -- these include the compiler, compiler version, and the versions of other software that the software depends upon. In contrast, there are other variable factors that we do expect to vary, and that we should accommodate when the software is rebuilt in diverse environments. It is a good idea to confirm that your software builds reproducibly in those environments too.
Tooling such as [`reprotest`](https://salsa.debian.org/reproducible-builds/reprotest) has been developed to systematically explore the factors that can affect build reproducibility, and we recommend re-using existing utilities rather than writing your own.
=====================================
_docs/getting-started.md
=====================================
@@ -8,8 +8,9 @@ This is a brief guide to help you get started writing software that builds [repr
The easiest check that you can perform, without installing any additional software tooling, is to build your software twice and to compare the build output files.
-<!-- [tip: comparison] A common approach is to [compare cryptographic hashes](https://reproducible-builds.org/docs/checksums/) rather than the artifacts, but using diff tools or the `cmp` command are also valid alternatives.
-This works as long as the builds are reproducible byte-by-byte, but embedded signatures make this difficult. You can check [this page](https://reproducible-builds.org/docs/embedded-signatures/) for some suggestions on how to deal with them. -->
+**Tip**: A common approach is to [compare cryptographic hashes](https://reproducible-builds.org/docs/checksums/) rather than the artifacts, but using diff tools or the `cmp` command are also valid alternatives.
+
+This works as long as the builds are reproducible byte-by-byte, but embedded signatures make this difficult. You can check [this page](https://reproducible-builds.org/docs/embedded-signatures/) for some suggestions on how to deal with them.
If the results differ, then you have found reproducibility bug either in your software or in your toolchain, and can proceed directly to the [troubleshooting](/docs/reproducibility-troubleshooting/) guide.
View it on GitLab: https://salsa.debian.org/reproducible-builds/reproducible-website/-/compare/2712efe08b3caab1c6854dfd3835bfea83136d44...6b5f8a6c5e7a8b8158be893dfa94cd9ab366c277
--
View it on GitLab: https://salsa.debian.org/reproducible-builds/reproducible-website/-/compare/2712efe08b3caab1c6854dfd3835bfea83136d44...6b5f8a6c5e7a8b8158be893dfa94cd9ab366c277
You're receiving this email because of your account on salsa.debian.org.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.reproducible-builds.org/pipermail/rb-commits/attachments/20241013/3c73cdfa/attachment.htm>
More information about the rb-commits
mailing list