diff options
Diffstat (limited to 'docs/INSTALL.md')
| -rw-r--r-- | docs/INSTALL.md | 329 |
1 files changed, 178 insertions, 151 deletions
diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 33b439ec5..ed8ca2869 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -27,14 +27,16 @@ proceed. # Unix -A normal Unix installation is made in three or four steps (after you've +A normal Unix installation is made in three or four steps (after you have unpacked the source archive): - ./configure + ./configure --with-openssl [--with-gnutls --with-wolfssl] make make test (optional) make install +(Adjust the configure line accordingly to use the TLS library you want.) + You probably need to be root when doing the last command. Get a full listing of all available configure options by invoking it like: @@ -56,19 +58,19 @@ your own home directory: The configure script always tries to find a working SSL library unless explicitly told not to. If you have OpenSSL installed in the default search -path for your compiler/linker, you don't need to do anything special. If you +path for your compiler/linker, you do not need to do anything special. If you have OpenSSL installed in `/usr/local/ssl`, you can run configure like: - ./configure --with-ssl + ./configure --with-openssl If you have OpenSSL installed somewhere else (for example, `/opt/OpenSSL`) and you have pkg-config installed, set the pkg-config path first, like this: - env PKG_CONFIG_PATH=/opt/OpenSSL/lib/pkgconfig ./configure --with-ssl + env PKG_CONFIG_PATH=/opt/OpenSSL/lib/pkgconfig ./configure --with-openssl Without pkg-config installed, use this: - ./configure --with-ssl=/opt/OpenSSL + ./configure --with-openssl=/opt/OpenSSL If you insist on forcing a build without SSL support, even though you may have OpenSSL installed in your system, you can run configure like this: @@ -83,10 +85,10 @@ work: CPPFLAGS="-I/path/to/ssl/include" LDFLAGS="-L/path/to/ssl/lib" ./configure If you have shared SSL libs installed in a directory where your run-time -linker doesn't find them (which usually causes configure failures), you can +linker does not find them (which usually causes configure failures), you can provide this option to gcc to set a hard-coded path to the run-time linker: - LDFLAGS=-Wl,-R/usr/local/ssl/lib ./configure --with-ssl + LDFLAGS=-Wl,-R/usr/local/ssl/lib ./configure --with-openssl ## More Options @@ -100,7 +102,7 @@ an option like: ./configure --disable-thread -If you're a curl developer and use gcc, you might want to enable more debug +If you are a curl developer and use gcc, you might want to enable more debug options with the `--enable-debug` option. curl can be built to use a whole range of libraries to provide various useful @@ -109,17 +111,19 @@ want to alter it, you can select how to deal with each individual library. ## Select TLS backend -The default OpenSSL configure check will also detect and use BoringSSL or -libressl. +These options are provided to select TLS backend to use. - - GnuTLS: `--without-ssl --with-gnutls`. - - wolfSSL: `--without-ssl --with-wolfssl` - - NSS: `--without-ssl --with-nss` - - mbedTLS: `--without-ssl --with-mbedtls` - - schannel: `--without-ssl --with-schannel` - - secure transport: `--without-ssl --with-secure-transport` - - MesaLink: `--without-ssl --with-mesalink` - - BearSSL: `--without-ssl --with-bearssl` + - AmiSSL: `--with-amissl` + - BearSSL: `--with-bearssl` + - GnuTLS: `--with-gnutls`. + - mbedTLS: `--with-mbedtls` + - MesaLink: `--with-mesalink` + - NSS: `--with-nss` + - OpenSSL: `--with-openssl` (also for BoringSSL and libressl) + - rustls: `--with-rustls` + - schannel: `--with-schannel` + - secure transport: `--with-secure-transport` + - wolfSSL: `--with-wolfssl` # Windows @@ -148,7 +152,9 @@ debug multithreaded dynamic C runtime. Make sure that MinGW32's bin dir is in the search path, for example: - set PATH=c:\mingw32\bin;%PATH% +```cmd +set PATH=c:\mingw32\bin;%PATH% +``` then run `mingw32-make mingw32` in the root dir. There are other make targets available to build libcurl with more features, use: @@ -164,20 +170,26 @@ to verify that the provided `Makefile.m32` files use the proper paths, and adjust as necessary. It is also possible to override these paths with environment variables, for example: - set ZLIB_PATH=c:\zlib-1.2.8 - set OPENSSL_PATH=c:\openssl-1.0.2c - set LIBSSH2_PATH=c:\libssh2-1.6.0 +```cmd +set ZLIB_PATH=c:\zlib-1.2.8 +set OPENSSL_PATH=c:\openssl-1.0.2c +set LIBSSH2_PATH=c:\libssh2-1.6.0 +``` It is also possible to build with other LDAP SDKs than MS LDAP; currently it is possible to build with native Win32 OpenLDAP, or with the Novell CLDAP SDK. If you want to use these you need to set these vars: - set LDAP_SDK=c:\openldap - set USE_LDAP_OPENLDAP=1 +```cmd +set LDAP_SDK=c:\openldap +set USE_LDAP_OPENLDAP=1 +``` or for using the Novell SDK: - set USE_LDAP_NOVELL=1 +```cmd +set USE_LDAP_NOVELL=1 +``` If you want to enable LDAPS support then set LDAPS=1. @@ -185,7 +197,7 @@ If you want to enable LDAPS support then set LDAPS=1. Almost identical to the unix installation. Run the configure script in the curl source tree root with `sh configure`. Make sure you have the `sh` -executable in `/bin/` or you'll see the configure fail toward the end. +executable in `/bin/` or you will see the configure fail toward the end. Run `make` @@ -196,7 +208,7 @@ environment, therefore, you cannot use the various disable-protocol options of the configure utility on this platform. You can use specific defines to disable specific protocols and features. See -[CURL-DISABLE.md](CURL-DISABLE-md) for the full list. +[CURL-DISABLE.md](CURL-DISABLE.md) for the full list. If you want to set any of these defines you have the following options: @@ -254,13 +266,12 @@ no longer support the legacy handshakes and algorithms used by those versions. If you will be using curl in one of those earlier versions of Windows you should choose another SSL backend such as OpenSSL. -# Apple iOS and macOS +# Apple Platforms (macOS, iOS, tvOS, watchOS, and their simulator counterparts) On modern Apple operating systems, curl can be built to use Apple's SSL/TLS implementation, Secure Transport, instead of OpenSSL. To build with Secure Transport for SSL/TLS, use the configure option `--with-secure-transport`. (It -is not necessary to use the option `--without-ssl`.) This feature requires iOS -5.0 or later, or OS X 10.5 ("Leopard") or later. +is not necessary to use the option `--without-openssl`.) When Secure Transport is in use, the curl options `--cacert` and `--capath` and their libcurl equivalents, will be ignored, because Secure Transport uses @@ -269,20 +280,51 @@ the server. This, of course, includes the root certificates that ship with the OS. The `--cert` and `--engine` options, and their libcurl equivalents, are currently unimplemented in curl with Secure Transport. -For macOS users: In OS X 10.8 ("Mountain Lion"), Apple made a major overhaul -to the Secure Transport API that, among other things, added support for the -newer TLS 1.1 and 1.2 protocols. To get curl to support TLS 1.1 and 1.2, you -must build curl on Mountain Lion or later, or by using the equivalent SDK. If -you set the `MACOSX_DEPLOYMENT_TARGET` environmental variable to an earlier -version of macOS prior to building curl, then curl will use the new Secure -Transport API on Mountain Lion and later, and fall back on the older API when -the same curl binary is executed on older cats. For example, running these -commands in curl's directory in the shell will build the code such that it -will run on cats as old as OS X 10.6 ("Snow Leopard") (using bash): - - export MACOSX_DEPLOYMENT_TARGET="10.6" - ./configure --with-secure-transport - make +In general, a curl build for an Apple `ARCH/SDK/DEPLOYMENT_TARGET` combination +can be taken by providing appropriate values for `ARCH`, `SDK`, `DEPLOYMENT_TARGET` +below and running the commands: + +```bash +# Set these three according to your needs +export ARCH=x86_64 +export SDK=macosx +export DEPLOYMENT_TARGET=10.8 + +export CFLAGS="-arch $ARCH -isysroot $(xcrun -sdk $SDK --show-sdk-path) -m$SDK-version-min=$DEPLOYMENT_TARGET" +./configure --host=$ARCH-apple-darwin --prefix $(pwd)/artifacts --with-secure-transport +make -j8 +make install +``` + +Above will build curl for macOS platform with `x86_64` architecture and `10.8` as deployment target. + +Here is an example for iOS device: + +```bash +export ARCH=arm64 +export SDK=iphoneos +export DEPLOYMENT_TARGET=11.0 + +export CFLAGS="-arch $ARCH -isysroot $(xcrun -sdk $SDK --show-sdk-path) -m$SDK-version-min=$DEPLOYMENT_TARGET" +./configure --host=$ARCH-apple-darwin --prefix $(pwd)/artifacts --with-secure-transport +make -j8 +make install +``` + +Another example for watchOS simulator for macs with Apple Silicon: + +```bash +export ARCH=arm64 +export SDK=watchsimulator +export DEPLOYMENT_TARGET=5.0 + +export CFLAGS="-arch $ARCH -isysroot $(xcrun -sdk $SDK --show-sdk-path) -m$SDK-version-min=$DEPLOYMENT_TARGET" +./configure --host=$ARCH-apple-darwin --prefix $(pwd)/artifacts --with-secure-transport +make -j8 +make install +``` + +In all above, the built libraries and executables can be found in `artifacts` folder. # Android @@ -295,36 +337,71 @@ where it has been installed and then set up some environment variables before launching `configure`. On macOS, those variables could look like this to compile for `aarch64` and API level 29: - export NDK=~/Library/Android/sdk/ndk/20.1.5948944 - export HOST_TAG=darwin-x86_64 - export TOOLCHAIN=$NDK/toolchains/llvm/prebuilt/$HOST_TAG - export AR=$TOOLCHAIN/bin/aarch64-linux-android-ar - export AS=$TOOLCHAIN/bin/aarch64-linux-android-as - export CC=$TOOLCHAIN/bin/aarch64-linux-android29-clang - export CXX=$TOOLCHAIN/bin/aarch64-linux-android29-clang++ - export LD=$TOOLCHAIN/bin/aarch64-linux-android-ld - export RANLIB=$TOOLCHAIN/bin/aarch64-linux-android-ranlib - export STRIP=$TOOLCHAIN/bin/aarch64-linux-android-strip +```bash +export NDK=~/Library/Android/sdk/ndk/20.1.5948944 +export HOST_TAG=darwin-x86_64 +export TOOLCHAIN=$NDK/toolchains/llvm/prebuilt/$HOST_TAG +export AR=$TOOLCHAIN/bin/aarch64-linux-android-ar +export AS=$TOOLCHAIN/bin/aarch64-linux-android-as +export CC=$TOOLCHAIN/bin/aarch64-linux-android29-clang +export CXX=$TOOLCHAIN/bin/aarch64-linux-android29-clang++ +export LD=$TOOLCHAIN/bin/aarch64-linux-android-ld +export RANLIB=$TOOLCHAIN/bin/aarch64-linux-android-ranlib +export STRIP=$TOOLCHAIN/bin/aarch64-linux-android-strip +``` When building on Linux or targeting other API levels or architectures, you need to adjust those variables accordingly. After that you can build curl like this: ./configure --host aarch64-linux-android --with-pic --disable-shared -Note that this won't give you SSL/TLS support. If you need SSL/TLS, you have +Note that this will not give you SSL/TLS support. If you need SSL/TLS, you have to build curl against a SSL/TLS layer, e.g. OpenSSL, because it's impossible for curl to access Android's native SSL/TLS layer. To build curl for Android using OpenSSL, follow the OpenSSL build instructions and then install `libssl.a` and `libcrypto.a` to `$TOOLCHAIN/sysroot/usr/lib` and copy `include/openssl` to `$TOOLCHAIN/sysroot/usr/include`. Now you can build curl for Android using OpenSSL like this: - - ./configure --host aarch64-linux-android --with-pic --disable-shared --with-ssl="$TOOLCHAIN/sysroot/usr" + + ./configure --host aarch64-linux-android --with-pic --disable-shared --with-openssl="$TOOLCHAIN/sysroot/usr" Note, however, that you must target at least Android M (API level 23) or `configure` -won't be able to detect OpenSSL since `stderr` (and the like) weren't defined +will not be able to detect OpenSSL since `stderr` (and the like) were not defined before Android M. +# IBM i + +For IBM i (formerly OS/400), you can use curl in two different ways: + +- Natively, running in the **ILE**. The obvious use is being able to call curl + from ILE C or RPG applications. + - You will need to build this from source. See `packages/OS400/README` for + the ILE specific build instructions. +- In the **PASE** environment, which runs AIX programs. curl will be built as + it would be on AIX. + - IBM provides builds of curl in their Yum repository for PASE software. + - To build from source, follow the Unix instructions. + +There are some additional limitations and quirks with curl on this platform; +they affect both environments. + +## Multithreading notes + +By default, jobs in IBM i will not start with threading enabled. (Exceptions +include interactive PASE sessions started by `QP2TERM` or SSH.) If you use +curl in an environment without threading when options like async DNS were +enabled, you will messages like: + +``` +getaddrinfo() thread failed to start +``` + +Do not panic! curl and your program are not broken. You can fix this by: + +- Set the environment variable `QIBM_MULTI_THREADED` to `Y` before starting + your program. This can be done at whatever scope you feel is appropriate. +- Alternatively, start the job with the `ALWMLTTHD` parameter set to `*YES`. + # Cross compile Download and unpack the curl package. @@ -337,22 +414,24 @@ configure with any options you need. Be sure and specify the `--host` and example of cross-compiling for the IBM 405GP PowerPC processor using the toolchain from MonteVista for Hardhat Linux. - #! /bin/sh - - export PATH=$PATH:/opt/hardhat/devkit/ppc/405/bin - export CPPFLAGS="-I/opt/hardhat/devkit/ppc/405/target/usr/include" - export AR=ppc_405-ar - export AS=ppc_405-as - export LD=ppc_405-ld - export RANLIB=ppc_405-ranlib - export CC=ppc_405-gcc - export NM=ppc_405-nm - - ./configure --target=powerpc-hardhat-linux - --host=powerpc-hardhat-linux - --build=i586-pc-linux-gnu - --prefix=/opt/hardhat/devkit/ppc/405/target/usr/local - --exec-prefix=/usr/local +```bash +#! /bin/sh + +export PATH=$PATH:/opt/hardhat/devkit/ppc/405/bin +export CPPFLAGS="-I/opt/hardhat/devkit/ppc/405/target/usr/include" +export AR=ppc_405-ar +export AS=ppc_405-as +export LD=ppc_405-ld +export RANLIB=ppc_405-ranlib +export CC=ppc_405-gcc +export NM=ppc_405-nm + +./configure --target=powerpc-hardhat-linux + --host=powerpc-hardhat-linux + --build=i586-pc-linux-gnu + --prefix=/opt/hardhat/devkit/ppc/405/target/usr/local + --exec-prefix=/usr/local +``` You may also need to provide a parameter like `--with-random=/dev/urandom` to configure as it cannot detect the presence of a random number generating @@ -393,10 +472,10 @@ use, here are some other flags that can reduce the size of the library: - `--disable-unix-sockets` (disables support for UNIX sockets) - `--disable-verbose` (eliminates debugging strings and error code strings) - `--disable-versioned-symbols` (disables support for versioned symbols) - - `--enable-hidden-symbols` (eliminates unneeded symbols in the shared library) + - `--enable-symbol-hiding` (eliminates unneeded symbols in the shared library) - `--without-libidn` (disables support for the libidn DNS library) - `--without-librtmp` (disables support for RTMP) - - `--without-ssl` (disables support for SSL/TLS) + - `--without-openssl` (disables support for SSL/TLS) - `--without-zlib` (disables support for on-the-fly decompression) The GNU compiler and linker have a number of options that can reduce the @@ -433,77 +512,25 @@ line. Following is a list of appropriate key words: # PORTS -This is a probably incomplete list of known hardware and operating systems -that curl has been compiled for. If you know a system curl compiles and -runs on, that isn't listed, please let us know! - - - Alpha DEC OSF 4 - - Alpha Digital UNIX v3.2 - - Alpha FreeBSD 4.1, 4.5 - - Alpha Linux 2.2, 2.4 - - Alpha NetBSD 1.5.2 - - Alpha OpenBSD 3.0 - - Alpha OpenVMS V7.1-1H2 - - Alpha Tru64 v5.0 5.1 - - AVR32 Linux - - ARM Android 1.5, 2.1, 2.3, 3.2, 4.x - - ARM INTEGRITY - - ARM iOS - - Cell Linux - - Cell Cell OS - - HP-PA HP-UX 9.X 10.X 11.X - - HP-PA Linux - - HP3000 MPE/iX - - MicroBlaze uClinux - - MIPS IRIX 6.2, 6.5 - - MIPS Linux - - OS/400 - - Pocket PC/Win CE 3.0 - - Power AIX 3.2.5, 4.2, 4.3.1, 4.3.2, 5.1, 5.2 - - PowerPC Darwin 1.0 - - PowerPC INTEGRITY - - PowerPC Linux - - PowerPC Mac OS 9 - - PowerPC Mac OS X - - SH4 Linux 2.6.X - - SH4 OS21 - - SINIX-Z v5 - - Sparc Linux - - Sparc Solaris 2.4, 2.5, 2.5.1, 2.6, 7, 8, 9, 10 - - Sparc SunOS 4.1.X - - StrongARM (and other ARM) RISC OS 3.1, 4.02 - - StrongARM/ARM7/ARM9 Linux 2.4, 2.6 - - StrongARM NetBSD 1.4.1 - - Symbian OS (P.I.P.S.) 9.x - - TPF - - Ultrix 4.3a - - UNICOS 9.0 - - i386 BeOS - - i386 DOS - - i386 eCos 1.3.1 - - i386 Esix 4.1 - - i386 FreeBSD - - i386 HURD - - i386 Haiku OS - - i386 Linux 1.3, 2.0, 2.2, 2.3, 2.4, 2.6 - - i386 Mac OS X - - i386 MINIX 3.1 - - i386 NetBSD - - i386 Novell NetWare - - i386 OS/2 - - i386 OpenBSD - - i386 QNX 6 - - i386 SCO unix - - i386 Solaris 2.7 - - i386 Windows 95, 98, ME, NT, 2000, XP, 2003 - - i486 ncr-sysv4.3.03 (NCR MP-RAS) - - ia64 Linux 2.3.99 - - m68k AmigaOS 3 - - m68k Linux - - m68k uClinux - - m68k OpenBSD - - m88k dg-dgux5.4R3.00 - - s390 Linux - - x86_64 Linux - - XScale/PXA250 Linux 2.4 - - Nios II uClinux +This is a probably incomplete list of known CPU architectures and operating +systems that curl has been compiled for. If you know a system curl compiles +and runs on, that is not listed, please let us know! + +## 85 Operating Systems + +AIX, AmigaOS, Android, Aros, BeOS, Blackberry 10, Blackberry Tablet OS, Cell +OS, ChromeOS, Cisco IOS, Cygwin, Dragonfly BSD, eCOS, FreeBSD, FreeDOS, +FreeRTOS, Fuchsia, Garmin OS, Genode, Haiku, HardenedBSD, HP-UX, Hurd, +Illumos, Integrity, iOS, ipadOS, IRIX, LineageOS, Linux, Lua RTOS, Mac OS 9, +macOS, Mbed, Micrium, MINIX, MorphOS, MPE/iX, MS-DOS, NCR MP-RAS, NetBSD, +Netware, Nintendo Switch, NonStop OS, NuttX, OpenBSD, OpenStep, Orbis OS, +OS/2, OS/400, OS21, Plan 9, PlayStation Portable, QNX, Qubes OS, ReactOS, +Redox, RICS OS, Sailfish OS, SCO Unix, Serenity, SINIX-Z, Solaris, SunOS, +Syllable OS, Symbian, Tizen, TPF, Tru64, tvOS, ucLinux, Ultrix, UNICOS, +UnixWare, VMS, vxWorks, WebOS, Wii system software, Windows, Windows CE, Xbox +System, z/OS, z/TPF, z/VM, z/VSE + +## 22 CPU Architectures + +Alpha, ARC, ARM, AVR32, Cell, HP-PA, Itanium, m68k, MicroBlaze, MIPS, Nios, +OpenRISC, POWER, PowerPC, RISC-V, s390, SH4, SPARC, VAX, x86, x86-64, Xtensa |