docs/INSTALL.md

   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 from git
  11
  12 If you get your code off a git repository instead of a release tarball, see
  13 the `GIT-INFO` file in the root directory for specific instructions on how to
  14 proceed.
  15
  16 # Unix
  17
  18 A normal Unix installation is made in three or four steps (after you've
  19 unpacked the source archive):
  20
  21     ./configure
  22     make
  23     make test (optional)
  24     make install
  25
  26 You probably need to be root when doing the last command.
  27
  28 Get a full listing of all available configure options by invoking it like:
  29
  30     ./configure --help
  31
  32 If you want to install curl in a different file hierarchy than `/usr/local`,
  33 specify that when running configure:
  34
  35     ./configure --prefix=/path/to/curl/tree
  36
  37 If you have write permission in that directory, you can do 'make install'
  38 without being root. An example of this would be to make a local install in
  39 your own home directory:
  40
  41     ./configure --prefix=$HOME
  42     make
  43     make install
  44
  45 The configure script always tries to find a working SSL library unless
  46 explicitly told not to. If you have OpenSSL installed in the default search
  47 path for your compiler/linker, you don't need to do anything special. If you
  48 have OpenSSL installed in /usr/local/ssl, you can run configure like:
  49
  50     ./configure --with-ssl
  51
  52 If you have OpenSSL installed somewhere else (for example, /opt/OpenSSL) and
  53 you 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
  57 Without pkg-config installed, use this:
  58
  59    ./configure --with-ssl=/opt/OpenSSL
  60
  61 If you insist on forcing a build without SSL support, even though you may
  62 have OpenSSL installed in your system, you can run configure like this:
  63
  64    ./configure --without-ssl
  65
  66 If you have OpenSSL installed, but with the libraries in one place and the
  67 header files somewhere else, you have to set the LDFLAGS and CPPFLAGS
  68 environment variables prior to running configure.  Something like this should
  69 work:
  70
  71     CPPFLAGS="-I/path/to/ssl/include" LDFLAGS="-L/path/to/ssl/lib" ./configure
  72
  73 If you have shared SSL libs installed in a directory where your run-time
  74 linker doesn't find them (which usually causes configure failures), you can
  75 provide the -R option to ld on some operating systems to set a hard-coded
  76 path to the run-time linker:
  77
  78     LDFLAGS=-R/usr/local/ssl/lib ./configure --with-ssl
  79
  80 ## More Options
  81
  82 To force a static library compile, disable the shared library creation by
  83 running configure like:
  84
  85     ./configure --disable-shared
  86
  87 To tell the configure script to skip searching for thread-safe functions, add
  88 an option like:
  89
  90     ./configure --disable-thread
  91
  92 If you're a curl developer and use gcc, you might want to enable more debug
  93 options with the `--enable-debug` option.
  94
  95 curl can be built to use a whole range of libraries to provide various useful
  96 services, and configure will try to auto-detect a decent default. But if you
  97 want to alter it, you can select how to deal with each individual library.
  98
  99 ## Select TLS backend
 100
 101 The default OpenSSL configure check will also detect and use BoringSSL or
 102 libressl.
 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
 129 If your app is misbehaving in some strange way, or it is suffering from
 130 memory corruption, before asking for further help, please try first to
 131 rebuild every single library your app uses as well as your app using the
 132 debug multithreaded dynamic C runtime.
 133
 134  If you get linkage errors read section 5.7 of the FAQ document.
 135
 136 ## MingW32
 137
 138 Make sure that MinGW32's bin dir is in the search path, for example:
 139
 140     set PATH=c:\mingw32\bin;%PATH%
 141
 142 then run `mingw32-make mingw32` in the root dir. There are other
 143 make 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
 151 If you have any problems linking libraries or finding header files, be sure
 152 to verify that the provided "Makefile.m32" files use the proper paths, and
 153 adjust as necessary. It is also possible to override these paths with
 154 environment 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
 160 It is also possible to build with other LDAP SDKs than MS LDAP; currently
 161 it is possible to build with native Win32 OpenLDAP, or with the Novell CLDAP
 162 SDK. 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
 167 or for using the Novell SDK:
 168
 169     set USE_LDAP_NOVELL=1
 170
 171 If you want to enable LDAPS support then set LDAPS=1.
 172
 173 ## Cygwin
 174
 175 Almost identical to the unix installation. Run the configure script in the
 176 curl source tree root with `sh configure`. Make sure you have the sh
 177 executable in /bin/ or you'll see the configure fail toward the end.
 178
 179 Run `make`
 180
 181 ## Borland C++ compiler
 182
 183 Ensure that your build environment is properly set up to use the compiler and
 184 associated tools. PATH environment variable must include the path to bin
 185 subdirectory of your compiler installation, eg: `c:\Borland\BCC55\bin`
 186
 187 It is advisable to set environment variable BCCDIR to the base path of the
 188 compiler installation.
 189
 190     set BCCDIR=c:\Borland\BCC55
 191
 192 In order to build a plain vanilla version of curl and libcurl run the
 193 following command from curl's root directory:
 194
 195     make borland
 196
 197 To build curl and libcurl with zlib and OpenSSL support set environment
 198 variables `ZLIB_PATH` and `OPENSSL_PATH` to the base subdirectories of the
 199 already built zlib and OpenSSL libraries and from curl's root directory run
 200 command:
 201
 202     make borland-ssl-zlib
 203
 204 libcurl library will be built in 'lib' subdirectory while curl tool is built
 205 in 'src' subdirectory. In order to use libcurl library it is advisable to
 206 modify compiler's configuration file bcc32.cfg located in
 207 `c:\Borland\BCC55\bin` to reflect the location of libraries include paths for
 208 example the '-I' line could result in something like:
 209
 210     -I"c:\Borland\BCC55\include;c:\curl\include;c:\openssl\inc32"
 211
 212 bcc3.cfg `-L` line could also be modified to reflect the location of of
 213 libcurl library resulting for example:
 214
 215     -L"c:\Borland\BCC55\lib;c:\curl\lib;c:\openssl\out32"
 216
 217 In order to build sample program `simple.c` from the docs\examples
 218 subdirectory run following command from mentioned subdirectory:
 219
 220     bcc32 simple.c libcurl.lib cw32mt.lib
 221
 222 In order to build sample program simplessl.c an SSL enabled libcurl is
 223 required, as well as the OpenSSL libeay32.lib and ssleay32.lib libraries.
 224
 225 In order to build sample program `sslbackend.c`, an SSL enabled libcurl
 226 is required.
 227
 228 ## Disabling Specific Protocols in Windows builds
 229
 230 The configure utility, unfortunately, is not available for the Windows
 231 environment, therefore, you cannot use the various disable-protocol options of
 232 the configure utility on this platform.
 233
 234 However, you can use the following defines to disable specific
 235 protocols:
 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
 249 If 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
 256 Note: The pre-processor settings can be found using the Visual Studio IDE
 257 under "Project -> Settings -> C/C++ -> General" in VC6 and "Project ->
 258 Properties -> Configuration Properties -> C/C++ -> Preprocessor" in later
 259 versions.
 260
 261 ## Using BSD-style lwIP instead of Winsock TCP/IP stack in Win32 builds
 262
 263 In order to compile libcurl and curl using BSD-style lwIP TCP/IP stack it is
 264 necessary to make definition of preprocessor symbol USE_LWIPSOCK visible to
 265 libcurl and curl compilation processes. To set this definition you have the
 266 following 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
 272 Note: The pre-processor settings can be found using the Visual Studio IDE
 273 under "Project -> Settings -> C/C++ -> General" in VC6 and "Project ->
 274 Properties -> Configuration Properties -> C/C++ -> Preprocessor" in later
 275 versions.
 276
 277 Once that libcurl has been built with BSD-style lwIP TCP/IP stack support, in
 278 order to use it with your program it is mandatory that your program includes
 279 lwIP header file `<lwip/opt.h>` (or another lwIP header that includes this)
 280 before including any libcurl header. Your program does not need the
 281 `USE_LWIPSOCK` preprocessor definition which is for libcurl internals only.
 282
 283 Compilation has been verified with [lwIP
 284 1.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
 287 This BSD-style lwIP TCP/IP stack support must be considered experimental given
 288 that it has been verified that lwIP 1.4.0 still needs some polish, and libcurl
 289 might yet need some additional adjustment, caveat emptor.
 290
 291 ## Important static libcurl usage note
 292
 293 When building an application that uses the static libcurl library on Windows,
 294 you must add `-DCURL_STATICLIB` to your `CFLAGS`.  Otherwise the linker will
 295 look for dynamic import symbols.
 296
 297 ## Legacy Windows and SSL
 298
 299 WinSSL (specifically SChannel from Windows SSPI), is the native SSL library in
 300 Windows. However, WinSSL in Windows <= XP is unable to connect to servers that
 301 no longer support the legacy handshakes and algorithms used by those
 302 versions. If you will be using curl in one of those earlier versions of
 303 Windows you should choose another SSL backend such as OpenSSL.
 304
 305 # Apple iOS and Mac OS X
 306
 307 On modern Apple operating systems, curl can be built to use Apple's SSL/TLS
 308 implementation, Secure Transport, instead of OpenSSL. To build with Secure
 309 Transport for SSL/TLS, use the configure option `--with-darwinssl`. (It is not
 310 necessary to use the option `--without-ssl`.) This feature requires iOS 5.0 or
 311 later, or OS X 10.5 ("Leopard") or later.
 312
 313 When Secure Transport is in use, the curl options `--cacert` and `--capath`
 314 and their libcurl equivalents, will be ignored, because Secure Transport uses
 315 the certificates stored in the Keychain to evaluate whether or not to trust
 316 the server. This, of course, includes the root certificates that ship with the
 317 OS. The `--cert` and `--engine` options, and their libcurl equivalents, are
 318 currently unimplemented in curl with Secure Transport.
 319
 320 For OS X users: In OS X 10.8 ("Mountain Lion"), Apple made a major overhaul to
 321 the Secure Transport API that, among other things, added support for the newer
 322 TLS 1.1 and 1.2 protocols. To get curl to support TLS 1.1 and 1.2, you must
 323 build curl on Mountain Lion or later, or by using the equivalent SDK. If you
 324 set the `MACOSX_DEPLOYMENT_TARGET` environmental variable to an earlier
 325 version of OS X prior to building curl, then curl will use the new Secure
 326 Transport API on Mountain Lion and later, and fall back on the older API when
 327 the same curl binary is executed on older cats. For example, running these
 328 commands in curl's directory in the shell will build the code such that it
 329 will 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
 337 Download and unpack the curl package.
 338
 339 'cd' to the new directory. (e.g. `cd curl-7.12.3`)
 340
 341 Set environment variables to point to the cross-compile toolchain and call
 342 configure with any options you need.  Be sure and specify the `--host` and
 343 `--build` parameters at configuration time.  The following script is an
 344 example of cross-compiling for the IBM 405GP PowerPC processor using the
 345 toolchain 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
 364 You may also need to provide a parameter like `--with-random=/dev/urandom` to
 365 configure as it cannot detect the presence of a random number generating
 366 device for a target system.  The `--prefix` parameter specifies where curl
 367 will be installed.  If `configure` completes successfully, do `make` and `make
 368 install` as usual.
 369
 370 In 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
 376 There are a number of configure options that can be used to reduce the size of
 377 libcurl for embedded applications where binary size is an important factor.
 378 First, be sure to set the CFLAGS variable when configuring with any relevant
 379 compiler optimization flags to reduce the size of the binary.  For gcc, this
 380 would 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
 385 Note that newer compilers often produce smaller code than older versions
 386 due to improved optimization.
 387
 388 Be sure to specify as many `--disable-` and `--without-` flags on the
 389 configure command-line as you can to disable all the libcurl features that you
 390 know your application is not going to need.  Besides specifying the
 391 `--disable-PROTOCOL` flags for all the types of URLs your application will not
 392 use, 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
 409 The GNU compiler and linker have a number of options that can reduce the
 410 size of the libcurl dynamic libraries on some platforms even further.
 411 Specify them by providing appropriate CFLAGS and LDFLAGS variables on the
 412 configure 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
 418 Be sure also to strip debugging symbols from your binaries after compiling
 419 using 'strip' (or the appropriate variant if cross-compiling).  If space is
 420 really tight, you may be able to remove some unneeded sections of the shared
 421 library using the -R option to objcopy (e.g. the .comment section).
 422
 423 Using these techniques it is possible to create a basic HTTP-only shared
 424 libcurl library for i386 Linux platforms that is only 113 KiB in size, and an
 425 FTP-only library that is 113 KiB in size (as of libcurl version 7.50.3, using
 426 gcc 5.4.0).
 427
 428 You may find that statically linking libcurl to your application will result
 429 in a lower total size than dynamically linking.
 430
 431 Note that the curl test harness can detect the use of some, but not all, of
 432 the `--disable` statements suggested above. Use will cause tests relying on
 433 those features to fail.  The test harness can be manually forced to skip the
 434 relevant tests by specifying certain key words on the runtests.pl command
 435 line.  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
 443 This is a probably incomplete list of known hardware and operating systems
 444 that curl has been compiled for. If you know a system curl compiles and
 445 runs 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