2016-10-21 16:55:24 +03:00
# how to install curl and libcurl
## Installing Binary Packages
Lots of people download binary distributions of curl and libcurl. This
document does not describe how to install curl or libcurl using such a binary
package. This document describes how to compile, build and install curl and
libcurl from source code.
2019-09-27 12:37:29 +03:00
## Building using vcpkg
You can download and install curl and libcurl using the [vcpkg ](https://github.com/Microsoft/vcpkg/ ) dependency manager:
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
vcpkg install curl[tool]
2022-09-21 00:30:19 +03:00
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.
2019-09-27 12:37:29 +03:00
2016-10-21 16:55:24 +03:00
## Building from git
If you get your code off a git repository instead of a release tarball, see
the `GIT-INFO` file in the root directory for specific instructions on how to
proceed.
# Unix
2021-10-31 18:34:44 +03:00
A normal Unix installation is made in three or four steps (after you have
2016-10-21 16:55:24 +03:00
unpacked the source archive):
2021-04-15 10:04:30 +03:00
./configure --with-openssl [--with-gnutls --with-wolfssl]
2016-10-21 16:55:24 +03:00
make
make test (optional)
make install
2021-04-15 10:04:30 +03:00
(Adjust the configure line accordingly to use the TLS library you want.)
2016-10-21 16:55:24 +03:00
You probably need to be root when doing the last command.
Get a full listing of all available configure options by invoking it like:
./configure --help
If you want to install curl in a different file hierarchy than `/usr/local` ,
specify that when running configure:
./configure --prefix=/path/to/curl/tree
If you have write permission in that directory, you can do 'make install'
without being root. An example of this would be to make a local install in
your own home directory:
./configure --prefix=$HOME
make
make install
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
2021-10-31 18:34:44 +03:00
path for your compiler/linker, you do not need to do anything special. If you
2018-07-26 04:57:55 +03:00
have OpenSSL installed in `/usr/local/ssl` , you can run configure like:
2016-10-21 16:55:24 +03:00
2021-04-13 19:11:43 +03:00
./configure --with-openssl
2016-10-21 16:55:24 +03:00
2018-07-26 04:57:55 +03:00
If you have OpenSSL installed somewhere else (for example, `/opt/OpenSSL` ) and
2016-10-21 16:55:24 +03:00
you have pkg-config installed, set the pkg-config path first, like this:
2021-04-13 19:11:43 +03:00
env PKG_CONFIG_PATH=/opt/OpenSSL/lib/pkgconfig ./configure --with-openssl
2016-10-21 16:55:24 +03:00
Without pkg-config installed, use this:
2021-04-13 19:11:43 +03:00
./configure --with-openssl=/opt/OpenSSL
2016-10-21 16:55:24 +03:00
2022-11-18 13:25:24 +03:00
If you insist on forcing a build without SSL support, you can run configure
like this:
2016-10-21 16:55:24 +03:00
2021-04-15 10:04:30 +03:00
./configure --without-ssl
2016-10-21 16:55:24 +03:00
If you have OpenSSL installed, but with the libraries in one place and the
2019-05-17 01:11:27 +03:00
header files somewhere else, you have to set the `LDFLAGS` and `CPPFLAGS`
2021-11-26 10:46:59 +03:00
environment variables prior to running configure. Something like this should
2016-10-21 16:55:24 +03:00
work:
CPPFLAGS="-I/path/to/ssl/include" LDFLAGS="-L/path/to/ssl/lib" ./configure
2022-03-29 14:58:11 +03:00
If you have shared SSL libs installed in a directory where your runtime
2021-10-31 18:34:44 +03:00
linker does not find them (which usually causes configure failures), you can
2022-03-29 14:58:11 +03:00
provide this option to gcc to set a hard-coded path to the runtime linker:
2016-10-21 16:55:24 +03:00
2021-04-13 19:11:43 +03:00
LDFLAGS=-Wl,-R/usr/local/ssl/lib ./configure --with-openssl
2016-10-21 16:55:24 +03:00
2022-11-18 13:25:24 +03:00
## Static builds
2016-10-21 16:55:24 +03:00
To force a static library compile, disable the shared library creation by
running configure like:
./configure --disable-shared
2022-11-18 13:25:24 +03:00
The configure script is primarily done to work with shared/dynamic third party
dependencies. When linking with shared libraries, the dependency "chain" is
handled automatically by the library loader - on all modern systems.
2016-10-21 16:55:24 +03:00
2022-11-18 13:25:24 +03:00
If you instead link with a static library, you need to provide all the
dependency libraries already at the link command line.
Figuring out all the dependency libraries for a given library is hard, as it
might involve figuring out the dependencies of the dependencies and they vary
between platforms and change between versions.
When using static dependencies, the build scripts will mostly assume that you,
the user, will provide all the necessary additional dependency libraries as
additional arguments in the build. With configure, by setting `LIBS` or
`LDFLAGS` on the command line.
Building statically is not for the faint of heart.
## Debug
2016-10-21 16:55:24 +03:00
2021-10-31 18:34:44 +03:00
If you are a curl developer and use gcc, you might want to enable more debug
2016-10-21 16:55:24 +03:00
options with the `--enable-debug` option.
curl can be built to use a whole range of libraries to provide various useful
services, and configure will try to auto-detect a decent default. But if you
want to alter it, you can select how to deal with each individual library.
## Select TLS backend
2022-01-27 04:12:50 +03:00
These options are provided to select the TLS backend to use.
2021-04-15 10:04:30 +03:00
- AmiSSL: `--with-amissl`
- BearSSL: `--with-bearssl`
- GnuTLS: `--with-gnutls` .
- mbedTLS: `--with-mbedtls`
- NSS: `--with-nss`
2023-01-18 19:54:30 +03:00
- OpenSSL: `--with-openssl` (also for BoringSSL, AWS-LC, libressl, and quictls)
2021-04-15 10:04:30 +03:00
- rustls: `--with-rustls`
2022-09-21 00:30:19 +03:00
- Schannel: `--with-schannel`
- Secure Transport: `--with-secure-transport`
2021-04-15 10:04:30 +03:00
- wolfSSL: `--with-wolfssl`
2016-10-21 16:55:24 +03:00
2023-02-01 01:29:23 +03:00
You can build curl with *multiple* TLS backends at your choice, but some TLS
backends cannot be combined: if you build with an OpenSSL fork (or wolfSSL),
you cannot add another OpenSSL fork (or wolfSSL) simply because they have
conflicting identical symbol names.
When you build with multiple TLS backends, you can select the active one at
run-time when curl starts up.
2023-04-13 19:15:31 +03:00
## configure finding libs in wrong directory
When the configure script checks for third-party libraries, it adds those
directories to the `LDFLAGS` variable and then tries linking to see if it
works. When successful, the found directory is kept in the `LDFLAGS` variable
when the script continues to execute and do more tests and possibly check for
more libraries.
This can make subsequent checks for libraries wrongly detect another
installation in a directory that was previously added to `LDFLAGS` by another
library check.
2016-10-21 16:55:24 +03:00
# Windows
2022-03-29 14:58:11 +03:00
## Building Windows DLLs and C runtime (CRT) linkage issues
2016-10-21 16:55:24 +03:00
As a general rule, building a DLL with static CRT linkage is highly
discouraged, and intermixing CRTs in the same app is something to avoid at
any cost.
Reading and comprehending Microsoft Knowledge Base articles KB94248 and
KB140584 is a must for any Windows developer. Especially important is full
understanding if you are not going to follow the advice given above.
2019-05-17 01:11:27 +03:00
- [How To Use the C Run-Time ](https://support.microsoft.com/help/94248/how-to-use-the-c-run-time )
- [Run-Time Library Compiler Options ](https://docs.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library )
- [Potential Errors Passing CRT Objects Across DLL Boundaries ](https://docs.microsoft.com/cpp/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries )
2016-10-21 16:55:24 +03:00
2022-09-21 00:30:19 +03:00
If your app is misbehaving in some strange way, or it is suffering from memory
corruption, before asking for further help, please try first to rebuild every
single library your app uses as well as your app using the debug
multi-threaded dynamic C runtime.
2016-10-21 16:55:24 +03:00
If you get linkage errors read section 5.7 of the FAQ document.
2022-09-30 00:29:04 +03:00
## MinGW32
2016-10-21 16:55:24 +03:00
2022-09-30 00:29:04 +03:00
Make sure that MinGW32's bin directory is in the search path, for example:
2016-10-21 16:55:24 +03:00
2020-12-07 20:09:37 +03:00
```cmd
set PATH=c:\mingw32\bin;%PATH%
```
2016-10-21 16:55:24 +03:00
then run `mingw32-make mingw32` in the root dir. There are other
make targets available to build libcurl with more features, use:
- `mingw32-make mingw32-zlib` to build with Zlib support;
- `mingw32-make mingw32-ssl-zlib` to build with SSL and Zlib enabled;
- `mingw32-make mingw32-ssh2-ssl-zlib` to build with SSH2, SSL, Zlib;
- `mingw32-make mingw32-ssh2-ssl-sspi-zlib` to build with SSH2, SSL, Zlib
and SSPI support.
If you have any problems linking libraries or finding header files, be sure
2022-11-22 11:25:05 +03:00
to verify that the provided `Makefile.mk` files use the proper paths, and
2016-10-21 16:55:24 +03:00
adjust as necessary. It is also possible to override these paths with
environment variables, for example:
2020-12-07 20:09:37 +03:00
```cmd
Makefile.m32: delete legacy component bits [ci skip]
- Drop auto-detection of OpenSSL 1.0.2 and earlier. Now always defaulting
to OpenSSL 1.1.0 and later, LibreSSL and BoringSSL.
- Drop `Invalid path to OpenSSL package` detection. OpenSSL has been
using a standard file layout since 1.1.0, so this seems unnecessary
now.
- Drop special logic to enable Novell LDAP SDK support.
- Drop special logic to enable OpenLDAP LDAP SDK support. This seems
to be distinct from native OpenLDAP, with support implemented inside
`lib/ldap.c` (vs. `lib/openldap.c`) back when the latter did not exist
yet in curl.
- Add `-lwldap32` only if there is no other LDAP library (either native
OpenLDAP, or SDKs above) present.
- Update `doc/INSTALL.md` accordingly.
After this patch, it's necessary to make configration changes when using
OpenSSL 1.0.2 or earlier, or the two LDAP SDKs.
OpenSSL 1.0.2 and earlier:
```
export OPENSSL_INCLUDE = <path-to-openssl>/outinc
export OPENSSL_LIBPATH = <path-to-openssl>/out
export OPENSSL_LIBS = -lssl32 -leay32 -lgdi32
```
Novell LDAP SDK, previously enabled via `USE_LDAP_NOVELL=1`:
```
export CURL_CFLAG_EXTRAS = -I<path-to-sdk>/inc -DCURL_HAS_NOVELL_LDAPSDK
export CURL_LDFLAG_EXTRAS = -L<path-to-sdk>/lib/mscvc -lldapsdk -lldapssl -lldapx
```
OpenLDAP LDAP SDK, previously enabled via `USE_LDAP_OPENLDAP=1`:
```
export CURL_CFLAG_EXTRAS = -I<path-to-sdk>/include -DCURL_HAS_OPENLDAP_LDAPSDK
export CURL_LDFLAG_EXTRAS = -L<path-to-sdk>/lib -lldap -llber
```
I haven't tested these scenarios, and in general we recommend using
a recent OpenSSL release. Also, WinLDAP (the Windows default) and
OpenLDAP (via `-DUSE_OPENLDAP`) are the LDAP options actively worked on
in curl.
Closes #9631
2022-10-02 12:34:13 +03:00
set ZLIB_PATH=c:\zlib-1.2.12
set OPENSSL_PATH=c:\openssl-3.0.5
set LIBSSH2_PATH=c:\libssh2-1.10.0
2020-12-07 20:09:37 +03:00
```
2016-10-21 16:55:24 +03:00
2022-09-21 00:30:19 +03:00
It is also possible to build with other LDAP installations 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:
2016-10-21 16:55:24 +03:00
2020-12-07 20:09:37 +03:00
```cmd
Makefile.m32: major rework [ci skip]
This patch overhauls `Makefile.m32` scripts, fixing a list of quirks,
making its behaviour and customization envvars align better with other
build systems, aiming for less code, that is easier to read, use and
maintain.
Details:
- Rename customization envvars:
`CURL_CC` -> `CC`
`CURL_RC` -> `RC`
`CURL_AR` -> `AR`
`CURL_LDFLAG_EXTRAS_DLL` -> `CURL_LDFLAGS_LIB`
`CURL_LDFLAG_EXTRAS_EXE` -> `CURL_LDFLAGS_BIN`
- Drop `CURL_STRIP` and `CURL_RANLIB`. These tools are no longer used.
- Accept `CFLAGS`, `CPPFLAGS`, `RCFLAGS`, `LDFLAGS` and `LIBS` envvars.
- Drop `CURL_CFLAG_EXTRAS`, `CURL_LDFLAG_EXTRAS`, `CURL_RCFLAG_EXTRAS` in
favor of the above.
- Do not automatically enable `zlib` with `libssh2`. `zlib` is optional
with `libssh2`.
- Omit unnecessary `CPPFLAGS` options when building `curl.exe` and
examples.
- Drop support for deprecated `-winssl` `CFG` option. Use `-schannel`
instead.
- Avoid late evaluation where not necessary (`=` -> `:=`).
- Drop support for `CURL_DLL_A_SUFFIX` to override the implib suffix.
Instead, use the standard naming scheme by default: `libcurl.dll.a`.
The toolchain recognizes the name, and selects it automatically when
asking for a `-shared` vs. `-static` build.
- Stop applying `strip` to `libcurl.a`. Follow-up from
16a58e9f93c7e89e1f87720199388bcfcfa148a4. There was no debug info to
strip since then.
- Stop setting `-O3`, `-W`, `-Wall` options. You can add these to
`CFLAGS` as desired.
- Always enable `-DCURL_DISABLE_OPENSSL_AUTO_LOAD_CONFIG` with OpenSSL,
to avoid that vulnerability on Windows.
- Add `-lbrotlicommon` to `LIBS` when using `brotli`.
- Do not enable `-nghttp3` without `-ngtcp2`.
- `-ssh2` and `-rtmp` options no longer try to auto-select a TLS-backend.
You need to set the backend explicitly. This scales better and avoids
issues with certain combinations (e.g. `libssh2` + `wolfssl` with no
`schannel`).
- Default to OpenSSL TLS-backend with `ngtcp2`. Possible to override via
`NGTCP2_LIBS`.
- Old, alternate method of enabling components (e.g. `SSH2=1`) no longer
supported.
- Delete `SPNEGO` references. They were no-ops.
- Drop support for Win9x environments.
- Allow setting `OPENSSL_LIBS` independently from `OPENSSL_LIBPATH`.
- Support autotools/CMake `libssh2` builds by default.
- Respect `CURL_DLL_SUFFIX` in `-dyn` mode when building `curl.exe` and
examples.
- Assume standard directory layout with `LIBCARES_PATH`. (Instead of the
long gone embedded one.)
- Stop static linking with c-ares by default. Add
`CPPFLAGS=-DCARES_STATICLIB` to enable it.
- Reorganize internal layout to avoid redundancy and emit clean diffs
between src/lib and example make files.
- Delete unused variables.
- Code cleanups/rework.
- Comment and indentation fixes.
Closes #9632
2022-10-03 22:46:56 +03:00
set CPPFLAGS=-Ic:/openldap/include -DCURL_HAS_OPENLDAP_LDAPSDK
set LDFLAGS=-Lc:/openldap/lib
set LIBS=-lldap -llber
2020-12-07 20:09:37 +03:00
```
2016-10-21 16:55:24 +03:00
or for using the Novell SDK:
2020-12-07 20:09:37 +03:00
```cmd
Makefile.m32: major rework [ci skip]
This patch overhauls `Makefile.m32` scripts, fixing a list of quirks,
making its behaviour and customization envvars align better with other
build systems, aiming for less code, that is easier to read, use and
maintain.
Details:
- Rename customization envvars:
`CURL_CC` -> `CC`
`CURL_RC` -> `RC`
`CURL_AR` -> `AR`
`CURL_LDFLAG_EXTRAS_DLL` -> `CURL_LDFLAGS_LIB`
`CURL_LDFLAG_EXTRAS_EXE` -> `CURL_LDFLAGS_BIN`
- Drop `CURL_STRIP` and `CURL_RANLIB`. These tools are no longer used.
- Accept `CFLAGS`, `CPPFLAGS`, `RCFLAGS`, `LDFLAGS` and `LIBS` envvars.
- Drop `CURL_CFLAG_EXTRAS`, `CURL_LDFLAG_EXTRAS`, `CURL_RCFLAG_EXTRAS` in
favor of the above.
- Do not automatically enable `zlib` with `libssh2`. `zlib` is optional
with `libssh2`.
- Omit unnecessary `CPPFLAGS` options when building `curl.exe` and
examples.
- Drop support for deprecated `-winssl` `CFG` option. Use `-schannel`
instead.
- Avoid late evaluation where not necessary (`=` -> `:=`).
- Drop support for `CURL_DLL_A_SUFFIX` to override the implib suffix.
Instead, use the standard naming scheme by default: `libcurl.dll.a`.
The toolchain recognizes the name, and selects it automatically when
asking for a `-shared` vs. `-static` build.
- Stop applying `strip` to `libcurl.a`. Follow-up from
16a58e9f93c7e89e1f87720199388bcfcfa148a4. There was no debug info to
strip since then.
- Stop setting `-O3`, `-W`, `-Wall` options. You can add these to
`CFLAGS` as desired.
- Always enable `-DCURL_DISABLE_OPENSSL_AUTO_LOAD_CONFIG` with OpenSSL,
to avoid that vulnerability on Windows.
- Add `-lbrotlicommon` to `LIBS` when using `brotli`.
- Do not enable `-nghttp3` without `-ngtcp2`.
- `-ssh2` and `-rtmp` options no longer try to auto-select a TLS-backend.
You need to set the backend explicitly. This scales better and avoids
issues with certain combinations (e.g. `libssh2` + `wolfssl` with no
`schannel`).
- Default to OpenSSL TLS-backend with `ngtcp2`. Possible to override via
`NGTCP2_LIBS`.
- Old, alternate method of enabling components (e.g. `SSH2=1`) no longer
supported.
- Delete `SPNEGO` references. They were no-ops.
- Drop support for Win9x environments.
- Allow setting `OPENSSL_LIBS` independently from `OPENSSL_LIBPATH`.
- Support autotools/CMake `libssh2` builds by default.
- Respect `CURL_DLL_SUFFIX` in `-dyn` mode when building `curl.exe` and
examples.
- Assume standard directory layout with `LIBCARES_PATH`. (Instead of the
long gone embedded one.)
- Stop static linking with c-ares by default. Add
`CPPFLAGS=-DCARES_STATICLIB` to enable it.
- Reorganize internal layout to avoid redundancy and emit clean diffs
between src/lib and example make files.
- Delete unused variables.
- Code cleanups/rework.
- Comment and indentation fixes.
Closes #9632
2022-10-03 22:46:56 +03:00
set CPPFLAGS=-Ic:/openldapsdk/inc -DCURL_HAS_NOVELL_LDAPSDK
set LDFLAGS=-Lc:/openldapsdk/lib/mscvc
set LIBS=-lldapsdk -lldapssl -lldapx
2020-12-07 20:09:37 +03:00
```
2016-10-21 16:55:24 +03:00
2022-11-22 11:25:05 +03:00
If you want to enable LDAPS support then append `-ldaps` to the make target.
2016-10-21 16:55:24 +03:00
## Cygwin
2022-04-21 18:05:36 +03:00
Almost identical to the Unix installation. Run the configure script in the
2019-05-17 01:11:27 +03:00
curl source tree root with `sh configure` . Make sure you have the `sh`
2021-10-31 18:34:44 +03:00
executable in `/bin/` or you will see the configure fail toward the end.
2016-10-21 16:55:24 +03:00
Run `make`
2022-11-22 11:25:05 +03:00
## MS-DOS
Requires DJGPP in the search path and pointing to the Watt-32 stack via
`WATT_PATH=c:/djgpp/net/watt` .
Run `make -f Makefile.dist djgpp` in the root curl dir.
For build configuration options, please see the MinGW32 section.
Notes:
- DJGPP 2.04 beta has a `sscanf()` bug so the URL parsing is not done
properly. Use DJGPP 2.03 until they fix it.
- Compile Watt-32 (and OpenSSL) with the same version of DJGPP. Otherwise
things go wrong because things like FS-extensions and `errno` values have
been changed between releases.
## AmigaOS
Run `make -f Makefile.dist amiga` in the root curl dir.
For build configuration options, please see the MinGW32 section.
2016-10-21 16:55:24 +03:00
## Disabling Specific Protocols in Windows builds
The configure utility, unfortunately, is not available for the Windows
environment, therefore, you cannot use the various disable-protocol options of
the configure utility on this platform.
2019-11-11 19:16:04 +03:00
You can use specific defines to disable specific protocols and features. See
2022-09-21 00:30:19 +03:00
[CURL-DISABLE ](CURL-DISABLE.md ) for the full list.
2016-10-21 16:55:24 +03:00
If you want to set any of these defines you have the following options:
2019-05-17 01:11:27 +03:00
- Modify `lib/config-win32.h`
- Modify `lib/curl_setup.h`
- Modify `winbuild/Makefile.vc`
2016-10-21 16:55:24 +03:00
- Modify the "Preprocessor Definitions" in the libcurl project
Note: The pre-processor settings can be found using the Visual Studio IDE
2022-02-13 13:29:49 +03:00
under "Project -> Properties -> Configuration Properties -> C/C++ ->
Preprocessor".
2016-10-21 16:55:24 +03:00
## Using BSD-style lwIP instead of Winsock TCP/IP stack in Win32 builds
In order to compile libcurl and curl using BSD-style lwIP TCP/IP stack it is
2022-01-27 04:12:50 +03:00
necessary to make the definition of the preprocessor symbol `USE_LWIPSOCK`
visible to libcurl and curl compilation processes. To set this definition you
have the following alternatives:
2016-10-21 16:55:24 +03:00
2019-05-17 01:11:27 +03:00
- Modify `lib/config-win32.h` and `src/config-win32.h`
- Modify `winbuild/Makefile.vc`
2016-10-21 16:55:24 +03:00
- Modify the "Preprocessor Definitions" in the libcurl project
Note: The pre-processor settings can be found using the Visual Studio IDE
2022-02-13 13:29:49 +03:00
under "Project -> Properties -> Configuration Properties -> C/C++ ->
Preprocessor".
2016-10-21 16:55:24 +03:00
Once that libcurl has been built with BSD-style lwIP TCP/IP stack support, in
order to use it with your program it is mandatory that your program includes
lwIP header file `<lwip/opt.h>` (or another lwIP header that includes this)
before including any libcurl header. Your program does not need the
`USE_LWIPSOCK` preprocessor definition which is for libcurl internals only.
2022-09-21 00:30:19 +03:00
Compilation has been verified with lwIP 1.4.0.
2016-10-21 16:55:24 +03:00
This BSD-style lwIP TCP/IP stack support must be considered experimental given
that it has been verified that lwIP 1.4.0 still needs some polish, and libcurl
2022-09-21 00:30:19 +03:00
might yet need some additional adjustment.
2016-10-21 16:55:24 +03:00
## Important static libcurl usage note
When building an application that uses the static libcurl library on Windows,
2021-11-26 10:46:59 +03:00
you must add `-DCURL_STATICLIB` to your `CFLAGS` . Otherwise the linker will
2016-10-21 16:55:24 +03:00
look for dynamic import symbols.
## Legacy Windows and SSL
2019-05-17 01:11:27 +03:00
Schannel (from Windows SSPI), is the native SSL library in Windows. However,
Schannel in Windows < = XP is unable to connect to servers that
2016-10-21 16:55:24 +03:00
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.
2021-04-07 12:05:47 +03:00
# Apple Platforms (macOS, iOS, tvOS, watchOS, and their simulator counterparts)
2016-10-21 16:55:24 +03:00
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
2022-09-02 00:39:34 +03:00
Transport for SSL/TLS, use the configure option `--with-secure-transport` .
2016-10-21 16:55:24 +03:00
When Secure Transport is in use, the curl options `--cacert` and `--capath`
and their libcurl equivalents, will be ignored, because Secure Transport uses
the certificates stored in the Keychain to evaluate whether or not to trust
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.
2021-04-07 12:05:47 +03:00
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:
2016-10-21 16:55:24 +03:00
2020-12-07 20:09:37 +03:00
```bash
2021-04-07 12:05:47 +03:00
# 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"
2021-06-06 13:12:01 +03:00
./configure --host=$ARCH-apple-darwin --prefix $(pwd)/artifacts --with-secure-transport
2021-04-07 12:05:47 +03:00
make -j8
make install
2020-12-07 20:09:37 +03:00
```
2016-10-21 16:55:24 +03:00
2021-04-07 12:05:47 +03:00
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"
2021-06-06 13:12:01 +03:00
./configure --host=$ARCH-apple-darwin --prefix $(pwd)/artifacts --with-secure-transport
2021-04-07 12:05:47 +03:00
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"
2021-06-06 13:12:01 +03:00
./configure --host=$ARCH-apple-darwin --prefix $(pwd)/artifacts --with-secure-transport
2021-04-07 12:05:47 +03:00
make -j8
make install
```
2022-01-27 04:12:50 +03:00
In all above, the built libraries and executables can be found in the
`artifacts` folder.
2021-04-07 12:05:47 +03:00
2019-11-17 00:05:43 +03:00
# Android
2022-10-14 05:25:05 +03:00
When building curl for Android it's recommended to use a Linux/macOS environment
2019-11-17 00:05:43 +03:00
since using curl's `configure` script is the easiest way to build curl
for Android. Before you can build curl for Android, you need to install the
Android NDK first. This can be done using the SDK Manager that is part of
Android Studio. Once you have installed the Android NDK, you need to figure out
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:
2020-12-07 20:09:37 +03:00
```bash
2022-10-14 05:25:05 +03:00
export ANDROID_NDK_HOME=~/Library/Android/sdk/ndk/25.1.8937393 # Point into your NDK.
export HOST_TAG=darwin-x86_64 # Same tag for Apple Silicon. Other OS values here: https://developer.android.com/ndk/guides/other_build_systems#overview
export TOOLCHAIN=$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/$HOST_TAG
export AR=$TOOLCHAIN/bin/llvm-ar
export AS=$TOOLCHAIN/bin/llvm-as
export CC=$TOOLCHAIN/bin/aarch64-linux-android21-clang
export CXX=$TOOLCHAIN/bin/aarch64-linux-android21-clang++
export LD=$TOOLCHAIN/bin/ld
export RANLIB=$TOOLCHAIN/bin/llvm-ranlib
export STRIP=$TOOLCHAIN/bin/llvm-strip
2020-12-07 20:09:37 +03:00
```
2019-11-17 00:05:43 +03:00
2019-11-28 14:57:58 +03:00
When building on Linux or targeting other API levels or architectures, you need
2019-11-17 00:05:43 +03:00
to adjust those variables accordingly. After that you can build curl like this:
./configure --host aarch64-linux-android --with-pic --disable-shared
2021-10-31 18:34:44 +03:00
Note that this will not give you SSL/TLS support. If you need SSL/TLS, you have
2019-11-17 00:05:43 +03:00
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:
2021-04-13 19:11:43 +03:00
2022-10-14 05:25:05 +03:00
```bash
2023-05-22 00:27:43 +03:00
LIBS="-lssl -lcrypto -lc++" # For OpenSSL/BoringSSL. In general, you will need to the SSL/TLS layer's transitive dependencies if you are linking statically.
2022-10-14 05:25:05 +03:00
./configure --host aarch64-linux-android --with-pic --disable-shared --with-openssl="$TOOLCHAIN/sysroot/usr"
```
2019-11-17 00:05:43 +03:00
2021-05-05 17:39:37 +03:00
# IBM i
For IBM i (formerly OS/400), you can use curl in two different ways:
2021-05-18 19:55:55 +03:00
- Natively, running in the **ILE** . The obvious use is being able to call curl
2021-05-05 17:39:37 +03:00
from ILE C or RPG applications.
2021-05-18 19:55:55 +03:00
- You will need to build this from source. See `packages/OS400/README` for
2021-05-05 17:39:37 +03:00
the ILE specific build instructions.
2021-05-18 19:55:55 +03:00
- In the **PASE** environment, which runs AIX programs. curl will be built as
2021-05-05 17:39:37 +03:00
it would be on AIX.
2021-05-18 19:55:55 +03:00
- IBM provides builds of curl in their Yum repository for PASE software.
- To build from source, follow the Unix instructions.
2021-05-05 17:39:37 +03:00
There are some additional limitations and quirks with curl on this platform;
they affect both environments.
2022-09-21 00:30:19 +03:00
## Multi-threading notes
2021-05-05 17:39:37 +03:00
2021-10-31 18:34:44 +03:00
By default, jobs in IBM i will not start with threading enabled. (Exceptions
2021-05-05 17:39:37 +03:00
include interactive PASE sessions started by `QP2TERM` or SSH.) If you use
2022-09-21 00:30:19 +03:00
curl in an environment without threading when options like asynchronous DNS
were enabled, you will get messages like:
2021-05-05 17:39:37 +03:00
```
getaddrinfo() thread failed to start
```
2021-11-26 10:46:59 +03:00
Do not panic. curl and your program are not broken. You can fix this by:
2021-05-05 17:39:37 +03:00
2021-05-18 19:55:55 +03:00
- Set the environment variable `QIBM_MULTI_THREADED` to `Y` before starting
2021-05-05 17:39:37 +03:00
your program. This can be done at whatever scope you feel is appropriate.
2021-05-18 19:55:55 +03:00
- Alternatively, start the job with the `ALWMLTTHD` parameter set to `*YES` .
2021-05-05 17:39:37 +03:00
2016-10-21 16:55:24 +03:00
# Cross compile
Download and unpack the curl package.
2019-05-17 01:11:27 +03:00
`cd` to the new directory. (e.g. `cd curl-7.12.3` )
2016-10-21 16:55:24 +03:00
Set environment variables to point to the cross-compile toolchain and call
2021-11-26 10:46:59 +03:00
configure with any options you need. Be sure and specify the `--host` and
2022-09-21 00:30:19 +03:00
`--build` parameters at configuration time. The following script is an example
of cross-compiling for the IBM 405GP PowerPC processor using the toolchain on
Linux.
2016-10-21 16:55:24 +03:00
2020-12-07 20:09:37 +03:00
```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
```
2016-10-21 16:55:24 +03:00
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
2021-11-26 10:46:59 +03:00
device for a target system. The `--prefix` parameter specifies where curl
will be installed. If `configure` completes successfully, do `make` and `make
2016-10-21 16:55:24 +03:00
install` as usual.
In some cases, you may be able to simplify the above commands to as little as:
./configure --host=ARCH-OS
# REDUCING SIZE
There are a number of configure options that can be used to reduce the size of
libcurl for embedded applications where binary size is an important factor.
2019-05-17 01:11:27 +03:00
First, be sure to set the `CFLAGS` variable when configuring with any relevant
2021-11-26 10:46:59 +03:00
compiler optimization flags to reduce the size of the binary. For gcc, this
2016-10-21 16:55:24 +03:00
would mean at minimum the -Os option, and potentially the `-march=X` ,
`-mdynamic-no-pic` and `-flto` options as well, e.g.
./configure CFLAGS='-Os' LDFLAGS='-Wl,-Bsymbolic'...
Note that newer compilers often produce smaller code than older versions
due to improved optimization.
Be sure to specify as many `--disable-` and `--without-` flags on the
configure command-line as you can to disable all the libcurl features that you
2021-11-26 10:46:59 +03:00
know your application is not going to need. Besides specifying the
2016-10-21 16:55:24 +03:00
`--disable-PROTOCOL` flags for all the types of URLs your application will not
2021-12-01 05:33:49 +03:00
use, here are some other flags that can reduce the size of the library by
disabling support for some feature:
2022-09-21 00:30:19 +03:00
- `--disable-alt-svc` (HTTP Alt-Svc)
2021-12-01 05:33:49 +03:00
- `--disable-ares` (the C-ARES DNS library)
- `--disable-cookies` (HTTP cookies)
- `--disable-crypto-auth` (cryptographic authentication)
- `--disable-dateparse` (date parsing for time conditionals)
- `--disable-dnsshuffle` (internal server load spreading)
- `--disable-doh` (DNS-over-HTTP)
- `--disable-get-easy-options` (lookup easy options at runtime)
- `--disable-hsts` (HTTP Strict Transport Security)
- `--disable-http-auth` (all HTTP authentication)
- `--disable-ipv6` (IPv6)
- `--disable-libcurl-option` (--libcurl C code generation support)
- `--disable-manual` (built-in documentation)
- `--disable-netrc` (.netrc file)
- `--disable-ntlm-wb` (NTLM WinBind)
- `--disable-progress-meter` (graphical progress meter in library)
- `--disable-proxy` (HTTP and SOCKS proxies)
2022-09-21 00:30:19 +03:00
- `--disable-pthreads` (multi-threading)
- `--disable-socketpair` (socketpair for asynchronous name resolving)
2021-12-01 05:33:49 +03:00
- `--disable-threaded-resolver` (threaded name resolver)
- `--disable-tls-srp` (Secure Remote Password authentication for TLS)
- `--disable-unix-sockets` (UNIX sockets)
2016-10-21 16:55:24 +03:00
- `--disable-verbose` (eliminates debugging strings and error code strings)
2021-12-01 05:33:49 +03:00
- `--disable-versioned-symbols` (versioned symbols)
2021-10-21 22:57:33 +03:00
- `--enable-symbol-hiding` (eliminates unneeded symbols in the shared library)
2021-12-01 05:33:49 +03:00
- `--without-brotli` (Brotli on-the-fly decompression)
- `--without-libpsl` (Public Suffix List in cookies)
- `--without-nghttp2` (HTTP/2 using nghttp2)
- `--without-ngtcp2` (HTTP/2 using ngtcp2)
- `--without-zstd` (Zstd on-the-fly decompression)
- `--without-libidn2` (internationalized domain names)
- `--without-librtmp` (RTMP)
- `--without-ssl` (SSL/TLS)
- `--without-zlib` (on-the-fly decompression)
2016-10-21 16:55:24 +03:00
The GNU compiler and linker have a number of options that can reduce the
size of the libcurl dynamic libraries on some platforms even further.
2019-05-17 01:11:27 +03:00
Specify them by providing appropriate `CFLAGS` and `LDFLAGS` variables on
the configure command-line, e.g.
2016-10-21 16:55:24 +03:00
CFLAGS="-Os -ffunction-sections -fdata-sections
-fno-unwind-tables -fno-asynchronous-unwind-tables -flto"
LDFLAGS="-Wl,-s -Wl,-Bsymbolic -Wl,--gc-sections"
Be sure also to strip debugging symbols from your binaries after compiling
2021-11-26 10:46:59 +03:00
using 'strip' (or the appropriate variant if cross-compiling). If space is
2016-10-21 16:55:24 +03:00
really tight, you may be able to remove some unneeded sections of the shared
library using the -R option to objcopy (e.g. the .comment section).
2021-12-01 05:33:49 +03:00
Using these techniques it is possible to create a basic HTTP-only libcurl
shared library for i386 Linux platforms that is only 133 KiB in size
(as of libcurl version 7.80.0, using gcc 11.2.0).
2016-10-21 16:55:24 +03:00
You may find that statically linking libcurl to your application will result
in a lower total size than dynamically linking.
Note that the curl test harness can detect the use of some, but not all, of
the `--disable` statements suggested above. Use will cause tests relying on
2021-11-26 10:46:59 +03:00
those features to fail. The test harness can be manually forced to skip the
2019-05-17 01:11:27 +03:00
relevant tests by specifying certain key words on the `runtests.pl` command
2021-12-01 05:33:49 +03:00
line. Following is a list of appropriate key words for those configure options
2022-04-21 18:05:36 +03:00
that are not automatically detected:
2016-10-21 16:55:24 +03:00
- `--disable-cookies` !cookies
2022-09-21 00:30:19 +03:00
- `--disable-dateparse` !RETRY-AFTER !`CURLOPT_TIMECONDITION` !`CURLINFO_FILETIME` !`If-Modified-Since` !`curl_getdate` !`-z`
- `--disable-libcurl-option` !`--libcurl`
2021-12-01 05:33:49 +03:00
- `--disable-verbose` !verbose\ logs
2016-10-21 16:55:24 +03:00
# PORTS
2020-12-24 02:13:09 +03:00
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
2021-10-31 18:34:44 +03:00
and runs on, that is not listed, please let us know!
2020-12-24 02:13:09 +03:00
2022-11-28 19:16:37 +03:00
## 92 Operating Systems
2020-12-24 02:13:09 +03:00
2022-11-29 12:02:47 +03:00
AIX, AmigaOS, Android, Aros, BeOS, Blackberry 10, Blackberry Tablet OS,
Cell OS, Chrome OS, Cisco IOS, Cygwin, DG/UX, Dragonfly BSD, DR DOS, eCOS,
FreeBSD, FreeDOS, FreeRTOS, Fuchsia, Garmin OS, Genode, Haiku, HardenedBSD,
HP-UX, Hurd, Illumos, Integrity, iOS, ipadOS, IRIX, 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, Omni OS, OpenBSD,
OpenStep, Orbis OS, OS/2, OS/400, OS21, Plan 9, PlayStation Portable, QNX,
Qubes OS, ReactOS, Redox, RICS OS, RTEMS, Sailfish OS, SCO Unix, Serenity,
SINIX-Z, Solaris, SunOS, Syllable OS, Symbian, Tizen, TPF, Tru64, tvOS,
ucLinux, Ultrix, UNICOS, UnixWare, VMS, vxWorks, watchOS, WebOS,
Wii system software, Windows, Windows CE, Xbox System, Xenix, Zephyr,
z/OS, z/TPF, z/VM, z/VSE
## 26 CPU Architectures
Alpha, ARC, ARM, AVR32, CompactRISC, Elbrus, ETRAX, HP-PA, Itanium,
LoongArch, m68k, m88k, MicroBlaze, MIPS, Nios, OpenRISC, POWER, PowerPC,
RISC-V, s390, SH4, SPARC, Tilera, VAX, x86, Xtensa