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