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