= Installation instructions =

== Quick recipe for systems using apt ==

---------------------------------------------------------------------
make fullinstall              # Install prerequisites and build
make check                    # Run the tests
---------------------------------------------------------------------

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.

== Prerequisites ==

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 to format the documentation.  The Makefile
will silently refrain from doing this if you don't have it 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.

== Building the software from the repository ==

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.

== Testing the software ==

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.

== Notes to packagers ==

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.

// end
