Annotation of embedaddon/rsync/INSTALL.md, revision 1.1.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>