INSTALL.md

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