Add packages to INSTALL.md; put INSTALL.md on ftp site

diff --git a/INSTALL.md b/INSTALL.md
index a504fb78d13700142d18c6f3417d52f03f330828..dc0b3be9058ba038755804da98f927182d3fd812 100644 (file)
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,13 +1,123 @@
-To build and install rsync:
+# How to build and install rsync
 
-    $ ./configure
-    $ make
-    # make install
+When building rsync, you'll want to install various libraries in order to get
+all the new features enabled.  The configure script will alert you when the
+newest libraries are missing and tell you the appropriate `--disable-LIB`
+option to use if you want to just skip that feature.  What follows are various
+support libraries that you may want to install to build rsync with the maximum
+features (the impatient can skip down to the package summary):
+
+## The basic setup
+
+You need to have a C compiler installed and optionally a C++ compiler in order
+to try to build some hardware-accelerated checksum routines.  If you're
+installing from the git repo (instead of a release tar file) you'll also need
+the GNU autotools (autoconf & automake) and your choice of 2 python3 markdown
+libraries: cmarkgfm or commonmark (needed to generate the man pages).
+
+If your OS doesn't provide a python3-cmarkgfm or python3-commonmark package,
+you can run the following to install the commonmark python library for your
+build user (after installing python3's pip package):
+
+>     pip3 install --user commonmark
+
+## ACL support
+
+To support copying ACL file information, make sure you have an acl
+development library installed. It also helps to have the helper programs
+installed to manipulate ACLs and to run the rsync testsuite.
+
+## Xattr support
+
+To support copying xattr file information, make sure you have an xattr
+development library installed. It also helps to have the helper programs
+installed to manipulate xattrs and to run the rsync testsuite.
+
+## xxhash
+
+The [xxHash library](https://cyan4973.github.io/xxHash/) provides extremely
+fast checksum functions that can make the "rsync algorithm" run much more
+quickly, especially when matching blocks in large files.  Installing this
+development library adds xxhash checksums as the default checksum algorithm.
+
+## zstd
+
+The [zstd library](http://facebook.github.io/zstd/) compression algorithm that
+uses a lot less CPU than the default zlib algorithm at the same compression
+level.  Note that you need at least version 1.4, so you might need to skip the
+zstd compression if you can only install a 1.3 release.  Installing this
+development library adds zstd compression as the default compression algorithm.
+
+## lz4
+
+The [lz4 library](https://lz4.github.io/lz4/) compression algorithm that uses
+very little CPU, though it also has the smallest compression ratio of other
+algorithms.  Installing this development library adds lz4 compression as an
+available compression algorithm.
+
+## openssl crypto
+
+The [openssl crypto library](https://www.openssl.org/docs/man1.0.2/man3/crypto.html)
+provides some hardware accelerated checksum algorithms for MD4 and MD5.
+Installing this development library makes rsync use the (potentially) faster
+checksum routines when computing MD4 & MD5 checksums.
+
+## Package summary
+
+To sum up, here are some package install commands for various OSes:
+
+ -  For Debian and Ubuntu (Debian Buster users may want to briefly(?) enable
+    buster-backports to update zstd from 1.3 to 1.4):
+
+    >     sudo apt install gcc g++ autoconf automake python3-cmarkgfm
+    >     sudo apt install acl libacl1-dev
+    >     sudo apt install attr libattr1-dev
+    >     sudo apt install libxxhash-dev
+    >     sudo apt install libzstd-dev
+    >     sudo apt install libzlz4-dev
+    >     sudo apt install libssl-dev
+
+ -  For CentOS (use EPEL for python3-pip):
+
+    >     sudo yum install epel-release
+    >     sudo yum install gcc g++ autoconf automake python3-pip
+    >     sudo yum install acl libacl-devel
+    >     sudo yum install attr libattr-devel
+    >     sudo yum install xxhash-devel
+    >     sudo yum install libzstd-devel
+    >     sudo yum install lz4-devel
+    >     sudo yum install openssl-devel
+    >     pip3 install --user commonmark
+
+ -  For FreeBSD (this assumes that the python3 version is 3.7):
+
+    >     sudo pkg install -y gcc g++ autotools python3
+    >     sudo pkg install -y xxhash
+    >     sudo pkg install -y zstd
+    >     sudo pkg install -y liblz4
+    >     sudo pkg install -y py37-CommonMark
+
+ -  For macOS:
+
+    >     brew install automake
+    >     brew install xxhash
+    >     brew install zstd
+    >     brew install lz4
+    >     brew install openssl
+
+## Build and install
+
+After installing the various libraries, you need to configure, build, and
+install the source:
+
+>      ./configure
+>      make
+>      sudo make install
 
 You may set the installation directory and other parameters by options
 to ./configure.  To see them, use:
 
-    $ ./configure --help
+>     ./configure --help
 
 Configure tries to figure out if the local system uses group "nobody" or
 "nogroup" by looking in the /etc/group file.  (This is only used for the
@@ -37,50 +147,46 @@ a "detached head" git position then you'll need to manually chdir into
 the build dir to run make.  I also like to create 2 more symlinks in the
 sourc dir:  ln -s build/rsync . ; ln -s build/testtmp .
 
-MAKE COMPATIBILITY
-------------------
+## Make compatibility
 
 Note that Makefile.in has a rule that uses a wildcard in a prerequisite.  If
 your make has a problem with this rule, you will see an error like this:
 
     Don't know how to make ./*.c
 
-You can change the "proto.h-tstamp" target in Makefile.in to list all the *.c
+You can change the "proto.h-tstamp" target in Makefile.in to list all the \*.c
 filenames explicitly in order to avoid this issue.
 
-RPM NOTES
----------
+## RPM notes
 
 Under packaging you will find .spec files for several distributions.
 The .spec file in packaging/lsb can be used for Linux systems that
 adhere to the Linux Standards Base (e.g., RedHat and others).
 
-HP-UX NOTES
------------
+## HP-UX notes
 
 The HP-UX 10.10 "bundled" C compiler seems not to be able to cope with
 ANSI C.  You may see this error message in config.log if ./configure
 fails:
 
-  (Bundled) cc: "configure", line 2162: error 1705: Function prototypes are an ANSI feature.
+    (Bundled) cc: "configure", line 2162: error 1705: Function prototypes are an ANSI feature.
 
 Install gcc or HP's "ANSI/C Compiler".
 
-MAC OSX NOTES
--------------
+## Mac OS X notes
 
 Some versions of Mac OS X (Darwin) seem to have an IPv6 stack, but do
-not completely implement the "New Sockets" API.  
+not completely implement the "New Sockets" API.
 
-<http://www.ipv6.org/impl/mac.html> says that Apple started to support
-IPv6 in 10.2 (Jaguar).  If your build fails, try again after running
+[This site](http://www.ipv6.org/impl/mac.html) says that Apple started to
+support IPv6 in 10.2 (Jaguar).  If your build fails, try again after running
 configure with --disable-ipv6.
 
-IBM AIX NOTES
--------------
+## IBM AIX notes
 
 IBM AIX has a largefile problem with mkstemp.  See IBM PR-51921.
-The workaround is to append the below to config.h
-       #ifdef _LARGE_FILES
-       #undef HAVE_SECURE_MKSTEMP
-       #endif
+The workaround is to append the following to config.h:
+
+>     #ifdef _LARGE_FILES
+>     #undef HAVE_SECURE_MKSTEMP
+>     #endif

diff --git a/packaging/release-rsync b/packaging/release-rsync
index d1a3f590d66dfb33debc6d66940921c08a9a41f5..08779e4f3da1e3bfbdccc0572c87c6c6a5da69a9 100755 (executable)
--- a/packaging/release-rsync
+++ b/packaging/release-rsync
@@ -324,7 +324,7 @@ About to:
     shutil.rmtree(rsync_ver)
 
     print(f"Updating the other files in {dest} ...")
-    md_files = 'README.md NEWS.md'.split()
+    md_files = 'README.md NEWS.md INSTALL.md'.split()
     html_files = [ fn for fn in gen_pathnames if fn.endswith('.html') ]
     cmd_chk(['rsync', '-a', *md_files, *html_files, dest])
     cmd_chk(["packaging/md2html"] + [ dest +'/'+ fn for fn in md_files ])