1 # How to build and install rsync
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):
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.
16 ## Autoconf & man pages
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):
25 > pip3 install --user commonmark
27 You can test if you've got it fixed by running (from the src dir):
29 > ./md2man --test rsync-ssl.1.md
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:
35 > ./prepare-source fetchgen
37 [6]: https://download.samba.org/pub/rsync/generated-files/
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.
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.
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.
58 [1]: https://cyan4973.github.io/xxHash/
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.
68 [2]: http://facebook.github.io/zstd/
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
77 [3]: https://lz4.github.io/lz4/
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
86 [4]: https://www.openssl.org/docs/man1.0.2/man3/crypto.html
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
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):
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 liblz4-dev
104 > sudo apt install -y libssl-dev
106 - For CentOS (use EPEL for python3-pip):
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
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
127 - For FreeBSD (this assumes that the python3 version is 3.7):
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
136 > brew install automake
137 > brew install xxhash
140 > brew install openssl
142 - For Cygwin (with all cygwin programs stopped, run the appropriate setup program from a cmd shell):
144 > setup-x86_64 --quiet-mode -P make,gawk,autoconf,automake,gcc-core,python3,python38-pip
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
150 Then, from a bash shell as your build user:
152 > pip3 install --user commonmark
156 After installing the various libraries, you need to configure, build, and
163 The default install path is /usr/local/bin, but you can set the installation
164 directory and other parameters using options to ./configure. To see them, use:
168 Configure tries to figure out if the local system uses group "nobody" or
169 "nogroup" by looking in the /etc/group file. (This is only used for the
170 default group of an rsync daemon, which attempts to run with "nobody"
171 user and group permissions.) You can change the default user and group
172 for the daemon by editing the NOBODY_USER and NOBODY_GROUP defines in
173 config.h, or just override them in your /etc/rsyncd.conf file.
175 As of 2.4.7, rsync uses Eric Troan's popt option-parsing library. A
176 cut-down copy of a recent release is included in the rsync distribution,
177 and will be used if there is no popt library on your build host, or if
178 the --with-included-popt option is passed to ./configure.
180 If you configure using --enable-maintainer-mode, then rsync will try
181 to pop up an xterm on DISPLAY=:0 if it crashes. You might find this
182 useful, but it should be turned off for production builds.
184 If you want to automatically use a separate "build" directory based on
185 the current git branch name, start with a pristine git checkout and run
186 "mkdir auto-build-save" before you run the first ./configure command.
187 That will cause a fresh build dir to spring into existence along with a
188 special Makefile symlink that allows you to run "make" and "./configure"
189 from the source dir (the "build" dir gets auto switched based on branch).
190 This is helpful when using the branch-from-patch and patch-update scripts
191 to maintain the official rsync patches. If you ever need to build from
192 a "detached head" git position then you'll need to manually chdir into
193 the build dir to run make. I also like to create 2 more symlinks in the
194 source dir: ln -s build/rsync . ; ln -s build/testtmp .
196 ## Make compatibility
198 Note that Makefile.in has a rule that uses a wildcard in a prerequisite. If
199 your make has a problem with this rule, you will see an error like this:
201 Don't know how to make ./*.c
203 You can change the "proto.h-tstamp" target in Makefile.in to list all the \*.c
204 filenames explicitly in order to avoid this issue.
208 Under packaging you will find .spec files for several distributions.
209 The .spec file in packaging/lsb can be used for Linux systems that
210 adhere to the Linux Standards Base (e.g., RedHat and others).
214 The HP-UX 10.10 "bundled" C compiler seems not to be able to cope with
215 ANSI C. You may see this error message in config.log if ./configure
218 (Bundled) cc: "configure", line 2162: error 1705: Function prototypes are an ANSI feature.
220 Install gcc or HP's "ANSI/C Compiler".
224 Some versions of Mac OS X (Darwin) seem to have an IPv6 stack, but do
225 not completely implement the "New Sockets" API.
227 [This site][5] says that Apple started to support IPv6 in 10.2 (Jaguar). If
228 your build fails, try again after running configure with --disable-ipv6.
230 [5]: http://www.ipv6.org/impl/mac.html
234 IBM AIX has a largefile problem with mkstemp. See IBM PR-51921.
235 The workaround is to append the following to config.h:
237 > #ifdef _LARGE_FILES
238 > #undef HAVE_SECURE_MKSTEMP