.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.4. .TH REPROTEST "1" "May 2017" "reprotest 0.6.2" "User Commands" .SH NAME reprotest \- Build packages and check them for reproducibility. . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH SYNOPSIS .nf \fBreprotest\fR \-\-help\ [] \fBreprotest\fR [options] \fIauto\fR [[more options] --|--] \ [ [ ...]] \fBreprotest\fR [options] [[more options] --|--] \ [ [ ...]] .fi .SH DESCRIPTION .B reprotest builds the same source code twice in different environments, and then checks the binaries produced by each build for differences. If any are found, then \fBdiffoscope\fR(1) (or if unavailable then \fBdiff\fR(1)) is used to display them in detail for later analysis. .sp See the \fBCOMMAND-LINE EXAMPLES\fR section further below to get you started, as well as more detailed explanations of all the command-line options. The same information is also available in \fI/usr/share/doc/reprotest/README.rst\fR or similar. .\" the below hack gets rid of the python "usage" message in favour of the above .SS positional arguments: .TP build_command Build command to execute, or "auto" to guess this. In the latter case, the next argument 'artifact' will not be interpreted that way but instead as the source to build, e.g. "." or some other path. .TP artifact Build artifact to test for reproducibility. May be a shell pattern such as "*.deb *.changes". .TP virtual_server_args Arguments to pass to the virtual_server, the first argument being the name of the server. If this itself contains options (of the form \fB\-xxx\fR or \fB\-\-xxx\fR), you should put a "\-\-" between these arguments and reprotest's own options. Default: "null", to run directly in \fI\,/tmp\/\fP. Choices: chroot, lxc, lxd, null, qemu, schroot, ssh .SS "optional arguments:" .TP \fB\-\-help\fR [VIRTUAL_SERVER_NAME] Show this help message and exit. When given an argument, show instead the help message for that virtual server and exit. .TP \fB\-\-verbosity\fR VERBOSITY An integer. Control which messages are displayed. .TP \fB\-\-config\-file\fR CONFIG_FILE File to load configuration from. (Default: \&.reprotestrc) .TP \fB\-\-source\-root\fR SOURCE_ROOT Root of the source tree, if not the current working directory. .TP \fB\-\-store\-dir\fR STORE_DIR Save the artifacts in this directory, which must be empty or non\-existent. Otherwise, the artifacts will be deleted and you only see their hashes (if reproducible) or the diff output (if not). .TP \fB\-\-testbed\-pre\fR COMMANDS Shell commands to run before starting the test bed, in the context of the current system environment. This may be used to e.g. compute information needed by the build, where the computation needs packages you don't want installed in the testbed itself. .TP \fB\-\-testbed\-init\fR COMMANDS Shell commands to run after starting the test bed, but before applying variations. Used to e.g. install disorderfs in a chroot. .TP \fB\-\-auto\-preset\-expr\fR PYTHON_EXPRESSION This may be used to transform the presets returned by the auto\-detection feature. The value should be a python expression that transforms the _ variable, which is of type reprotest.presets.ReprotestPreset. See that class's documentation for ways you can write this expression. Default: _ .TP \fB\-\-variations\fR VARIATIONS Build variations to test as a comma\-separated list (without spaces). Default is to test all available variations: environment, build_path, fileordering, home, kernel, locales, exec_path, time, timezone, umask. .TP \fB\-\-dont\-vary\fR DONT_VARY Build variations *not* to test as a comma\-separated list (without spaces). These take precedence over what you set for "variations". Default is nothing, i.e. test whatever you set for "variations". .TP \fB\-\-diffoscope\-arg\fR DIFFOSCOPE_ARG Give extra arguments to diffoscope when running it. .TP \fB\-\-no\-diffoscope\fR Don't run diffoscope; instead run diff(1). Useful if you don't want to install diffoscope and/or just want a quick answer on whether the reproduction was successful or not, without spending time to compute all the detailed differences. .TP \fB\-\-no\-clean\-on\-error\fR Don't clean the virtual_server if there was an error. Useful for debugging, but WARNING: this is currently not implemented very well and may leave cruft on your system. .SH "COMMAND-LINE EXAMPLES" .sp The easiest way to run reprotest is via our presets: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Build the current directory in a null server (/tmp) $ reprotest auto . $ reprotest auto . \-\- null \-d # for more verbose output # Build the given Debian source package in an schroot # See https://wiki.debian.org/sbuild for instructions on setting that up. $ reprotest auto reprotest_0.3.3.dsc \-\- schroot unstable\-amd64\-sbuild .ft P .fi .UNINDENT .UNINDENT .sp Currently, we only support this for Debian packages, but are keen on adding more. If we don\(aqt have knowledge on how to build your file or directory, you can send a patch to us on adding this intelligence \- see the reprotest.presets python module, and adapt the existing logic. .sp In the meantime, you can use the more advanced CLI to build arbitrary things. This takes two mandatory arguments, the build command to run and the build artifact file/pattern to test after running the build. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ reprotest \(aqpython3 setup.py bdist\(aq \(aqdist/*.tar.gz\(aq .ft P .fi .UNINDENT .UNINDENT .sp When using this from a shell: .sp If the build command has spaces, you will need to quote them, e.g. \fBreprotest "debuild \-b \-uc \-us" [..]\fP\&. .sp If you want to use several build artifact patterns, or if you want to use shell wildcards as a pattern, you will also need to quote them, e.g. \fBreprotest [..] "*.tar.gz *.tar.xz"\fP\&. .sp If your build artifacts have spaces in their names, you will need to quote these twice, e.g. \fB\(aq"a file with spaces.gz"\(aq\fP for a single artifact or \fB\(aq"dir 1"/* "dir 2"/*\(aq\fP for multiple patterns. .sp To get more help for the CLI, including documentation on optional arguments and what they do, run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ reprotest \-\-help .ft P .fi .UNINDENT .UNINDENT .SH "RUNNING IN A VIRTUAL SERVER" .sp You can also run the build inside what is called a "virtual server". This could be a container, a chroot, etc. You run them like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ reprotest \(aqpython3 setup.py bdist_wheel\(aq \(aqdist/*.whl\(aq qemu /path/to/qemu.img $ reprotest \(aqdebuild \-b \-uc \-us\(aq \(aq../*.deb\(aq schroot unstable\-amd64 .ft P .fi .UNINDENT .UNINDENT .sp There are different server types available. See \fB\-\-help\fP for a list of them, which appears near the top, in the "virtual_server_args" part of the "positional arguments" section. .sp For each virtual server (e.g. "schroot"), you see which extra arguments it supports: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ reprotest \-\-help schroot .ft P .fi .UNINDENT .UNINDENT .sp When running builds inside a virtual server, you will probably have to give extra commands, in order to set up your build dependencies inside the virtual server. For example, to take you through what the "Debian directory" preset would look like, if we ran it via the advanced CLI: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # "Debian directory" preset $ reprotest auto . \-\- schroot unstable\-amd64\-sbuild # In the advanced CLI, this is equivalent to roughly: $ reprotest \e \-\-testbed\-init \(aqapt\-get \-y \-\-no\-install\-recommends install \e util\-linux disorderfs 2>/dev/null; \e test \-c /dev/fuse || mknod \-m 666 /dev/fuse c 10 229\(aq \e \(aqPATH=/sbin:/usr/sbin:$PATH apt\-get \-y \-\-no\-install\-recommends build\-dep ./; \e dpkg\-buildpackage \-uc \-us \-b\(aq \e \(aq../*.deb\(aq \e \-\- \e schroot unstable\-amd64\-sbuild .ft P .fi .UNINDENT .UNINDENT .sp The \fB\-\-testbed\-init\fP argument is needed to set up basic tools, which reprotest needs in order to make the variations in the first place. This should be the same regardless of what package is being built, but might differ depending on what virtual_server is being used. .sp Next, we have the build_command. For our Debian directory, we install build\-dependencies using apt\-get, then we run the actual build command itself using dpkg\-buildpackage(1). .sp Then, we have the artifact pattern. For reproducibility, we\(aqre only interested in the binary packages. .sp Finally, we specify that this is to take place in the "schroot" virtual_server with arguments "unstable\-amd64\-sbuild". .sp Of course, all of this is a burden to remember, if you must run the same thing many times. So that is why adding new presets for new files would be good. .sp Here is a more complex example. It tells reprotest to store the build products into \fB\&./artifacts\fP to analyse later; and also tweaks the "Debian dsc" preset so that it uses our \fI\%experimental toolchain\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ reprotest \-\-store\-dir=artifacts \e \-\-auto\-preset\-expr \(aq_.prepend.testbed_init("apt\-get install \-y wget 2>/dev/null; \e echo deb http://reproducible.alioth.debian.org/debian/ ./ >> /etc/apt/sources.list; \e wget \-q \-O\- https://reproducible.alioth.debian.org/reproducible.asc | apt\-key add \-; \e apt\-get update; apt\-get upgrade \-y 2>/dev/null; ")\(aq \e auto ./bash_4.4\-4.0~reproducible1.dsc \e \-\- \e schroot unstable\-amd64\-sbuild .ft P .fi .UNINDENT .UNINDENT .sp (Yes, this could be a lot nicer to achieve; we\(aqre working on it.) .SH "CONFIG FILE" .sp You can also give options to reprotest via a config file. This is a time\-saving measure similar to \fBauto\fP presets; the difference is that these are more suited for local builds that are suited to your personal purposes. (You may use both presets and config files in the same build.) .sp The config file has one section, basics, and the same options as the CLI, except there\(aqs no \fBdont_vary\fP option, and there are \fBbuild_command\fP and \fBartifact\fP fields. If \fBbuild_command\fP and/or \fBartifact\fP are set in the config file, reprotest can be run without passing those as command\-line arguments. Command\-line arguments always override config file options. .sp Reprotest by default loads \fB\&./.reprotestrc\fP, or you can tell it to load another file with the \fB\-\-config\-file\fP command line option. .sp A sample config file is below. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \[char91]basics] build_command = setup.py sdist artifact = dist/reprotest\-0.2.tar.gz source_root = reprotest/ variations = environment build_path home kernel locales exec_path time timezone umask .ft P .fi .UNINDENT .UNINDENT .SH "KNOWN BUGS" .sp The "time" variation uses \fBfaketime\fP which \fIsometimes\fP causes weird and hard\-to\-diagnose problems. In the past, this has included: .INDENT 0.0 .IP \(bu 2 builds taking an infinite amount of time; though this should be fixed in recent versions of reprotest. .IP \(bu 2 builds with implausibly huge differences caused by ./configure scripts producing different results with and without faketime. This still affects bash and probably certain other packages using autotools. .UNINDENT .sp If you see a difference that you really think should not be there, try passing \fB\-\-dont\-vary time\fP to reprotest, and/or check our results on \fI\%https://tests.reproducible\-builds.org/\fP which use a different (more reliable) mechanism to vary the system time. .\" Generated by docutils manpage writer. .