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