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