1=head1 NAME
2
3debrepro - reproducibility tester for Debian packages
4
5=head1 SYNOPSIS
6
7B<debrepro> [I<OPTIONS>] [I<SOURCEDIR>]
8
9=head1  DESCRIPTION
10
11B<debrepro> will build a given source directory twice, with a set of
12variations between the first and the second build, and compare the
13produced binary packages. If B<diffoscope> is installed, it is used to
14compare non-matching binaries. If B<disorderfs> is installed, it is used
15during the build to inject non-determinism in filesystem listing
16operations.
17
18I<SOURCEDIR> must be a directory containing an unpacked Debian source
19package. If I<SOURCEDIR> is omitted, the current directory is assumed.
20
21=head1 OUTPUT DIRECTORY
22
23At the very end of a build, B<debrepro> will inform the location of the
24output directory where the build artifacts can be found. In that
25directory, you will find:
26
27=over
28
29=item I<$OUTPUTDIR/first>
30
31Contains the results of the first build, including a copy of the source
32tree, and the resulting binary packages.
33
34=item I<$OUTPUTDIR/first/build.sh>
35
36Contains the exact build script that was used in the first build.
37
38=item I<$OUTPUTDIR/second>
39
40Contains the results of the second build, including a copy of the source tree,
41and the resulting binary packages.
42
43=item I<$OUTPUTDIR/second/build.sh>
44
45Contains the exact build script that was used in the second build.
46
47=back
48
49Taking a B<diff(1)> between I<$OUTPUTDIR/first/build.sh> and
50I<$OUTPUTDIR/second/build.sh> is an excellent way of figuring out
51exactly what changed between the two builds.
52
53=head1 SUPPORTED VARIATIONS
54
55=over
56
57=item B<user>
58
59The I<$USER> environment variable will contain different values between the
60first and second builds.
61
62=item B<path>
63
64During the second build, a fake, non-existing directory will be appended to the
65I<$PATH> environment variable.
66
67=item B<umask>
68
69The builds will use different umask settings.
70
71=item B<locale>
72
73Both I<$LC_ALL> and I<$LANG> will be different across the two builds.
74
75=item B<timezone>
76
77I<$TZ> will be different across builds.
78
79=item B<filesystem-ordering>
80
81If B<disorderfs> is installed, both builds will be done under a disorderfs
82overlay directory. This will cause filesystem listing operations to be return
83items in a non-deterministic order.
84
85=item B<time>
86
87The second build will be executed 213 days, 7 hours and 13 minutes in the
88future with regards to the current time (using B<faketime(1)>).
89
90=back
91
92=head1 OPTIONS
93
94=over
95
96=item -s VARIATION, --skip VARIATION
97
98Don't perform the named VARIATION. Variation names are the ones used in
99their description in section B<SUPPORTED VARIATIONS>.
100
101=item -b COMMAND, --before-second-build COMMAND
102
103Run COMMAND before performing the second build. This can be used for
104example to apply a patch to a source tree for the second build, and
105check whether (or how) the resulting binaries are affected.
106
107Examples:
108
109  $ debrepro --before-second-build "git checkout branch-with-changes"
110
111  $ debrepro --before-second-build "patch -p1 < /path/to/patch"
112
113=item -t TIME, --timeout TIME
114
115Apply a timeout to all builds. I<TIME> must be a time specification
116compatible with GNU timeout(1).
117
118
119=item -h, --help
120
121Display this help message and exit.
122
123=back
124
125=head1 EXIT STATUS
126
127=over
128
129=item 0Z<>
130
131Package is reproducible.
132
133Reproducible here means that the two builds produced the exactly the
134same binaries, under the set of variations that B<debrepro> tests. Other
135sources of non-determinism in builds that are not yet tested might still
136affect builds in the wild.
137
138=item 1Z<>
139
140Package is not reproducible.
141
142=item 2Z<>
143
144The given input is not a valid Debian source package.
145
146=item 3Z<>
147
148Required programs are missing.
149
150=back
151
152=head1 SEE ALSO
153
154diffoscope (1), disorderfs (1), timeout(1)
155
156=head1  AUTHOR
157
158Antonio Terceiro <terceiro@debian.org>.
159