Installation instructions

We’ve had one report of a Go 1.14 build-toolchain failure with this diagnostic: "/bin/sh: -c: line 1: syntax error: unexpected end of file". Upgrading to 1.15 fixes it.

This code is developed under Linux and expected to work under any other Unix, including OS X. Full function has been confirmed under MS-Windows/WSL, but native MS-Windows is not supported.

You will want 64-bit hardware. While this code passes its tests on 32-bit machines, they have an address space too small to be useful for surgery on large repositories. (32-bit build is tested with "make GOOS=linux GOARCH=386".)

You will need git at version 2.19.2 or later. Versions of reposurgeon after 4.7 assume the --show-original-ids option of git-fast-export is available.

You will need the Go compiler at revision 1.12 or later. It is recommended that you run with the most recent version of the Go compiler, as point releases often have GC performance improvements that are significant on reposurgeon’s workload.

Note that if you install a non-default version of golang under Debian-derived Linuxes you may have to tweak your $PATH variable to make the Go tools visible. To avoid this, the golang-current production enables the official Go backports PPA. This will always install the most recent compiler version; the last line reports it. Note that if you do this, the stock version-numbered golang packages carried by your distribution need not be installed.

hg-git-fast-import is required if you want to write Mercurial repositories, but not to read them. Note that this is not part of stock Mercurial, but does a better job of handling odd cases than the stock 'hg-fastimport' plugin.

A few scripts are written in shell. Any Bourne-shell-like implementation will do. The restricted shell shipped on Debian/Ubuntu will work. Shell is almost certainly already installed on your system.

You will need asciidoctor, awkm and ruby to format the documentation. The Makefile will silently refrain from doing this if you don’t have asciidoctor installed.

The repotool mirror code needs rsync.

GNU make is required for the regression tests, but not for running the code. golint, shellcheck, mercurial, and cvs are required for the full regression tests; only a subset of the tests will be run in their absence. The cvs-fast-export and Subversion svnadmin importer are also required for testing. Very old versions of Subversion (certainly 1.6 or earlier, but not 1.9 or later) will cause one spurious test failure.

gnuplot is only required if you’re planning to try performance-tuning with repobench.

To build the tools after cloning the repository, simply run "make" in the toplevel directory. This also builds the suite documentation if you have asciidoctor installed.

There is an extensive regression-test suite in the test/ directory. To test the correctness of this software once its prerequisites are installed, invoke make check in the main directory.

You’ll need openssh-server or equivalent for the repotool tests to work; they use rsync.

The package should recommend CVS and Subversion, though not require them.

It probably is not necessary to package repobench, as it is a benchmarking tool only of interest to developers working with the source distribution.

The scripts in contrib/ are unstable, undocumented, and should not be packaged.