=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 -B COMMAND, --build-command COMMAND

Use custom build command. Default: I<dpkg-buildpackage -b -us -uc>.

If a custom build command is specified, the restriction of only running
against a Debian source tree is relaxed and you can run debrepro against
any source directory.

=item -a PATTERN, --artifact-pattern PATTERN

Define a file glob pattern to determine which artifacts need to be
compared across the builds. Default: I<../*.deb>.

=item -n, --no-copy

Do not copy the source directory to the temporary work directory before
each build. Use this to run debrepro against the source directory
directly.

=item -t TIME, --timeout TIME

Apply a timeout to all builds. I<TIME> must be a time specification
compatible with GNU timeout(1).


=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), timeout(1)

=head1  AUTHOR

Antonio Terceiro <terceiro@debian.org>.