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>