[reprotest] 02/03: Add a hacky man page using rst2man and help2man
Ximin Luo
infinity0 at debian.org
Tue Jan 24 20:26:44 UTC 2017
This is an automated email from the git hooks/post-receive script.
infinity0 pushed a commit to branch master
in repository reprotest.
commit e73783f2bf3f466581e13256e08de9a762dbc3d8
Author: Ximin Luo <infinity0 at debian.org>
Date: Tue Jan 24 21:21:22 2017 +0100
Add a hacky man page using rst2man and help2man
---
.gitignore | 2 +
MANIFEST.in | 2 +-
README.md => README.rst | 165 ++++++++++++++++++++++++++--------------------
TODO | 3 +-
debian/changelog | 1 +
debian/control | 17 +++--
debian/reprotest.docs | 2 +-
debian/reprotest.manpages | 1 +
debian/rules | 4 ++
doc/Makefile | 16 +++++
doc/reprotest | 4 ++
doc/reprotest.h2m.0 | 24 +++++++
reprotest/__init__.py | 12 +++-
setup.cfg | 2 +-
setup.py | 2 +-
15 files changed, 172 insertions(+), 85 deletions(-)
diff --git a/.gitignore b/.gitignore
index 9c82c34..7dc1035 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,5 @@ __pycache__
/.coverage.*
/.cache
/.tox
+/doc/reprotest.1
+/doc/reprotest.h2m
diff --git a/MANIFEST.in b/MANIFEST.in
index 0544523..4d1668f 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,2 +1,2 @@
-include README.md
+include README.rst
include reprotest/virt/*
diff --git a/README.md b/README.rst
similarity index 52%
rename from README.md
rename to README.rst
index 96962cc..5eb24e0 100644
--- a/README.md
+++ b/README.rst
@@ -1,8 +1,10 @@
-Command Line Interface
-======================
+Command-line examples
+=====================
The easiest way to run reprotest is via our presets:
+::
+
# Build the current directory in a null server (/tmp)
reprotest auto .
reprotest auto . -- null -d # for more verbose output
@@ -11,58 +13,68 @@ The easiest way to run reprotest is via our presets:
# See https://wiki.debian.org/sbuild for instructions on setting that up.
reprotest auto reprotest_0.3.3.dsc -- schroot unstable-amd64-sbuild
-Currently, we only support this for Debian packages, but are keen on adding
-more. If we don't 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.
+Currently, we only support this for Debian packages, but are keen on
+adding more. If we don't 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.
+
+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:
-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:
+::
reprotest 'python3 setup.py bdist' 'dist/*.tar.gz'
When using this from a shell:
-If the build command has spaces, you will need to quote them, e.g. `reprotest
-"debuild -b -uc -us" [..]`.
+If the build command has spaces, you will need to quote them, e.g.
+``reprotest "debuild -b -uc -us" [..]``.
-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. `reprotest [..]
-"*.tar.gz *.tar.xz"`.
+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.
+``reprotest [..] "*.tar.gz *.tar.xz"``.
-If your build artifacts have spaces in their names, you will need to quote
-these twice, e.g. `'"a file with spaces.gz"'` for a single artifact or `'"dir
-1"/* "dir 2"/*'` for multiple patterns.
+If your build artifacts have spaces in their names, you will need to
+quote these twice, e.g. ``'"a file with spaces.gz"'`` for a single
+artifact or ``'"dir 1"/* "dir 2"/*'`` for multiple patterns.
-To get more help for the CLI, including documentation on optional arguments and
-what they do, run:
+To get more help for the CLI, including documentation on optional
+arguments and what they do, run:
- reprotest --help
+::
+ reprotest --help
Running in a virtual server
===========================
-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:
+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:
+
+::
reprotest 'python3 setup.py bdist_wheel' 'dist/*.whl' qemu /path/to/qemu.img
reprotest 'debuild -b -uc -us' '../*.deb' schroot unstable-amd64
-There are different server types available. See `--help` for a list of them,
-which appears near the top, in the "virtual_server_args" part of the
-"positional arguments" section.
+There are different server types available. See ``--help`` for a list of
+them, which appears near the top, in the "virtual\_server\_args" part of
+the "positional arguments" section.
+
+For each virtual server (e.g. "schroot"), you see which extra arguments
+it supports:
-For each virtual server (e.g. "schroot"), you see which extra arguments it
-supports:
+::
reprotest --help schroot
-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:
+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:
+
+::
# "Debian directory" preset
reprotest auto . -- schroot unstable-amd64-sbuild
@@ -77,44 +89,47 @@ would look like, if we ran it via the advanced CLI:
-- \
schroot unstable-amd64-sbuild
-The `--testbed-init` 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.
+The ``--testbed-init`` 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.
-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).
+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).
-Then, we have the artifact pattern. For reproducibility, we're only interested
-in the binary packages.
+Then, we have the artifact pattern. For reproducibility, we're only
+interested in the binary packages.
-Finally, we specify that this is to take place in the "schroot" virtual_server
-with arguments "unstable-amd64-sbuild".
-
-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.
+Finally, we specify that this is to take place in the "schroot"
+virtual\_server with arguments "unstable-amd64-sbuild".
+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.
Config File
===========
-You can also give options to reprotest via a config file. This is a time-saving
-measure similar to `auto` 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.)
+You can also give options to reprotest via a config file. This is a
+time-saving measure similar to ``auto`` 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.)
-The config file has one section, basics, and the same options as the CLI,
-except there's no `dont_vary` option, and there are `build_command` and
-`artifact` fields. If `build_command` and/or `artifact` 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.
+The config file has one section, basics, and the same options as the
+CLI, except there's no ``dont_vary`` option, and there are
+``build_command`` and ``artifact`` fields. If ``build_command`` and/or
+``artifact`` 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.
-Reprotest by default loads `./.reprotestrc`, or you can tell it to load another
-file with the `--config-file` command line option.
+Reprotest by default loads ``./.reprotestrc``, or you can tell it to
+load another file with the ``--config-file`` command line option.
A sample config file is below.
+::
+
[basics]
build_command = setup.py sdist
artifact = dist/reprotest-0.2.tar.gz
@@ -130,26 +145,28 @@ A sample config file is below.
timezone
umask
-
Running the Tests
=================
-Tests are run with [Tox](https://pypi.python.org/pypi/tox),
-[pytest](https://pypi.python.org/pypi/pytest) and
-[Coverage](https://pypi.python.org/pypi/coverage). On Debian, this can be done
-with `apt-get install python3-coverage python3-pytest tox`.
+Tests are run with `Tox <https://pypi.python.org/pypi/tox>`__,
+`pytest <https://pypi.python.org/pypi/pytest>`__ and
+`Coverage <https://pypi.python.org/pypi/coverage>`__. On Debian, this
+can be done with
+``apt-get install python3-coverage python3-pytest tox``.
-To run the tests, go to the root of the repository, where `tox.ini` is and run
-`tox`. For more verbose output, run `tox -- -s`.
+To run the tests, go to the root of the repository, where ``tox.ini`` is
+and run ``tox``. For more verbose output, run ``tox -- -s``.
This runs the tests with no virtualization. To test that reprotest works
-correctly with virtualization, you'll need to setup the virtualization servers
-schroot and qemu.
+correctly with virtualization, you'll need to setup the virtualization
+servers schroot and qemu.
+
+Some of the following instructions rely on Debian utilities. For
+schroot, run ``mk-sbuild --debootstrap-include=devscripts stable``. (If
+you aren't on ``amd64``, you'll have to include ``--arch``.) For qemu,
+first ``apt-get install autopkgtest vmdebootstrap qemu``, then run:
-Some of the following instructions rely on Debian utilities. For schroot, run
-`mk-sbuild --debootstrap-include=devscripts stable`. (If you aren't on
-`amd64`, you'll have to include `--arch`.) For qemu, first `apt-get install
-autopkgtest vmdebootstrap qemu`, then run:
+::
vmdebootstrap --verbose --serial-console --distribution=sid \
--customize=/usr/share/autopkgtest/setup-commands/setup-testbed \
@@ -158,18 +175,22 @@ autopkgtest vmdebootstrap qemu`, then run:
rm adt-sid.raw
The last two commands reduce the size of the image but aren't strictly
-necessary. Move `adt-sid.img` to `linux/` under your home directory.
+necessary. Move ``adt-sid.img`` to ``linux/`` under your home directory.
To log into the schroot and qemu containers, respectively, run:
+::
+
sudo schroot -c source:stable-amd64
qemu-system-x86_64 -enable-kvm -drive file=~/linux/adt-sid.img,if=virtio \
-net user -net nic,model=virtio -m 1024
-After replacing `~` with your home directory.
+After replacing ``~`` with your home directory.
For the host system and the two containers, run:
+::
+
apt-get install disorderfs
(Additionally for mk-sbuild stable, enable the backports repository.)
(Additionally for chroot, run:
@@ -179,4 +200,6 @@ For the host system and the two containers, run:
Now, finally run the tests:
+::
+
REPROTEST_TEST_SERVERS=null,qemu,schroot tox -- -s
diff --git a/TODO b/TODO
index 27b1b55..a646a7c 100644
--- a/TODO
+++ b/TODO
@@ -1,2 +1,3 @@
-- reprotest man page
+- better logging messages
+ - in particular, tell the user that all of ./ is getting copied into /tmp, etc
- make mock_build capture more stuff and test it in tests.py:test_variations
diff --git a/debian/changelog b/debian/changelog
index 08cae0f..46a8d55 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -7,6 +7,7 @@ reprotest (0.6) UNRELEASED; urgency=medium
path -> exec_path, to distinguish it from build_path
faketime -> time, since users care about interface not implementation
* Add a --config-file option and fix the loading of configs.
+ * Add a man page. (Closes: #833282)
-- Ximin Luo <infinity0 at debian.org> Sat, 07 Jan 2017 17:15:42 +0100
diff --git a/debian/control b/debian/control
index b0572c4..21237dd 100644
--- a/debian/control
+++ b/debian/control
@@ -9,6 +9,8 @@ Build-Depends: debhelper (>= 9.20141010),
dh-python,
python3-all,
python3-setuptools,
+ help2man <!nodoc>,
+ python3-docutils <!nodoc>,
# tests.py uses debuild from devscripts, which itself uses lintian
devscripts <!nocheck>,
diffoscope <!nocheck>,
@@ -38,10 +40,13 @@ Depends: ${python3:Depends},
Recommends: diffutils | diffoscope, disorderfs, locales-all, faketime
Suggests: autodep8, schroot, qemu-system, qemu-utils
Description: Build software and check it for reproducibility.
- reprotest builds the same source code in different environments and
- then checks the binaries produced by the builds to see if changing
- the environment, without changing the source code, changed the
- generated binaries.
+ 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 diffoscope (or if unavailable then diff) is used to display them
+ in detail for later analysis.
.
- reprotest is developed as part of the “reproducible builds” Debian
- project.
+ It supports different types of environment such as a "null" environment (i.e.
+ doing the builds directly in /tmp) or various other virtual servers, for
+ example schroot, ssh, qemu, and several others.
+ .
+ reprotest is developed as part of the “reproducible builds” Debian project.
diff --git a/debian/reprotest.docs b/debian/reprotest.docs
index b43bf86..a1320b1 100644
--- a/debian/reprotest.docs
+++ b/debian/reprotest.docs
@@ -1 +1 @@
-README.md
+README.rst
diff --git a/debian/reprotest.manpages b/debian/reprotest.manpages
new file mode 100644
index 0000000..a8a5f13
--- /dev/null
+++ b/debian/reprotest.manpages
@@ -0,0 +1 @@
+doc/reprotest.1
diff --git a/debian/rules b/debian/rules
index 9be53dd..ec5dc21 100755
--- a/debian/rules
+++ b/debian/rules
@@ -14,6 +14,10 @@ override_dh_auto_configure:
test $$(python3 setup.py --version) = $$(dpkg-parsechangelog -SVersion)
dh_auto_configure
+override_dh_auto_build:
+ dh_auto_build
+ cd doc && $(MAKE)
+
override_dh_auto_test:
ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS)))
VIRTUALENV_DOWNLOAD=no \
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100755
index 0000000..7dd1da5
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,16 @@
+#!/usr/bin/make -f
+
+VERSION = $$(cd .. && python3 setup.py -V)
+
+SED_rm_python_usage_msg = -e '/end_of_description_header/,/positional arguments/{d}'
+SED_fix_rst2man_quirks = -e 's,^ \\- ,,' -e 's,^\[,\\[char91],g'
+
+reprotest.1: reprotest.h2m ../reprotest/__init__.py
+ help2man --version-string=$(VERSION) ./reprotest -N --include="$<" | \
+ sed $(SED_rm_python_usage_msg) > "$@"
+
+reprotest.h2m: reprotest.h2m.0 ../README.rst Makefile
+ { cat reprotest.h2m.0; cat ../README.rst | \
+ rst2man --no-doc-title | \
+ sed $(SED_fix_rst2man_quirks) \
+ -e 's,\.SH \(.*\),[\1],g'; } > "$@"
diff --git a/doc/reprotest b/doc/reprotest
new file mode 100755
index 0000000..25d06d5
--- /dev/null
+++ b/doc/reprotest
@@ -0,0 +1,4 @@
+#!/bin/sh
+# dummy program wrapper for help2man
+cd ..
+exec python3 -m reprotest "$@"
diff --git a/doc/reprotest.h2m.0 b/doc/reprotest.h2m.0
new file mode 100644
index 0000000..a01e2e5
--- /dev/null
+++ b/doc/reprotest.h2m.0
@@ -0,0 +1,24 @@
+[NAME]
+reprotest \- Build packages and check them for reproducibility.
+[SYNOPSIS]
+.nf
+\fBreprotest\fR \-\-help\ [<virtual_server_name>]
+\fBreprotest\fR [options] \fIauto\fR <source_file_or_dir> [[more options] --|--] \
+[<virtual_server_args> [<virtual_server_args> ...]]
+\fBreprotest\fR [options] <build_command> <artifact> [[more options] --|--] \
+[<virtual_server_args> [<virtual_server_args> ...]]
+.fi
+[<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:
+.\" end_of_description_header
diff --git a/reprotest/__init__.py b/reprotest/__init__.py
index 23022a0..416e910 100644
--- a/reprotest/__init__.py
+++ b/reprotest/__init__.py
@@ -499,9 +499,9 @@ def check(build_command, artifact_pattern, virtual_server_args, source_root,
COMMAND_LINE_OPTIONS = types.MappingProxyType(collections.OrderedDict([
('build_command', types.MappingProxyType({
'default': None, 'nargs': '?', # 'type': str.split
- 'help': 'Build command to execute, or "auto" to guess this - in '
- 'the latter case then the subsequent argument will not be '
- 'interpreted as an artifact but rather as the source to build, '
+ 'help': '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.'})),
('artifact', types.MappingProxyType({
'default': None, 'nargs': '?',
@@ -609,6 +609,12 @@ def config(filename):
def command_line(*argv):
arg_parser = argparse.ArgumentParser(
+ prog='reprotest',
+ usage='''%(prog)s --help [<virtual_server_name>]
+ %(prog)s [options] auto <source_file_or_dir> [[more options] --|--]
+ [<virtual_server_args> [<virtual_server_args> ...]]
+ %(prog)s [options] <build_command> <artifact> [[more options] --|--]
+ [<virtual_server_args> [<virtual_server_args> ...]]''',
description='Build packages and check them for reproducibility.',
formatter_class=argparse.RawDescriptionHelpFormatter, add_help=False)
for option in COMMAND_LINE_OPTIONS:
diff --git a/setup.cfg b/setup.cfg
index b88034e..5aef279 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,2 +1,2 @@
[metadata]
-description-file = README.md
+description-file = README.rst
diff --git a/setup.py b/setup.py
index c92843b..9a653a0 100644
--- a/setup.py
+++ b/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup, find_packages
setup(name='reprotest',
version='0.6',
description='Build packages and check them for reproducibility.',
- long_description=open('README.md', encoding='utf-8').read(),
+ long_description=open('README.rst', encoding='utf-8').read(),
author='Ceridwen',
author_email='ceridwenv at gmail.com',
license='GPL-3+',
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/reproducible/reprotest.git
More information about the Reproducible-commits
mailing list