1 files changed, 152 insertions, 0 deletions
diff --git a/scripts/debrepro.pod b/scripts/debrepro.pod
new file mode 100644
index 0000000..edf8d92
--- /dev/null
+++ b/scripts/debrepro.pod
@@ -0,0 +1,152 @@
+=head1 NAME
+
+debrepro - reproducibility tester for Debian packages
+
+=head1 SYNOPSIS
+
+B<debrepro> [I<OPTIONS>] [I<SOURCEDIR>]
+
+=head1  DESCRIPTION
+
+B<debrepro> will build a given source directory twice, with a set of
+variations between the first and the second build, and compare the
+produced binary packages. If B<diffoscope> is installed, it is used to
+compare non-matching binaries. If B<disorderfs> is installed, it is used
+during the build to inject non-determinism in filesystem listing
+operations.
+
+I<SOURCEDIR> must be a directory containing an unpacked Debian source
+package. If I<SOURCEDIR> is omitted, the current directory is assumed.
+
+=head1 OUTPUT DIRECTORY
+
+At the very end of a build, B<debrepro> will inform the location of the
+output directory where the build artifacts can be found. In that
+directory, you will find:
+
+=over
+
+=item I<$OUTPUTDIR/first>
+
+Contains the results of the first build, including a copy of the source
+tree, and the resulting binary packages.
+
+=item I<$OUTPUTDIR/first/build.sh>
+
+Contains the exact build script that was used in the first build.
+
+=item I<$OUTPUTDIR/second>
+
+Contains the results of the second build, including a copy of the source tree,
+and the resulting binary packages.
+
+=item I<$OUTPUTDIR/second/build.sh>
+
+Contains the exact build script that was used in the second build.
+
+=back
+
+Taking a B<diff(1)> between I<$OUTPUTDIR/first/build.sh> and
+I<$OUTPUTDIR/second/build.sh> is an excellent way of figuring out
+exactly what changed between the two builds.
+
+=head1 SUPPORTED VARIATIONS
+
+=over
+
+=item B<user>
+
+The I<$USER> environment variable will contain different values between the
+first and second builds.
+
+=item B<path>
+
+During the second build, a fake, non-existing directory will be appended to the
+I<$PATH> environment variable.
+
+=item B<umask>
+
+The builds will use different umask settings.
+
+=item B<locale>
+
+Both I<$LC_ALL> and I<$LANG> will be different across the two builds.
+
+=item B<timezone>
+
+I<$TZ> will be different across builds.
+
+=item B<filesystem-ordering>
+
+If B<disorderfs> is installed, both builds will be done under a disorderfs
+overlay directory. This will cause filesystem listing operations to be return
+items in a non-deterministic order.
+
+=item B<time>
+
+The second build will be executed 213 days, 7 hours and 13 minutes in the
+future with regards to the current time (using B<faketime(1)>).
+
+=back
+
+=head1 OPTIONS
+
+=over
+
+=item -s VARIATION, --skip VARIATION
+
+Don't perform the named VARIATION. Variation names are the ones used in
+their description in section B<SUPPORTED VARIATIONS>.
+
+=item -b COMMAND, --before-second-build COMMAND
+
+Run COMMAND before performing the second build. This can be used for
+example to apply a patch to a source tree for the second build, and
+check whether (or how) the resulting binaries are affected.
+
+Examples:
+
+  $ debrepro --before-second-build "git checkout branch-with-changes"
+
+  $ debrepro --before-second-build "patch -p1 < /path/to/patch"
+
+=item -h, --help
+
+Display this help message and exit.
+
+=back
+
+=head1 EXIT STATUS
+
+=over
+
+=item 0Z<>
+
+Package is reproducible.
+
+Reproducible here means that the two builds produced the exactly the
+same binaries, under the set of variations that B<debrepro> tests. Other
+sources of non-determinism in builds that are not yet tested might still
+affect builds in the wild.
+
+=item 1Z<>
+
+Package is not reproducible.
+
+=item 2Z<>
+
+The given input is not a valid Debian source package.
+
+=item 3Z<>
+
+Required programs are missing.
+
+=back
+
+=head1 SEE ALSO
+
+diffoscope (1), disorderfs (1),
+
+=head1  AUTHOR
+
+Antonio Terceiro <terceiro@debian.org>.