romenskiy2012/curl
1
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-07-31 04:28:04 +03:00
Code Issues Projects Releases Packages Wiki Activity

cmake: document -D and env build options

Browse source 
Extend `INSTALL-CMAKE` document with the list of available options,
a short description and default values.

The list may not be 100% complete.

There are no component boundaries in CMake, so the line is blurry
between curl options, CMake options, CMake Find modules options.
I included certain CMake options that seemed useful, and/or have
dedicated use withing curl's CMake source. But, all CMake built-in
options are usable, as documented upstream in CMake.

The naming of the options has a heritage and the inconsistencies with
it, including a lack of clear namespace. This may be subject to future
updates, also after figuring out which name has special meaning within
CMake and/or CMake projects out of unwritten convention or something
more tangible.

CMake allows to initialize any internal variable via `-D`. This may be
useful to pre-initialize/override feature check results. The list
doesn't contain these, and they remain officially undocumented.

Also:
- make adjustments to keep the spellchecker happy.
- retrofit description changes to the cmake sources.
- stop documenting deprecated `Find*` variables.

Reported-by: Daniel Stenberg
Fixes https://github.com/curl/curl/discussions/14885
Closes #15388
This commit is contained in:
Viktor Szakats 2024-10-24 02:04:22 +02:00
parent ffc4e6a886
commit f66af623cf
No known key found for this signature in database
GPG key ID: B5ABD165E2AEF201
27 changed files with 392 additions and 173 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/CURL-DISABLE.md
View file

@ -40,7 +40,7 @@ Disable support for the negotiate authentication methods.
## `CURL_DISABLE_AWS`
Disable **AWS-SIG4** support.
Disable **aws-sigv4** support.
## `CURL_DISABLE_CA_SEARCH`

223
docs/INSTALL-CMAKE.md
View file

@ -138,3 +138,226 @@ assumes that CMake generates `Makefile`:
$ cd ../curl-build
$ make install
# CMake build options
- `BUILD_CURL_EXE`: Build curl executable. Default: `ON`
- `BUILD_EXAMPLES`: Build libcurl examples. Default: `ON`
- `BUILD_LIBCURL_DOCS`: Build libcurl man pages. Default: `ON`
- `BUILD_MISC_DOCS`: Build misc man pages (e.g. `curl-config` and `mk-ca-bundle`). Default: `ON`
- `BUILD_SHARED_LIBS`: Build shared libraries. Default: `ON`
- `BUILD_STATIC_CURL`: Build curl executable with static libcurl. Default: `OFF`
- `BUILD_STATIC_LIBS`: Build static libraries. Default: `OFF`
- `BUILD_TESTING`: Build tests. Default: `ON`
- `CURL_DEFAULT_SSL_BACKEND`: Override default TLS backend in MultiSSL builds.
Accepted values in order of default priority:
`wolfssl`, `gnutls`, `mbedtls`, `openssl`, `secure-transport`, `schannel`, `bearssl`, `rustls`
- `CURL_ENABLE_EXPORT_TARGET`: Enable CMake export target. Default: `ON`
- `CURL_HIDDEN_SYMBOLS`: Hide libcurl internal symbols (=hide all symbols that are not officially external). Default: `ON`
- `CURL_LIBCURL_SOVERSION`: Enable libcurl SOVERSION. Default: `ON` for supported platforms
- `CURL_LIBCURL_VERSIONED_SYMBOLS`: Enable libcurl versioned symbols. Default: `OFF`
- `CURL_LIBCURL_VERSIONED_SYMBOLS_PREFIX`: Override default versioned symbol prefix. Default: `<TLS-BACKEND>_` or `MULTISSL_`
- `CURL_LTO`: Enable compiler Link Time Optimizations. Default: `OFF`
- `CURL_STATIC_CRT`: Build libcurl with static CRT with MSVC (`/MT`). Default: `OFF`
- `CURL_TARGET_WINDOWS_VERSION`: Minimum target Windows version as hex string.
- `CURL_TEST_BUNDLES`: Bundle `libtest` and `unittest` tests into single binaries. Default: `OFF`
- `CURL_WERROR`: Turn compiler warnings into errors. Default: `OFF`
- `ENABLE_CURLDEBUG`: Enable TrackMemory feature: Default: =`ENABLE_DEBUG`
- `ENABLE_CURL_MANUAL`: Build the man page for curl and enable its `-M`/`--manual` option. Default: `ON`
- `ENABLE_DEBUG`: Enable curl debug features. Default: `OFF`
- `IMPORT_LIB_SUFFIX`: Import library suffix. Default: `_imp`
- `LIBCURL_OUTPUT_NAME`: Basename of the curl library. Default: `libcurl`
- `PICKY_COMPILER`: Enable picky compiler options. Default: `ON`
- `STATIC_LIB_SUFFIX`: Static library suffix. Default: (empty)
## CA bundle options
- `CURL_CA_BUNDLE`: Path to the CA bundle. Set `none` to disable or `auto` for auto-detection. Default: `auto`
- `CURL_CA_EMBED`: Path to the CA bundle to embed in the curl tool. Default: (disabled)
- `CURL_CA_FALLBACK`: Use built-in CA store of TLS backend. Default: `OFF`
- `CURL_CA_PATH`: Location of default CA path. Set `none` to disable or `auto` for auto-detection. Default: `auto`
- `CURL_CA_SEARCH_SAFE`: Enable safe CA bundle search (within the curl tool directory) on Windows. Default: `OFF`
## Enabling features
- `CURL_ENABLE_SSL`: Enable SSL support. Default: `ON`
- `CURL_WINDOWS_SSPI`: Enable SSPI on Windows. Default: =`CURL_USE_SCHANNEL`
- `ENABLE_IPV6`: Enable IPv6 support. Default: `ON`
- `ENABLE_THREADED_RESOLVER`: Enable threaded DNS lookup. Default: `ON` if c-ares is not enabled
- `ENABLE_UNICODE`: Use the Unicode version of the Windows API functions. Default: `OFF`
- `ENABLE_UNIX_SOCKETS`: Enable Unix domain sockets support. Default: `ON`
- `USE_ECH`: Enable ECH support. Default: `OFF`
- `USE_HTTPSRR`: Enable HTTPS RR support for ECH (experimental). Default: `OFF`
- `USE_OPENSSL_QUIC`: Use OpenSSL and nghttp3 libraries for HTTP/3 support. Default: `OFF`
## Disabling features
- `CURL_DISABLE_ALTSVC`: Disable alt-svc support. Default: `OFF`
- `CURL_DISABLE_AWS`: Disable **aws-sigv4**. Default: `OFF`
- `CURL_DISABLE_BASIC_AUTH`: Disable Basic authentication. Default: `OFF`
- `CURL_DISABLE_BEARER_AUTH`: Disable Bearer authentication. Default: `OFF`
- `CURL_DISABLE_BINDLOCAL`: Disable local binding support. Default: `OFF`
- `CURL_DISABLE_CA_SEARCH`: Disable unsafe CA bundle search in PATH on Windows. Default: `OFF`
- `CURL_DISABLE_COOKIES`: Disable cookies support. Default: `OFF`
- `CURL_DISABLE_DICT`: Disable DICT. Default: `OFF`
- `CURL_DISABLE_DIGEST_AUTH`: Disable Digest authentication. Default: `OFF`
- `CURL_DISABLE_DOH`: Disable DNS-over-HTTPS. Default: `OFF`
- `CURL_DISABLE_FILE`: Disable FILE. Default: `OFF`
- `CURL_DISABLE_FORM_API`: Disable **form-api**: Default: =`CURL_DISABLE_MIME`
- `CURL_DISABLE_FTP`: Disable FTP. Default: `OFF`
- `CURL_DISABLE_GETOPTIONS`: Disable `curl_easy_options` API for existing options to `curl_easy_setopt`. Default: `OFF`
- `CURL_DISABLE_GOPHER`: Disable Gopher. Default: `OFF`
- `CURL_DISABLE_HEADERS_API`: Disable **headers-api** support. Default: `OFF`
- `CURL_DISABLE_HSTS`: Disable HSTS support. Default: `OFF`
- `CURL_DISABLE_HTTP`: Disable HTTP. Default: `OFF`
- `CURL_DISABLE_HTTP_AUTH`: Disable all HTTP authentication methods. Default: `OFF`
- `CURL_DISABLE_IMAP`: Disable IMAP. Default: `OFF`
- `CURL_DISABLE_INSTALL`: Disable installation targets. Default: `OFF`
- `CURL_DISABLE_IPFS`: Disable IPFS. Default: `OFF`
- `CURL_DISABLE_KERBEROS_AUTH`: Disable Kerberos authentication. Default: `OFF`
- `CURL_DISABLE_LDAP`: Disable LDAP. Default: `OFF`
- `CURL_DISABLE_LDAPS`: Disable LDAPS. Default: =`CURL_DISABLE_LDAP`
- `CURL_DISABLE_LIBCURL_OPTION`: Disable `--libcurl` option from the curl tool. Default: `OFF`
- `CURL_DISABLE_MIME`: Disable MIME support. Default: `OFF`
- `CURL_DISABLE_MQTT`: Disable MQTT. Default: `OFF`
- `CURL_DISABLE_NEGOTIATE_AUTH`: Disable negotiate authentication. Default: `OFF`
- `CURL_DISABLE_NETRC`: Disable netrc parser. Default: `OFF`
- `CURL_DISABLE_NTLM`: Disable NTLM support. Default: `OFF`
- `CURL_DISABLE_OPENSSL_AUTO_LOAD_CONFIG`: Disable automatic loading of OpenSSL configuration. Default: `OFF`
- `CURL_DISABLE_PARSEDATE`: Disable date parsing. Default: `OFF`
- `CURL_DISABLE_POP3`: Disable POP3. Default: `OFF`
- `CURL_DISABLE_PROGRESS_METER`: Disable built-in progress meter. Default: `OFF`
- `CURL_DISABLE_PROXY`: Disable proxy support. Default: `OFF`
- `CURL_DISABLE_RTSP`: Disable RTSP. Default: `OFF`
- `CURL_DISABLE_SHA512_256`: Disable SHA-512/256 hash algorithm. Default: `OFF`
- `CURL_DISABLE_SHUFFLE_DNS`: Disable shuffle DNS feature. Default: `OFF`
- `CURL_DISABLE_SMB`: Disable SMB. Default: `OFF`
- `CURL_DISABLE_SMTP`: Disable SMTP. Default: `OFF`
- `CURL_DISABLE_SOCKETPAIR`: Disable use of socketpair for curl_multi_poll. Default: `OFF`
- `CURL_DISABLE_SRP`: Disable TLS-SRP support. Default: `OFF`
- `CURL_DISABLE_TELNET`: Disable Telnet. Default: `OFF`
- `CURL_DISABLE_TFTP`: Disable TFTP. Default: `OFF`
- `CURL_DISABLE_VERBOSE_STRINGS`: Disable verbose strings. Default: `OFF`
- `CURL_DISABLE_WEBSOCKETS`: Disable WebSocket. Default: `OFF`
- `HTTP_ONLY`: Disable all protocols except HTTP (This overrides all `CURL_DISABLE_*` options). Default: `OFF`
## Environment
- `CI`: Assume running under CI if set.
- `CURL_BUILDINFO`: Print `buildinfo.txt` if set.
- `CURL_CI`: Assume running under CI if set.
## CMake options
- `CMAKE_DEBUG_POSTFIX`: Default: `-d`
- `CMAKE_IMPORT_LIBRARY_SUFFIX` (see CMake)
- `CMAKE_INSTALL_BINDIR` (see CMake)
- `CMAKE_INSTALL_INCLUDEDIR` (see CMake)
- `CMAKE_INSTALL_LIBDIR` (see CMake)
- `CMAKE_INSTALL_PREFIX` (see CMake)
- `CMAKE_STATIC_LIBRARY_SUFFIX` (see CMake)
- `CMAKE_UNITY_BUILD_BATCH_SIZE`: Set the number of sources in a "unity" unit. Default: `0` (all)
- `CMAKE_UNITY_BUILD`: Enable "unity" (aka jumbo) builds. Default: `OFF`
Details via CMake
[variables](https://cmake.org/cmake/help/latest/manual/cmake-variables.7.html) and
[install directories](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html).
## Dependencies
- `CURL_BROTLI`: Use brotli. Default: `OFF`
- `CURL_USE_BEARSSL`: Enable BearSSL for SSL/TLS. Default: `OFF`
- `CURL_USE_GNUTLS`: Enable GnuTLS for SSL/TLS. Default: `OFF`
- `CURL_USE_GSASL`: Use libgsasl. Default: `OFF`
- `CURL_USE_GSSAPI`: Use GSSAPI implementation. Default: `OFF`
- `CURL_USE_LIBPSL`: Use libpsl. Default: `ON`
- `CURL_USE_LIBSSH2`: Use libssh2. Default: `ON`
- `CURL_USE_LIBSSH`: Use libssh. Default: `OFF`
- `CURL_USE_LIBUV`: Use libuv for event-based tests. Default: `OFF`
- `CURL_USE_MBEDTLS`: Enable mbedTLS for SSL/TLS. Default: `OFF`
- `CURL_USE_OPENSSL`: Enable OpenSSL for SSL/TLS. Default: `ON` if not other TLS backend was enabled
- `CURL_USE_PKGCONFIG`: Enable `pkg-config` to detect dependencies. Default: `ON` for Unix, vcpkg, MinGW if not cross-compiling
- `CURL_USE_RUSTLS`: Enable Rustls for SSL/TLS. Default: `OFF`
- `CURL_USE_SCHANNEL`: Enable Windows native SSL/TLS (Schannel). Default: `OFF`
- `CURL_USE_SECTRANSP`: Enable Apple OS native SSL/TLS (Secure Transport). Default: `OFF`
- `CURL_USE_WOLFSSH`: Use wolfSSH. Default: `OFF`
- `CURL_USE_WOLFSSL`: Enable wolfSSL for SSL/TLS. Default: `OFF`
- `CURL_ZLIB`: Use zlib (`ON`, `OFF` or `AUTO`). Default: `AUTO`
- `CURL_ZSTD`: Use zstd. Default: `OFF`
- `ENABLE_ARES`: Enable c-ares support. Default: `OFF`
- `USE_APPLE_IDN`: Use Apple built-in IDN support. Default: `OFF`
- `USE_LIBIDN2`: Use libidn2 for IDN support. Default: `ON`
- `USE_LIBRTMP`: Enable librtmp from rtmpdump. Default: `OFF`
- `USE_MSH3`: Use msh3/msquic library for HTTP/3 support. Default: `OFF`
- `USE_NGHTTP2`: Use nghttp2 library. Default: `ON`
- `USE_NGTCP2`: Use ngtcp2 and nghttp3 libraries for HTTP/3 support. Default: `OFF`
- `USE_QUICHE`: Use quiche library for HTTP/3 support. Default: `OFF`
- `USE_WIN32_IDN`: Use WinIDN for IDN support. Default: `OFF`
- `USE_WIN32_LDAP`: Use Windows LDAP implementation. Default: `ON`
## Dependency options (via CMake)
- `OPENSSL_ROOT_DIR`: Set this variable to the root installation of OpenSSL (and forks).
- `ZLIB_INCLUDE_DIR`: The zlib include directory.
- `ZLIB_LIBRARY`: Path to `zlib` library.
## Dependency options
- `PERL_EXECUTABLE` Perl binary used throughout the build and tests.
- `BEARSSL_INCLUDE_DIR`: The BearSSL include directory.
- `BEARSSL_LIBRARY`: Path to `bearssl` library.
- `BROTLI_INCLUDE_DIR`: The brotli include directory.
- `BROTLICOMMON_LIBRARY`: Path to `brotlicommon` library.
- `BROTLIDEC_LIBRARY`: Path to `brotlidec` library.
- `CARES_INCLUDE_DIR`: The c-ares include directory.
- `CARES_LIBRARY`: Path to `cares` library.
- `GSS_ROOT_DIR`: Set this variable to the root installation of GSS. (also supported as environment)
- `LDAP_LIBRARY`: Name or full path to `ldap` library. Default: `ldap`
- `LDAP_LBER_LIBRARY`: Name or full path to `lber` library. Default: `lber`
- `LDAP_INCLUDE_DIR`: Path to LDAP include directory.
- `LIBGSASL_INCLUDE_DIR`: The libgsasl include directory.
- `LIBGSASL_LIBRARY`: Path to `libgsasl` library.
- `LIBIDN2_INCLUDE_DIR`: The libidn2 include directory.
- `LIBIDN2_LIBRARY`: Path to `libidn2` library.
- `LIBPSL_INCLUDE_DIR`: The libpsl include directory.
- `LIBPSL_LIBRARY`: Path to `libpsl` library.
- `LIBSSH_INCLUDE_DIR`: The libssh include directory.
- `LIBSSH_LIBRARY`: Path to `libssh` library.
- `LIBSSH2_INCLUDE_DIR`: The libssh2 include directory.
- `LIBSSH2_LIBRARY`: Path to `libssh2` library.
- `LIBUV_INCLUDE_DIR`: The libuv include directory.
- `LIBUV_LIBRARY`: Path to `libuv` library.
- `MSH3_INCLUDE_DIR`: The msh3 include directory.
- `MSH3_LIBRARY`: Path to `msh3` library.
- `MBEDTLS_INCLUDE_DIR`: The mbedTLS include directory.
- `MBEDTLS_LIBRARY`: Path to `mbedtls` library.
- `MBEDX509_LIBRARY`: Path to `mbedx509` library.
- `MBEDCRYPTO_LIBRARY`: Path to `mbedcrypto` library.
- `NGHTTP2_INCLUDE_DIR`: The nghttp2 include directory.
- `NGHTTP2_LIBRARY`: Path to `nghttp2` library.
- `NGHTTP3_INCLUDE_DIR`: The nghttp3 include directory.
- `NGHTTP3_LIBRARY`: Path to `nghttp3` library.
- `NGTCP2_INCLUDE_DIR`: The ngtcp2 include directory.
- `NGTCP2_LIBRARY`: Path to `ngtcp2` library.
- `NETTLE_INCLUDE_DIR`: The nettle include directory.
- `NETTLE_LIBRARY`: Path to `nettle` library.
- `QUICHE_INCLUDE_DIR`: The quiche include directory.
- `QUICHE_LIBRARY`: Path to `quiche` library.
- `RUSTLS_INCLUDE_DIR`: The Rustls include directory.
- `RUSTLS_LIBRARY`: Path to `rustls` library.
- `WOLFSSH_INCLUDE_DIR`: The wolfSSH include directory.
- `WOLFSSH_LIBRARY`: Path to `wolfssh` library.
- `WOLFSSL_INCLUDE_DIR`: The wolfSSL include directory.
- `WOLFSSL_LIBRARY`: Path to `wolfssl` library.
- `ZSTD_INCLUDE_DIR`: The zstd include directory.
- `ZSTD_LIBRARY`: Path to `zstd` library.
## Test tools
- `APACHECTL`: Default: `apache2ctl`
- `APXS`: Default: `apxs`
- `CADDY`: Default: `caddy`
- `HTTPD_NGHTTPX`: Default: `nghttpx`
- `HTTPD`: Default: `apache2`
- `TEST_NGHTTPX`: Default: `nghttpx`
- `VSFTPD`: Default: `vsftps`