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