Debian Codegraph @

deps/curl/docs/INSTALL.md

raw
1 # how to install curl and libcurl
2
3 ## Installing Binary Packages
4
5 Lots of people download binary distributions of curl and libcurl. This
6 document does not describe how to install curl or libcurl using such a binary
7 package. This document describes how to compile, build and install curl and
8 libcurl from source code.
9
10 ## Building using vcpkg
11
12 You can download and install curl and libcurl using the [vcpkg](https://github.com/Microsoft/vcpkg/) dependency manager:
13
14 git clone https://github.com/Microsoft/vcpkg.git
15 cd vcpkg
16 ./bootstrap-vcpkg.sh
17 ./vcpkg integrate install
18 vcpkg install curl[tool]
19
20 The curl port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
21
22 ## Building from git
23
24 If you get your code off a git repository instead of a release tarball, see
25 the `GIT-INFO` file in the root directory for specific instructions on how to
26 proceed.
27
28 # Unix
29
30 A normal Unix installation is made in three or four steps (after you've
31 unpacked the source archive):
32
33 ./configure
34 make
35 make test (optional)
36 make install
37
38 You probably need to be root when doing the last command.
39
40 Get a full listing of all available configure options by invoking it like:
41
42 ./configure --help
43
44 If you want to install curl in a different file hierarchy than `/usr/local`,
45 specify that when running configure:
46
47 ./configure --prefix=/path/to/curl/tree
48
49 If you have write permission in that directory, you can do 'make install'
50 without being root. An example of this would be to make a local install in
51 your own home directory:
52
53 ./configure --prefix=$HOME
54 make
55 make install
56
57 The configure script always tries to find a working SSL library unless
58 explicitly told not to. If you have OpenSSL installed in the default search
59 path for your compiler/linker, you don't need to do anything special. If you
60 have OpenSSL installed in `/usr/local/ssl`, you can run configure like:
61
62 ./configure --with-ssl
63
64 If you have OpenSSL installed somewhere else (for example, `/opt/OpenSSL`) and
65 you have pkg-config installed, set the pkg-config path first, like this:
66
67 env PKG_CONFIG_PATH=/opt/OpenSSL/lib/pkgconfig ./configure --with-ssl
68
69 Without pkg-config installed, use this:
70
71 ./configure --with-ssl=/opt/OpenSSL
72
73 If you insist on forcing a build without SSL support, even though you may
74 have OpenSSL installed in your system, you can run configure like this:
75
76 ./configure --without-ssl
77
78 If you have OpenSSL installed, but with the libraries in one place and the
79 header files somewhere else, you have to set the `LDFLAGS` and `CPPFLAGS`
80 environment variables prior to running configure. Something like this should
81 work:
82
83 CPPFLAGS="-I/path/to/ssl/include" LDFLAGS="-L/path/to/ssl/lib" ./configure
84
85 If you have shared SSL libs installed in a directory where your run-time
86 linker doesn't find them (which usually causes configure failures), you can
87 provide this option to gcc to set a hard-coded path to the run-time linker:
88
89 LDFLAGS=-Wl,-R/usr/local/ssl/lib ./configure --with-ssl
90
91 ## More Options
92
93 To force a static library compile, disable the shared library creation by
94 running configure like:
95
96 ./configure --disable-shared
97
98 To tell the configure script to skip searching for thread-safe functions, add
99 an option like:
100
101 ./configure --disable-thread
102
103 If you're a curl developer and use gcc, you might want to enable more debug
104 options with the `--enable-debug` option.
105
106 curl can be built to use a whole range of libraries to provide various useful
107 services, and configure will try to auto-detect a decent default. But if you
108 want to alter it, you can select how to deal with each individual library.
109
110 ## Select TLS backend
111
112 The default OpenSSL configure check will also detect and use BoringSSL or
113 libressl.
114
115 - GnuTLS: `--without-ssl --with-gnutls`.
116 - wolfSSL: `--without-ssl --with-wolfssl`
117 - NSS: `--without-ssl --with-nss`
118 - PolarSSL: `--without-ssl --with-polarssl`
119 - mbedTLS: `--without-ssl --with-mbedtls`
120 - schannel: `--without-ssl --with-schannel`
121 - secure transport: `--without-ssl --with-secure-transport`
122 - MesaLink: `--without-ssl --with-mesalink`
123 - BearSSL: `--without-ssl --with-bearssl`
124
125 # Windows
126
127 ## Building Windows DLLs and C run-time (CRT) linkage issues
128
129 As a general rule, building a DLL with static CRT linkage is highly
130 discouraged, and intermixing CRTs in the same app is something to avoid at
131 any cost.
132
133 Reading and comprehending Microsoft Knowledge Base articles KB94248 and
134 KB140584 is a must for any Windows developer. Especially important is full
135 understanding if you are not going to follow the advice given above.
136
137 - [How To Use the C Run-Time](https://support.microsoft.com/help/94248/how-to-use-the-c-run-time)
138 - [Run-Time Library Compiler Options](https://docs.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library)
139 - [Potential Errors Passing CRT Objects Across DLL Boundaries](https://docs.microsoft.com/cpp/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries)
140
141 If your app is misbehaving in some strange way, or it is suffering from
142 memory corruption, before asking for further help, please try first to
143 rebuild every single library your app uses as well as your app using the
144 debug multithreaded dynamic C runtime.
145
146 If you get linkage errors read section 5.7 of the FAQ document.
147
148 ## MingW32
149
150 Make sure that MinGW32's bin dir is in the search path, for example:
151
152 set PATH=c:\mingw32\bin;%PATH%
153
154 then run `mingw32-make mingw32` in the root dir. There are other
155 make targets available to build libcurl with more features, use:
156
157 - `mingw32-make mingw32-zlib` to build with Zlib support;
158 - `mingw32-make mingw32-ssl-zlib` to build with SSL and Zlib enabled;
159 - `mingw32-make mingw32-ssh2-ssl-zlib` to build with SSH2, SSL, Zlib;
160 - `mingw32-make mingw32-ssh2-ssl-sspi-zlib` to build with SSH2, SSL, Zlib
161 and SSPI support.
162
163 If you have any problems linking libraries or finding header files, be sure
164 to verify that the provided `Makefile.m32` files use the proper paths, and
165 adjust as necessary. It is also possible to override these paths with
166 environment variables, for example:
167
168 set ZLIB_PATH=c:\zlib-1.2.8
169 set OPENSSL_PATH=c:\openssl-1.0.2c
170 set LIBSSH2_PATH=c:\libssh2-1.6.0
171
172 It is also possible to build with other LDAP SDKs than MS LDAP; currently
173 it is possible to build with native Win32 OpenLDAP, or with the Novell CLDAP
174 SDK. If you want to use these you need to set these vars:
175
176 set LDAP_SDK=c:\openldap
177 set USE_LDAP_OPENLDAP=1
178
179 or for using the Novell SDK:
180
181 set USE_LDAP_NOVELL=1
182
183 If you want to enable LDAPS support then set LDAPS=1.
184
185 ## Cygwin
186
187 Almost identical to the unix installation. Run the configure script in the
188 curl source tree root with `sh configure`. Make sure you have the `sh`
189 executable in `/bin/` or you'll see the configure fail toward the end.
190
191 Run `make`
192
193 ## Disabling Specific Protocols in Windows builds
194
195 The configure utility, unfortunately, is not available for the Windows
196 environment, therefore, you cannot use the various disable-protocol options of
197 the configure utility on this platform.
198
199 You can use specific defines to disable specific protocols and features. See
200 [CURL-DISABLE.md](CURL-DISABLE-md) for the full list.
201
202 If you want to set any of these defines you have the following options:
203
204 - Modify `lib/config-win32.h`
205 - Modify `lib/curl_setup.h`
206 - Modify `winbuild/Makefile.vc`
207 - Modify the "Preprocessor Definitions" in the libcurl project
208
209 Note: The pre-processor settings can be found using the Visual Studio IDE
210 under "Project -> Settings -> C/C++ -> General" in VC6 and "Project ->
211 Properties -> Configuration Properties -> C/C++ -> Preprocessor" in later
212 versions.
213
214 ## Using BSD-style lwIP instead of Winsock TCP/IP stack in Win32 builds
215
216 In order to compile libcurl and curl using BSD-style lwIP TCP/IP stack it is
217 necessary to make definition of preprocessor symbol `USE_LWIPSOCK` visible to
218 libcurl and curl compilation processes. To set this definition you have the
219 following alternatives:
220
221 - Modify `lib/config-win32.h` and `src/config-win32.h`
222 - Modify `winbuild/Makefile.vc`
223 - Modify the "Preprocessor Definitions" in the libcurl project
224
225 Note: The pre-processor settings can be found using the Visual Studio IDE
226 under "Project -> Settings -> C/C++ -> General" in VC6 and "Project ->
227 Properties -> Configuration Properties -> C/C++ -> Preprocessor" in later
228 versions.
229
230 Once that libcurl has been built with BSD-style lwIP TCP/IP stack support, in
231 order to use it with your program it is mandatory that your program includes
232 lwIP header file `<lwip/opt.h>` (or another lwIP header that includes this)
233 before including any libcurl header. Your program does not need the
234 `USE_LWIPSOCK` preprocessor definition which is for libcurl internals only.
235
236 Compilation has been verified with [lwIP
237 1.4.0](https://download.savannah.gnu.org/releases/lwip/lwip-1.4.0.zip) and
238 [contrib-1.4.0](https://download.savannah.gnu.org/releases/lwip/contrib-1.4.0.zip).
239
240 This BSD-style lwIP TCP/IP stack support must be considered experimental given
241 that it has been verified that lwIP 1.4.0 still needs some polish, and libcurl
242 might yet need some additional adjustment, caveat emptor.
243
244 ## Important static libcurl usage note
245
246 When building an application that uses the static libcurl library on Windows,
247 you must add `-DCURL_STATICLIB` to your `CFLAGS`. Otherwise the linker will
248 look for dynamic import symbols.
249
250 ## Legacy Windows and SSL
251
252 Schannel (from Windows SSPI), is the native SSL library in Windows. However,
253 Schannel in Windows <= XP is unable to connect to servers that
254 no longer support the legacy handshakes and algorithms used by those
255 versions. If you will be using curl in one of those earlier versions of
256 Windows you should choose another SSL backend such as OpenSSL.
257
258 # Apple iOS and macOS
259
260 On modern Apple operating systems, curl can be built to use Apple's SSL/TLS
261 implementation, Secure Transport, instead of OpenSSL. To build with Secure
262 Transport for SSL/TLS, use the configure option `--with-darwinssl`. (It is not
263 necessary to use the option `--without-ssl`.) This feature requires iOS 5.0 or
264 later, or OS X 10.5 ("Leopard") or later.
265
266 When Secure Transport is in use, the curl options `--cacert` and `--capath`
267 and their libcurl equivalents, will be ignored, because Secure Transport uses
268 the certificates stored in the Keychain to evaluate whether or not to trust
269 the server. This, of course, includes the root certificates that ship with the
270 OS. The `--cert` and `--engine` options, and their libcurl equivalents, are
271 currently unimplemented in curl with Secure Transport.
272
273 For macOS users: In OS X 10.8 ("Mountain Lion"), Apple made a major overhaul
274 to the Secure Transport API that, among other things, added support for the
275 newer TLS 1.1 and 1.2 protocols. To get curl to support TLS 1.1 and 1.2, you
276 must build curl on Mountain Lion or later, or by using the equivalent SDK. If
277 you set the `MACOSX_DEPLOYMENT_TARGET` environmental variable to an earlier
278 version of macOS prior to building curl, then curl will use the new Secure
279 Transport API on Mountain Lion and later, and fall back on the older API when
280 the same curl binary is executed on older cats. For example, running these
281 commands in curl's directory in the shell will build the code such that it
282 will run on cats as old as OS X 10.6 ("Snow Leopard") (using bash):
283
284 export MACOSX_DEPLOYMENT_TARGET="10.6"
285 ./configure --with-darwinssl
286 make
287
288 # Android
289
290 When building curl for Android it's recommended to use a Linux environment
291 since using curl's `configure` script is the easiest way to build curl
292 for Android. Before you can build curl for Android, you need to install the
293 Android NDK first. This can be done using the SDK Manager that is part of
294 Android Studio. Once you have installed the Android NDK, you need to figure out
295 where it has been installed and then set up some environment variables before
296 launching `configure`. On macOS, those variables could look like this to compile
297 for `aarch64` and API level 29:
298
299 export NDK=~/Library/Android/sdk/ndk/20.1.5948944
300 export HOST_TAG=darwin-x86_64
301 export TOOLCHAIN=$NDK/toolchains/llvm/prebuilt/$HOST_TAG
302 export AR=$TOOLCHAIN/bin/aarch64-linux-android-ar
303 export AS=$TOOLCHAIN/bin/aarch64-linux-android-as
304 export CC=$TOOLCHAIN/bin/aarch64-linux-android29-clang
305 export CXX=$TOOLCHAIN/bin/aarch64-linux-android29-clang++
306 export LD=$TOOLCHAIN/bin/aarch64-linux-android-ld
307 export RANLIB=$TOOLCHAIN/bin/aarch64-linux-android-ranlib
308 export STRIP=$TOOLCHAIN/bin/aarch64-linux-android-strip
309
310 When building on Linux or targeting other API levels or architectures, you need
311 to adjust those variables accordingly. After that you can build curl like this:
312
313 ./configure --host aarch64-linux-android --with-pic --disable-shared
314
315 Note that this won't give you SSL/TLS support. If you need SSL/TLS, you have
316 to build curl against a SSL/TLS layer, e.g. OpenSSL, because it's impossible for
317 curl to access Android's native SSL/TLS layer. To build curl for Android using
318 OpenSSL, follow the OpenSSL build instructions and then install `libssl.a` and
319 `libcrypto.a` to `$TOOLCHAIN/sysroot/usr/lib` and copy `include/openssl` to
320 `$TOOLCHAIN/sysroot/usr/include`. Now you can build curl for Android using
321 OpenSSL like this:
322
323 ./configure --host aarch64-linux-android --with-pic --disable-shared --with-ssl="$TOOLCHAIN/sysroot/usr"
324
325 Note, however, that you must target at least Android M (API level 23) or `configure`
326 won't be able to detect OpenSSL since `stderr` (and the like) weren't defined
327 before Android M.
328
329 # Cross compile
330
331 Download and unpack the curl package.
332
333 `cd` to the new directory. (e.g. `cd curl-7.12.3`)
334
335 Set environment variables to point to the cross-compile toolchain and call
336 configure with any options you need. Be sure and specify the `--host` and
337 `--build` parameters at configuration time. The following script is an
338 example of cross-compiling for the IBM 405GP PowerPC processor using the
339 toolchain from MonteVista for Hardhat Linux.
340
341 #! /bin/sh
342
343 export PATH=$PATH:/opt/hardhat/devkit/ppc/405/bin
344 export CPPFLAGS="-I/opt/hardhat/devkit/ppc/405/target/usr/include"
345 export AR=ppc_405-ar
346 export AS=ppc_405-as
347 export LD=ppc_405-ld
348 export RANLIB=ppc_405-ranlib
349 export CC=ppc_405-gcc
350 export NM=ppc_405-nm
351
352 ./configure --target=powerpc-hardhat-linux
353 --host=powerpc-hardhat-linux
354 --build=i586-pc-linux-gnu
355 --prefix=/opt/hardhat/devkit/ppc/405/target/usr/local
356 --exec-prefix=/usr/local
357
358 You may also need to provide a parameter like `--with-random=/dev/urandom` to
359 configure as it cannot detect the presence of a random number generating
360 device for a target system. The `--prefix` parameter specifies where curl
361 will be installed. If `configure` completes successfully, do `make` and `make
362 install` as usual.
363
364 In some cases, you may be able to simplify the above commands to as little as:
365
366 ./configure --host=ARCH-OS
367
368 # REDUCING SIZE
369
370 There are a number of configure options that can be used to reduce the size of
371 libcurl for embedded applications where binary size is an important factor.
372 First, be sure to set the `CFLAGS` variable when configuring with any relevant
373 compiler optimization flags to reduce the size of the binary. For gcc, this
374 would mean at minimum the -Os option, and potentially the `-march=X`,
375 `-mdynamic-no-pic` and `-flto` options as well, e.g.
376
377 ./configure CFLAGS='-Os' LDFLAGS='-Wl,-Bsymbolic'...
378
379 Note that newer compilers often produce smaller code than older versions
380 due to improved optimization.
381
382 Be sure to specify as many `--disable-` and `--without-` flags on the
383 configure command-line as you can to disable all the libcurl features that you
384 know your application is not going to need. Besides specifying the
385 `--disable-PROTOCOL` flags for all the types of URLs your application will not
386 use, here are some other flags that can reduce the size of the library:
387
388 - `--disable-ares` (disables support for the C-ARES DNS library)
389 - `--disable-cookies` (disables support for HTTP cookies)
390 - `--disable-crypto-auth` (disables HTTP cryptographic authentication)
391 - `--disable-ipv6` (disables support for IPv6)
392 - `--disable-manual` (disables support for the built-in documentation)
393 - `--disable-proxy` (disables support for HTTP and SOCKS proxies)
394 - `--disable-unix-sockets` (disables support for UNIX sockets)
395 - `--disable-verbose` (eliminates debugging strings and error code strings)
396 - `--disable-versioned-symbols` (disables support for versioned symbols)
397 - `--enable-hidden-symbols` (eliminates unneeded symbols in the shared library)
398 - `--without-libidn` (disables support for the libidn DNS library)
399 - `--without-librtmp` (disables support for RTMP)
400 - `--without-ssl` (disables support for SSL/TLS)
401 - `--without-zlib` (disables support for on-the-fly decompression)
402
403 The GNU compiler and linker have a number of options that can reduce the
404 size of the libcurl dynamic libraries on some platforms even further.
405 Specify them by providing appropriate `CFLAGS` and `LDFLAGS` variables on
406 the configure command-line, e.g.
407
408 CFLAGS="-Os -ffunction-sections -fdata-sections
409 -fno-unwind-tables -fno-asynchronous-unwind-tables -flto"
410 LDFLAGS="-Wl,-s -Wl,-Bsymbolic -Wl,--gc-sections"
411
412 Be sure also to strip debugging symbols from your binaries after compiling
413 using 'strip' (or the appropriate variant if cross-compiling). If space is
414 really tight, you may be able to remove some unneeded sections of the shared
415 library using the -R option to objcopy (e.g. the .comment section).
416
417 Using these techniques it is possible to create a basic HTTP-only shared
418 libcurl library for i386 Linux platforms that is only 113 KiB in size, and an
419 FTP-only library that is 113 KiB in size (as of libcurl version 7.50.3, using
420 gcc 5.4.0).
421
422 You may find that statically linking libcurl to your application will result
423 in a lower total size than dynamically linking.
424
425 Note that the curl test harness can detect the use of some, but not all, of
426 the `--disable` statements suggested above. Use will cause tests relying on
427 those features to fail. The test harness can be manually forced to skip the
428 relevant tests by specifying certain key words on the `runtests.pl` command
429 line. Following is a list of appropriate key words:
430
431 - `--disable-cookies` !cookies
432 - `--disable-manual` !--manual
433 - `--disable-proxy` !HTTP\ proxy !proxytunnel !SOCKS4 !SOCKS5
434
435 # PORTS
436
437 This is a probably incomplete list of known hardware and operating systems
438 that curl has been compiled for. If you know a system curl compiles and
439 runs on, that isn't listed, please let us know!
440
441 - Alpha DEC OSF 4
442 - Alpha Digital UNIX v3.2
443 - Alpha FreeBSD 4.1, 4.5
444 - Alpha Linux 2.2, 2.4
445 - Alpha NetBSD 1.5.2
446 - Alpha OpenBSD 3.0
447 - Alpha OpenVMS V7.1-1H2
448 - Alpha Tru64 v5.0 5.1
449 - AVR32 Linux
450 - ARM Android 1.5, 2.1, 2.3, 3.2, 4.x
451 - ARM INTEGRITY
452 - ARM iOS
453 - Cell Linux
454 - Cell Cell OS
455 - HP-PA HP-UX 9.X 10.X 11.X
456 - HP-PA Linux
457 - HP3000 MPE/iX
458 - MicroBlaze uClinux
459 - MIPS IRIX 6.2, 6.5
460 - MIPS Linux
461 - OS/400
462 - Pocket PC/Win CE 3.0
463 - Power AIX 3.2.5, 4.2, 4.3.1, 4.3.2, 5.1, 5.2
464 - PowerPC Darwin 1.0
465 - PowerPC INTEGRITY
466 - PowerPC Linux
467 - PowerPC Mac OS 9
468 - PowerPC Mac OS X
469 - SH4 Linux 2.6.X
470 - SH4 OS21
471 - SINIX-Z v5
472 - Sparc Linux
473 - Sparc Solaris 2.4, 2.5, 2.5.1, 2.6, 7, 8, 9, 10
474 - Sparc SunOS 4.1.X
475 - StrongARM (and other ARM) RISC OS 3.1, 4.02
476 - StrongARM/ARM7/ARM9 Linux 2.4, 2.6
477 - StrongARM NetBSD 1.4.1
478 - Symbian OS (P.I.P.S.) 9.x
479 - TPF
480 - Ultrix 4.3a
481 - UNICOS 9.0
482 - i386 BeOS
483 - i386 DOS
484 - i386 eCos 1.3.1
485 - i386 Esix 4.1
486 - i386 FreeBSD
487 - i386 HURD
488 - i386 Haiku OS
489 - i386 Linux 1.3, 2.0, 2.2, 2.3, 2.4, 2.6
490 - i386 Mac OS X
491 - i386 MINIX 3.1
492 - i386 NetBSD
493 - i386 Novell NetWare
494 - i386 OS/2
495 - i386 OpenBSD
496 - i386 QNX 6
497 - i386 SCO unix
498 - i386 Solaris 2.7
499 - i386 Windows 95, 98, ME, NT, 2000, XP, 2003
500 - i486 ncr-sysv4.3.03 (NCR MP-RAS)
501 - ia64 Linux 2.3.99
502 - m68k AmigaOS 3
503 - m68k Linux
504 - m68k uClinux
505 - m68k OpenBSD
506 - m88k dg-dgux5.4R3.00
507 - s390 Linux
508 - x86_64 Linux
509 - XScale/PXA250 Linux 2.4
510 - Nios II uClinux