Reproducibility Quickstart Guide

This is a brief guide to help you get started writing software that builds reproducibly.

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: A common approach is to compare file checksums rather than the artifacts, but using diff tools or the cmp command are also valid alternatives.

Note: Software builds that involve cryptographic code signing may complicate basic file-to-file comparisons, because some code signing techniques intentionally introduce randomness. To learn how to deal with those situations, refer to the embedded signatures documentation.

If the results differ, then you have found a reproducibility bug either in your software or in your toolchain, and can proceed directly to the 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   │
└──────────────────────┬──────────────────────────┘
                       │
      ┌────────────────▼──────────────────┐
      │        Build your project         │
      └────────────────┬──────────────────┘
                       │
      ┌────────────────▼──────────────────┐
  ┌──►│         Build it again            │
  │   └────────────────┬──────────────────┘
  │                    │
  │   ┌────────────────▼──────────────────┐   No     ┌───────────────────────┐
  │   │      Is the output identical?     ├─────────►│ GOTO: Troubleshooting │
  │   └────────────────┬──────────────────┘          └───────────────────────┘
  │                    │  Yes
  │         ┌──────────▼───────────┐
  └─────────│ GOTO: Add variations │
            └──────────────────────┘

Reproducibility Quickstart Guide

Introduction

Achieve deterministic builds

Managing variance

Define a build environment

Distribute the environment

Verification

Specifications