[Git][reproducible-builds/reproducible-website][issue-56/getting-started-guide] 4 commits: Editing: cleanup / prepare markdown
James Addison (@jayaddison)
gitlab at salsa.debian.org
Sat Oct 5 19:54:35 UTC 2024
James Addison pushed to branch issue-56/getting-started-guide at Reproducible Builds / reproducible-website
Commits:
7db3ad37 by James Addison at 2024-10-05T20:30:31+01:00
Editing: cleanup / prepare markdown
- - - - -
1eee467a by James Addison at 2024-10-05T20:44:52+01:00
Jekyll: add distinct document headings
- - - - -
d692fd28 by James Addison at 2024-10-05T20:49:05+01:00
Editing: fix hyperlinks
- - - - -
301e6e3d by James Addison at 2024-10-05T20:53:46+01:00
Troubleshooting guide: fix table markup
- - - - -
3 changed files:
- _docs/getting-started-troubleshooting.md
- _docs/getting-started-variations.md
- _docs/getting-started.md
Changes:
=====================================
_docs/getting-started-troubleshooting.md
=====================================
@@ -1,5 +1,8 @@
-Troubleshooting
-===============
+---
+title: Reproducibility Troubleshooting
+layout: docs
+permalink: /docs/reproducibility-troubleshooting/
+---
A few hints:
@@ -10,16 +13,14 @@ A few hints:
* 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[link].
+Compare the differing output files, using a tool such as [diffoscope](https://diffoscope.org/).
We now need to inspect the differences and to try to understand what could have caused each of them.
In some cases, the differences themselves may provide some hints about possible fixes. For example:
- | table of examples |g
+| 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/) |
- | before | after | seems to be a... | possible remedy
-
- | 2021-04-10 | 2026-09-01 | date | SOURCE_DATE_EPOCH[link] |g
-
- https://gitlab.torproject.org/tpo/applications/tor-browser/-/wikis/Reproducible-Builds/Debugging-Android
+<!-- https://gitlab.torproject.org/tpo/applications/tor-browser/-/wikis/Reproducible-Builds/Debugging-Android -->
=====================================
_docs/getting-started-variations.md
=====================================
@@ -1,5 +1,8 @@
-Adding build variance
-=====================
+---
+title: Adding build variance
+layout: docs
+permalink: /docs/adding-build-variance/
+---
Rebuilding software on an individual machine and obtaining the same output does not guarantee that the software will always build reproducibly.
@@ -7,9 +10,9 @@ 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.
+<!-- [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. -->
-Tooling such as reprotest[hyperlink] 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.
+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.
## Factors that we would like to prevent from affecting the build output
@@ -20,33 +23,37 @@ Tooling such as reprotest[hyperlink] has been developed to systematically explor
- CPU speed, number of cores, load of the build machine
- hostname, user name, build path
+
### Reprotest
-[Reprotest] is a tool that rebuilds a project in different environments automatically.
+[`reprotest`](https://salsa.debian.org/reproducible-builds/reprotest) is a tool that rebuilds a project in different environments automatically.
+
It can apply several variations, including build path, file order, locales, hostname, etc...
It is especially aimed at Debian packages, but it can be configured to also run with other build systems.
-Its [readme] offers many examples about how to use it.
+Its [`README`](https://salsa.debian.org/reproducible-builds/reprotest/-/blob/master/README.rst) includes a variety of usage examples.
-[Reprotest](https://salsa.debian.org/reproducible-builds/reprotest)
-[readme](https://salsa.debian.org/reproducible-builds/reprotest/-/blob/master/README.rst)
## Factors that are usually acceptable to declare as constants
- Toolchain (compiler, ...)
- Dependencies listed in your project
+
### Lockfiles
Some build systems (Go, Cargo, NPM...) allow you to include the exact version of your dependencies.
Whenever possible, you should version it or include it in your source tarballs, so that people will be able to use them to recreate a similar environment to you.
+
### Vendored dependencies
Another possibility is to include a copy of your dependencies in your source tree, or to reference it with similar methods, such as git submodules.
+
### Debian Snapshots
Debian packages must be reproducible with the packages that were availalbe in the archive when they were built.
-You can use snapshot.debian.org to create a system in that state.
+
+You can use [`snapshot.debian.org`](https://snapshot.debian.org/) to create a system in that state.
=====================================
_docs/getting-started.md
=====================================
@@ -1,34 +1,43 @@
-Reproducibility Quickstart Guide
-================================
+---
+title: Reproducibility Quickstart Guide
+layout: docs
+permalink: /docs/getting-started/
+---
-This is a brief guide to help you get started writing software that builds reproducibly[link].
+This is a brief guide to help you get started writing software that builds [reproducibly](/docs/definition/).
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: 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. -->
-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[link] guide.
+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.
If the output is identical, then you should add more variance to the build environment to examine less-obvious factors that might influence the output:
-┌───────────────────────────────────────────────┐
-│ Define what output needs to be reproducible │
-└──────────────────────┬────────────────────────┘
+```
+┌─────────────────────────────────────────────────┐
+│ Define what output needs to be reproducible │
+└──────────────────────┬──────────────────────────┘
│
- ┌──────────────▼──────────────────┐
- │ Build your project │
- └──────────────┬──────────────────┘
+ ┌────────────────▼──────────────────┐
+ │ Build your project │
+ └────────────────┬──────────────────┘
│
- ▼
- ┌───────────────────────────────────┐
- ┌──►│ Build it again │
+ ┌────────────────▼──────────────────┐
+ ┌──►│ Build it again │
│ └────────────────┬──────────────────┘
│ │
│ ┌────────────────▼──────────────────┐ No ┌────────────────────┐
- │ │ Are the results identical? ├─────────►│ Troubleshoot[link] │
+ │ │ Is the output identical? ├─────────►│ GOTO: Troubleshoot │
│ └─────────────────┬─────────────────┘ └────────────────────┘
│ │ Yes
- │ ┌─────────▼─────────────┐
- └───────────│ Add variations[link] │
- └───────────────────────┘
+ │ ┌─────────▼────────────┐
+ └───────────│ GOTO: Add variations │
+ └──────────────────────┘
+```
+
+Destinations:
+
+ * [`Troubleshoot`](/docs/reproducibility-troubleshooting/)
+ * [`Add variations`](/docs/adding-build-variance/)
View it on GitLab: https://salsa.debian.org/reproducible-builds/reproducible-website/-/compare/636d231e0ac34dc21553059a531ddae29154cd3b...301e6e3de643c10b2cddc1248314c3988fe5f94d
--
View it on GitLab: https://salsa.debian.org/reproducible-builds/reproducible-website/-/compare/636d231e0ac34dc21553059a531ddae29154cd3b...301e6e3de643c10b2cddc1248314c3988fe5f94d
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/20241005/601f9d52/attachment.htm>
More information about the rb-commits
mailing list