From: Wayne Davison Date: Fri, 24 Jul 2020 00:29:13 +0000 (-0700) Subject: Add packages to INSTALL.md; put INSTALL.md on ftp site X-Git-Tag: v3.2.3pre1~37 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=e00662f2637ccf81e5d4b36feeebb8a1b3ec65e8;p=thirdparty%2Frsync.git Add packages to INSTALL.md; put INSTALL.md on ftp site --- diff --git a/INSTALL.md b/INSTALL.md index a504fb78..dc0b3be9 100644 --- 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. - 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 d1a3f590..08779e4f 100755 --- 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 ])