Annotation of embedaddon/rsync/INSTALL.md, revision 1.1
1.1 ! misho 1: # How to build and install rsync
! 2:
! 3: When building rsync, you'll want to install various libraries in order to get
! 4: all the features enabled. The configure script will alert you when the
! 5: newest libraries are missing and tell you the appropriate `--disable-LIB`
! 6: option to use if you want to just skip that feature. What follows are various
! 7: support libraries that you may want to install to build rsync with the maximum
! 8: features (the impatient can skip down to the package summary):
! 9:
! 10: ## The basic setup
! 11:
! 12: You need to have a C compiler installed and optionally a C++ compiler in order
! 13: to try to build some hardware-accelerated checksum routines. Rsync also needs
! 14: a modern awk, which might be provided via gawk or nawk on some OSes.
! 15:
! 16: ## Autoconf & man pages
! 17:
! 18: If you're installing from the git repo (instead of a release tar file) you'll
! 19: also need the GNU autotools (autoconf & automake) and your choice of 2 python3
! 20: markdown libraries: cmarkgfm or commonmark (needed to generate the man pages).
! 21: If your OS doesn't provide a python3-cmarkgfm or python3-commonmark package,
! 22: you can run the following to install the commonmark python library for your
! 23: build user (after installing python3's pip package):
! 24:
! 25: > pip3 install --user commonmark
! 26:
! 27: You can test if you've got it fixed by running (from the src dir):
! 28:
! 29: > ./md2man --test rsync-ssl.1.md
! 30:
! 31: Alternately, you can avoid generating the man pages by fetching the very latest
! 32: versions (that match the latest git source) from the [generated-files][6] dir.
! 33: One way to do that is to run:
! 34:
! 35: > ./prepare-source fetchgen
! 36:
! 37: [6]: https://download.samba.org/pub/rsync/generated-files/
! 38:
! 39: ## ACL support
! 40:
! 41: To support copying ACL file information, make sure you have an acl
! 42: development library installed. It also helps to have the helper programs
! 43: installed to manipulate ACLs and to run the rsync testsuite.
! 44:
! 45: ## Xattr support
! 46:
! 47: To support copying xattr file information, make sure you have an attr
! 48: development library installed. It also helps to have the helper programs
! 49: installed to manipulate xattrs and to run the rsync testsuite.
! 50:
! 51: ## xxhash
! 52:
! 53: The [xxHash library][1] provides extremely fast checksum functions that can
! 54: make the "rsync algorithm" run much more quickly, especially when matching
! 55: blocks in large files. Installing this development library adds xxhash
! 56: checksums as the default checksum algorithm.
! 57:
! 58: [1]: https://cyan4973.github.io/xxHash/
! 59:
! 60: ## zstd
! 61:
! 62: The [zstd library][2] compression algorithm that uses less CPU than
! 63: the default zlib algorithm at the same compression level. Note that you
! 64: need at least version 1.4, so you might need to skip the zstd compression if
! 65: you can only install a 1.3 release. Installing this development library
! 66: adds zstd compression as the default compression algorithm.
! 67:
! 68: [2]: http://facebook.github.io/zstd/
! 69:
! 70: ## lz4
! 71:
! 72: The [lz4 library][3] compression algorithm that uses very little CPU, though
! 73: it also has the smallest compression ratio of other algorithms. Installing
! 74: this development library adds lz4 compression as an available compression
! 75: algorithm.
! 76:
! 77: [3]: https://lz4.github.io/lz4/
! 78:
! 79: ## openssl crypto
! 80:
! 81: The [openssl crypto library][4] provides some hardware accelerated checksum
! 82: algorithms for MD4 and MD5. Installing this development library makes rsync
! 83: use the (potentially) faster checksum routines when computing MD4 & MD5
! 84: checksums.
! 85:
! 86: [4]: https://www.openssl.org/docs/man1.0.2/man3/crypto.html
! 87:
! 88: ## Package summary
! 89:
! 90: To help you get the libraries installed, here are some package install commands
! 91: for various OSes. The commands are split up to correspond with the above
! 92: items, but feel free to combine the package names into a single install, if you
! 93: like.
! 94:
! 95: - For Debian and Ubuntu (Debian Buster users may want to briefly(?) enable
! 96: buster-backports to update zstd from 1.3 to 1.4):
! 97:
! 98: > sudo apt install -y gcc g++ gawk autoconf automake python3-cmarkgfm
! 99: > sudo apt install -y acl libacl1-dev
! 100: > sudo apt install -y attr libattr1-dev
! 101: > sudo apt install -y libxxhash-dev
! 102: > sudo apt install -y libzstd-dev
! 103: > sudo apt install -y libzlz4-dev
! 104: > sudo apt install -y libssl-dev
! 105:
! 106: - For CentOS (use EPEL for python3-pip):
! 107:
! 108: > sudo yum -y install epel-release
! 109: > sudo yum -y install gcc g++ gawk autoconf automake python3-pip
! 110: > sudo yum -y install acl libacl-devel
! 111: > sudo yum -y install attr libattr-devel
! 112: > sudo yum -y install xxhash-devel
! 113: > sudo yum -y install libzstd-devel
! 114: > sudo yum -y install lz4-devel
! 115: > sudo yum -y install openssl-devel
! 116: > pip3 install --user commonmark
! 117:
! 118: - For Fedora 33:
! 119:
! 120: > sudo dnf -y install acl libacl-devel
! 121: > sudo dnf -y install attr libattr-devel
! 122: > sudo dnf -y install xxhash-devel
! 123: > sudo dnf -y install libzstd-devel
! 124: > sudo dnf -y install lz4-devel
! 125: > sudo dnf -y install openssl-devel
! 126:
! 127: - For FreeBSD (this assumes that the python3 version is 3.7):
! 128:
! 129: > sudo pkg install -y autotools python3 py37-CommonMark
! 130: > sudo pkg install -y xxhash
! 131: > sudo pkg install -y zstd
! 132: > sudo pkg install -y liblz4
! 133:
! 134: - For macOS:
! 135:
! 136: > brew install automake
! 137: > brew install xxhash
! 138: > brew install zstd
! 139: > brew install lz4
! 140: > brew install openssl
! 141:
! 142: - For Cygwin (with all cygwin programs stopped, run the appropriate setup program from a cmd shell):
! 143:
! 144: > setup-x86_64 --quiet-mode -P make,gawk,autoconf,automake,gcc-core,python3,python36-commonmark
! 145: > setup-x86_64 --quiet-mode -P attr,libattr-devel
! 146: > setup-x86_64 --quiet-mode -P libzstd-devel
! 147: > setup-x86_64 --quiet-mode -P liblz4-devel
! 148: > setup-x86_64 --quiet-mode -P libssl-devel
! 149:
! 150: ## Build and install
! 151:
! 152: After installing the various libraries, you need to configure, build, and
! 153: install the source:
! 154:
! 155: > ./configure
! 156: > make
! 157: > sudo make install
! 158:
! 159: The default install path is /usr/local/bin, but you can set the installation
! 160: directory and other parameters using options to ./configure. To see them, use:
! 161:
! 162: > ./configure --help
! 163:
! 164: Configure tries to figure out if the local system uses group "nobody" or
! 165: "nogroup" by looking in the /etc/group file. (This is only used for the
! 166: default group of an rsync daemon, which attempts to run with "nobody"
! 167: user and group permissions.) You can change the default user and group
! 168: for the daemon by editing the NOBODY_USER and NOBODY_GROUP defines in
! 169: config.h, or just override them in your /etc/rsyncd.conf file.
! 170:
! 171: As of 2.4.7, rsync uses Eric Troan's popt option-parsing library. A
! 172: cut-down copy of a recent release is included in the rsync distribution,
! 173: and will be used if there is no popt library on your build host, or if
! 174: the --with-included-popt option is passed to ./configure.
! 175:
! 176: If you configure using --enable-maintainer-mode, then rsync will try
! 177: to pop up an xterm on DISPLAY=:0 if it crashes. You might find this
! 178: useful, but it should be turned off for production builds.
! 179:
! 180: If you want to automatically use a separate "build" directory based on
! 181: the current git branch name, start with a pristine git checkout and run
! 182: "mkdir auto-build-save" before you run the first ./configure command.
! 183: That will cause a fresh build dir to spring into existence along with a
! 184: special Makefile symlink that allows you to run "make" and "./configure"
! 185: from the source dir (the "build" dir gets auto switched based on branch).
! 186: This is helpful when using the branch-from-patch and patch-update scripts
! 187: to maintain the official rsync patches. If you ever need to build from
! 188: a "detached head" git position then you'll need to manually chdir into
! 189: the build dir to run make. I also like to create 2 more symlinks in the
! 190: source dir: ln -s build/rsync . ; ln -s build/testtmp .
! 191:
! 192: ## Make compatibility
! 193:
! 194: Note that Makefile.in has a rule that uses a wildcard in a prerequisite. If
! 195: your make has a problem with this rule, you will see an error like this:
! 196:
! 197: Don't know how to make ./*.c
! 198:
! 199: You can change the "proto.h-tstamp" target in Makefile.in to list all the \*.c
! 200: filenames explicitly in order to avoid this issue.
! 201:
! 202: ## RPM notes
! 203:
! 204: Under packaging you will find .spec files for several distributions.
! 205: The .spec file in packaging/lsb can be used for Linux systems that
! 206: adhere to the Linux Standards Base (e.g., RedHat and others).
! 207:
! 208: ## HP-UX notes
! 209:
! 210: The HP-UX 10.10 "bundled" C compiler seems not to be able to cope with
! 211: ANSI C. You may see this error message in config.log if ./configure
! 212: fails:
! 213:
! 214: (Bundled) cc: "configure", line 2162: error 1705: Function prototypes are an ANSI feature.
! 215:
! 216: Install gcc or HP's "ANSI/C Compiler".
! 217:
! 218: ## Mac OS X notes
! 219:
! 220: Some versions of Mac OS X (Darwin) seem to have an IPv6 stack, but do
! 221: not completely implement the "New Sockets" API.
! 222:
! 223: [This site][5] says that Apple started to support IPv6 in 10.2 (Jaguar). If
! 224: your build fails, try again after running configure with --disable-ipv6.
! 225:
! 226: [5]: http://www.ipv6.org/impl/mac.html
! 227:
! 228: ## IBM AIX notes
! 229:
! 230: IBM AIX has a largefile problem with mkstemp. See IBM PR-51921.
! 231: The workaround is to append the following to config.h:
! 232:
! 233: > #ifdef _LARGE_FILES
! 234: > #undef HAVE_SECURE_MKSTEMP
! 235: > #endif
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>