This PR updates the CMake build/install docs in `docs/INSTALL-CMAKE.md`,
in particular focusing on the use of libcurl from CMake using
`find_package` as well as the newly added features/protocols support via
using `COMPONENTS` or `OPTIONAL_COMPONENTS` with `find_package`.
See #15854 for initial discussion and the corresponding PR #15858 that
was merged.
Some additional best-practices notes are added, for example:
* Encouraging building out-of-source
* Using `--config` with `cmake --build` for multi-config CMake
generators, not `CMAKE_BUILD_TYPE`
We also add a CURL CMake-specific tip on using `CMAKE_INSTALL_PREFIX`
during configure time to set the install prefix, not using `--prefix`
when running `cmake --install` so `curl-config` output is consistent.
Closes#16329
Static CRT crashes MSVCR* MSVC builds (in VS2008, VS2010, VS2012,
VS2013) according to CI and local tests. The reproducible crash happens
in `curl_mfprintf() -> fputc(s, stderr)` when trying to display the
warning message in `curl -V`. `stderr` is non-NULL and resolves to `2`.
This reproducer needs a debug-enabled build, but it's unrelated to debug
features or curl's memory tracker. It happens regardless of unity build,
CPU architecture or `DllMain()` use. Example from VS2013:
```
+ _bld/src/Debug/curl.exe --disable --version
./appveyor.sh: line 124: 203 Segmentation fault "${curl}" --disable --version
```
Ref: https://ci.appveyor.com/project/curlorg/curl/builds/51570451/job/ojpdqrsm1hmpmq6a#L210
Another crash happened in an UCRT build (VS2017) with a couple of
`printf()`s added to curl's `main()` function:
```
Microsoft Visual C++ Runtime Library
Debug Assertion Failed!
Program: C:/projects/curl/bld/src/Debug/curl.exe
File: minkernel/crts/ucrt/src/appcrt/heap/debug_heap.cpp
Line: 996
Expression: _act_first_block == header
```
(it hangs the job in CI due to the GUI popup)
Ref: https://github.com/curl/curl/pull/16394#issuecomment-2677181716
To avoid actual and potential issues, this patch issues a warning on
the shared-libcurl + static-CRT combination and falls back to the
default, shared CRT. IOW a static CRT build now requires a static curl
exe when using the `CURL_STATIC_CRT=ON` option.
Follow-up to 4fc6ebe18a#1621
Cherry-picked from #16394 (with more details there)
Closes#16456
Allow overriding the `IMPORT_LIB_SUFFIX` default with an empty value.
Also:
- add a fatal error if the implib and static lib filename are identical.
- clarify `IMPORT_LIB_SUFFIX` default value in the documentation.
Reported-by: RubisetCie on Github
Fixes#16324
Ref: 1199308dbc#11505Closes#16332
iOS:
- add jobs with autotools, CMake, CMake Xcode generator.
The Xcode generator is >10x slower than Unix Makefiles. Keep it
because it's the one recommended by CMake and for having its own
quirks we may want to know about.
- build, cache and use LibreSSL for these jobs.
With workaround for an iOS build issue fixed in master.
- make Xcode generator work by explicitly disabling code signing.
- make tests and examples build with the Xcode generator by setting
`-DMACOSX_BUNDLE_GUI_IDENTIFIER=se.curl`, to avoid
"Bundle identifier is missing" errors.
- cmake: disable `CURL_USE_PKGCONFIG` by default for Apple device.
- cmake: add `stdc++` library for BoringSSL and AWS-LC, with
`OPENSSL_USE_STATIC_LIBS=ON` set.
- cmake: add workaround for Xcode generator issue, where it cannot
handle two targets depending on one custom command. A better fix may
be dropping `tool_hugehelp.c` and `tool_ca_embed.c` from curltool
library. For a future PR.
Android:
- add vcpkg to Android jobs, enable dependencies.
Assisted-by: Tal Regev via #16045
- make vcpkg work with autotools.
- pass `--with-brotli` to autotools to detect the vcpkg-supplied brotli.
- enable BoringSSL for Android and add a job with it.
- silence 457 CMake configure warnings about the Android NDK CMake
scripts targeting freshly deprecated CMake versions.
These were much more involved than imagined. Basically nothing works out
of the box, and when combined, everything becomes a unique edge case.
autotools builds were a much easier to make work than CMake ones.
Also:
- GHA/non-native: re-sync names to be shorter and more aligned with
other workflows.
- GHA: add `persist-credentials: false` where missing.
Unresolved issues:
- `OPENSSL_ROOT_DIR` ignored/mis-used when pointing it to LibreSSL.
CMake seems to prepend the sysroot to the passed absolute directory.
Found no workaround.
- CMake when combined with Android, both the Google-recommended method
and the built-in CMake method fail to provide a way to avoid
`pkg-config` packages at system directories. Failed to find a knob
that can remove `/usr/include` from the search path. The workaround is
to disable zstd. (I enabled it by default in this release, maybe
premature?: f2adb3b6d7#15431)
Disabling `pkg-config` doesn't work because vcpkg dependencies do not
link without it.
- CMake's Xcode generator is slow because each `try_compile()` feature
check springs a new CMake + Xcode project taking a long time to run,
just to compile single-liner C files. A known issue, with no solution.
`-DCMAKE_MACOSX_BUNDLE=OFF` did not help, limiting build types to
a single one (e.g. `Debug`) also had no effect.
make | Xcode | GHA run
:---- | :---- | :--------------------------------------------------------------------
16s | 2m57s | https://github.com/curl/curl/actions/runs/12866334102/job/35868712426
23s | 4m13s | https://github.com/curl/curl/actions/runs/12868128013/job/35874212461
16s | 3m39s | https://github.com/curl/curl/actions/runs/12859073531/job/35849041880
14s | 2m23s | https://github.com/curl/curl/actions/runs/12858298423/job/35847201313
15s | 2m36s | https://github.com/curl/curl/actions/runs/12858058492/job/35846669761
19s | 3m19s | https://github.com/curl/curl/actions/runs/12868919430/job/35876601168Closes#16043
- GHA/non-native: add Android builds, both cmake and autotools,
both NDK 21 (oldest available) and 35 (newest available)
https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md
It comes with a maintenance burden to bump the oldest/latest values
with CI runner updates.
- cmake: disable `CURL_USE_PKGCONFIG` by default for Android.
To avoid picking up system package by default.
- build: add `ANDROID-<NDK-LEVEL>` flag to `buildinfo.txt`.
Also detect NDK level with the CMake built-in build method:
https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html#cross-compiling-for-android
- INSTALL.md: add CMake build instructions for Android.
- INSTALL.md: make NDK levels consistent in `./configure` example.
Closes#16014
Since the script 'apachectl' from the httpd project is severly mutilated
on several distros, use the executable httpd/apache2 directly in pytest
runs.
Remove detection of apachectl form autoconf and cmake.
Closes#16000
We recommend migrating to CMake from winbuild and Visual Studio project
files. winbuild is deprecated and will be dropped in September 2025.
CMake supports all the features and options, with new ones added
promptly. It supports out-of-tree, unity and documentation builds.
- deprecate winbuild method in favour of CMake by September 2025.
- add migration guide from winbuild to CMake.
- add migration guide from Visual Studio Project Files to CMake.
- add deprecation message to winbuild.
Need to ack with `WINBUILD_ACKNOWLEDGE_DEPRECATED=yes`
Authored-by: Jay Satiro
- mention `CMAKE_BUILD_TYPE` option in `INSTALL-CMAKE`.
- document missing `SSH_PATH` winbuild option.
Closes#15920
Adds the experimental feature `ssls-export` to libcurl and curl for
importing and exporting SSL sessions from/to a file.
* add functions to libcurl API
* add command line option `--ssl-sessions <filename>` to curl
* add documenation
* add support in configure
* add support in cmake
+ add pytest case
Closes#15924
via `DL_LIBRARY`, `MATH_LIBRARY`, `PTHREAD_LIBRARY` variables.
They are used in Rustls, wolfSSL Find modules.
Also:
- always use `NAMES` keyword in `find_library()` calls.
- respect `find_library()` results for `dl`, `m`, `pthread`.
- formatting.
Closes#15892
build:
- autotools: fix to build generated sources for the `tidy` target.
- autotools: allow passing custom clang-tidy options via
`CURL_CLANG_TIDYFLAGS` env.
- cmake: add `CURL_CLANG_TIDY` option to configure for `clang-tidy`.
Also add:
- `CLANG_TIDY` variable to customize the `clang-tidy` tool.
- `CURL_CLANG_TIDYFLAGS` to pass custom options to `clang-tidy`.
- apply `--enable-werror` and `-DCURL_WERROR=ON` to `clang-tidy`.
CI/GHA:
- add clang-tidy job for Linux, using autotools and clang-tidy v18.
This one needs to disable `clang-analyzer-valist.Uninitialized`
to avoid false positives:
https://github.com/llvm/llvm-project/issues/40656
Duration: 5.5 minutes
- add clang-tidy job for macOS, using cmake and clang-tidy v19.
This one also covers tests and examples, and doesn't hit the false
positives seen with llvm v18 and earlier.
Duration: 4.5 minutes
- Linux/macOS: skip installing test dependencies when not building or
running tests.
fix fallouts reported by `clang-tidy`:
- lib:
- cf-h2-proxy: unused assignment in non-debug builds.
- cf-socket: silence warning.
FIXME: https://github.com/curl/curl/pull/15825#issuecomment-2561867769
- ftp: NULL passed to `strncmp()`.
- http2: NULL-ptr deref.
- mprintf: silence warning.
- src/tool_writeout: NULL passed to `fputs()`.
- examples:
- invalid file pointers.
- missing `fclose()`.
- tests:
- http/clients/hx-download: memory leaks on error.
- http/clients/hx-download: memory leak on repeat `-r` option.
- server: double `fclose()`.
https://www.man7.org/linux/man-pages/man3/fclose.3.html
- server: invalid file pointer/handle.
- server/getpart: unused assignments.
- server/mqttd: leak on failed `realloc()`.
- server/tftpd: NULL passed to `strcmp()`.
Closes#15825
The new detection method also allows to enable librtmp without using
OpenSSL as a curl TLS backend at the same time.
Also:
- implement manual version detection for librtmp.
Version info is in hex. With CMake 3.13 and newer, extract it as a hex
number. With earlier CMake version, just strip the leading zeroes.
Doing more here seems overkill because librtmp has been standing
at 2.3/2.4 for a decade now. Bumping into hex digits seems unlikely
before deprecating CMake 3.13 support.
librtmp advertises v2.4 via its `pkg-config` module, and v2.3 via
its public header. The latter shows up in `curl -V` and either can
be shown at configure-time depending on detection method.
This isn't a curl bug.
- GHA/macos: enable rtmp in a job.
- apply the "half-detection" fix to the Find module.
`librtmp` is also affected (in CI too), because it depends on libssl and
libcrypto.
Closes#15832
- make `curl_dependency_option()` more generic.
- extend `CURL_BROTLI` and `CURL_ZSTD` options to accept
`AUTO` in addition to existing `ON` and `OFF`.
- change `CURL_BROTLI` and `CURL_ZSTD` option default
to `AUTO`. Was: `OFF`.
It brings cmake behavior closer to `./configure`.
Still different:
- `./configure` defaults to `off` which means to check default
locations. cmake checks more locations by default.
(Also tried `NO_CMAKE_PATH`, but then it checked less locations.)
- cmake returns both `brotlicommon` and `brotlidec` libs,
while `./configure` only returns the latter.
- ci: drop explicit cmake options, that are now unnecessary.
- GHA/configure-vs-cmake: make adjustments to make tests pass.
Closes#15431
This reverts commit 39c06f7883#15005.
Combined with most Find modules now supporting `pkg-config`
(39c741b7b0#15408) this change made
mingw-cross builds fragile by picking up OS-native components. Also
adding `/usr/include` to the header path, confusing feature detection.
`Makefile.mk` supported MS-DOS and Amiga, but `./configure` also
supported them in a better tested and more flexible way.
This patch also adds CMake support for MS-DOS/DJGPP and Amiga OS 3.
`Makefile.mk` was not maintained. Delete it in favour of first-tier
build methods.
Also include some non-MS-DOS/AmigaOS-specific tidy-up, see details at
the end of this message.
Details:
- fix/silence all MS-DOS/DJGPP build warnings and issues.
- add MS-DOS support to cmake.
- default to `ENABLE_THREADED_RESOLVER=OFF` for MS-DOS.
- add support for `WATT_ROOT`.
- use static libcurl with MS-DOS.
- fixup default CMake suffixes/prefixes for DJGPP.
- disable hidden symbols for MS-DOS. Not supported on MS-DOS.
- opt-in MS-DOS into `USE_UNIX_SOCKETS`.
- improve MS-DOS support in autotools.
- default to `--disable-threaded-resolver` for MS-DOS.
- make sure to use `close_s()` (from Watt-32) with autotools and cmake.
`Makefile.mk` used it before this patch.
- GHA: add DJGPP cmake (~30s) and autotools (~60s) build jobs.
Also build tests and examples with cmake.
- improve AmigaOS support in autotools:
- configure: detect `CloseSocket()` when it's a macro.
- configure: fix `IoctlSocket` detection on AmigaOS.
- curl-amissl.m4: pass AmiSSL libs to tests/servers.
- add AmigaOS3 support to cmake:
- cmake: fix `HAVE_IOCTLSOCKET_CAMEL` and
`HAVE_IOCTLSOCKET_CAMEL_FIONBIO` detections.
- set necessary system libs.
- add AmiSSL support.
- inet_ntop, inet_pton: fix using it for AmigaOS. cmake detects them,
and they did not compile with AmigaOS.
- cmake: better sync `gethostname` detection with autotools.
Fixes detection for AmigaOS, where `gethostname` is a macro.
- cmake: fix `sys/utime.h` detection on AmigaOS.
- cmake: force-disable `getaddrinfo` for AmigaOS.
- cmake: tweak threading and static/shared default for AmigaOS.
- cmake: rely on manual variable `AMIGA` to enable the platform.
- GHA: add AmigaOS cmake and autotools (~45s) jobs.
Also build tests and examples with cmake.
- INSTALL: update MS-DOS and AmigaOS build instructions.
- amigaos: fix `-Wpointer-sign` and
`zero or negative size array '_args'` in `Printf()`.
- amigaos: fix `-Wpointer-sign`
- amigaos: fix `-Wredundant-decls` `errno` and `h_errno`.
- amigaos: brute-force silence `lseek()` size warnings.
- amigaos: server/resolve: silence `-Wdiscarded-qualifiers`.
- amigaos: server/resolve: fix `-Wpointer-sign`.
- amigaos: fix `CURL_SA_FAMILY_T` type.
- nonblock: prefer `HAVE_IOCTLSOCKET_CAMEL_FIONBIO` for AmigaOS.
`ioctl` is also detected, but fails when used. Make the above override
it for a successful build.
Authored-by: Darren Banfi
Fixes#15537Closes#15603
- tftpd: prefer `HAVE_IOCTLSOCKET_CAMEL_FIONBIO` for AmigaOS.
- tftpd: tidy-up conditional code.
- curl: set stack size to 16384 for AmigaOS3/4
Overriding the default 4096.
Suggested-by: Darren Banfi
Ref: https://github.com/curl/curl/pull/15543#issuecomment-2498783123
Ref: https://wiki.amigaos.net/wiki/Controlling_Application_Stack
- functypes.h: fix `SEND_QUAL_ARG2` for AmigaOS.
- tftp: add missing cast in sendto() call for AmigaOS.
- getinfo: fix warning with AmigaOS.
- tool_operate: silence warning with AmigaOS
- amigaos: fix building libtests due to missing `RLIMIT_NOFILE`.
- curl_gethostname: silence warning for AmigaOS.
- ftp: silence `-Wtype-limits` for AmigaOS.
- libtest: fix timeval initialization for AmigaOS.
- examples: fix `timeval` initialization for AmigaOS.
- examples: silence warning for AmigaOS.
- configure: fix IPv6 detection for cross-builds.
- netrc: fix to build with AmigaOS cleanly.
- buildinfo: detect and add `DOS` tag for MS-DOS builds.
- buildinfo: add `AMIGA` to buildinfo.txt in auttools.
- build: move `USE_WATT32` macro definition to cmake/configure.
Non-MS-DOS/AmigeOS-specific tidy-ups:
- configure: sync `sa_family_t` detection with cmake.
- configure: sync `ADDRESS_FAMILY` detection signals with cmake.
- doh: use `CURL_SA_FAMILY_T`.
- lib: drop mingw-specific `CURL_SA_FAMILY_T` workaround.
- cmake: extend instead of override check-specific
configurations/requirements.
This allows to honor global requirements added earlier.
Necessary for AmigaOS for example.
- cmake: omit warning on disabled IPv6 for MS-DOS and AmigaOS.
No IPv6 support on these platforms. Also sync with autotools.
- lib1960: use libcurl `inet_pton()` wrapper.
- cmake: detect LibreSSL (to match autotools).
- cmake: say the specific OpenSSL flavour detected.
- hostip: add missing `HAVE_SOCKADDR_IN6_SIN6_SCOPE_ID` guard.
- lib: simplify classic mac feature guards.
Follow-up to a8861b6ccd#9764Closes#15543
Enable `CURL_USE_PKGCONFIG` by default for MinGW cross-builds.
Note: This may cause fallouts in certain envs where `pkg-config` picks
up native packages.
Follow-up to e1ab01d1bd#14658
Follow-up to c555ab469d#14575Closes#15005
The ECH feature cannot be built without HTTPS RR.
ECH automatically implied HTTPS RR in `./configure` but not in CMake,
winbuild, documentation.
Also update documentation and CI configs.
Follow-up to a362962b72#11922Closes#15648
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/14885Closes#15388
- INSTALL-CMAKE: delete `Current flaws in the curl CMake build` section.
#1123 was fixed in 7e93637acd#2443
- TODO: delete item 3.2.
Follow-up to 1cb4f5d6e8#1879Closes#15405
Instead of use 'docs/*.md' in dep5. For clarity and avoiding a wide-
matching wildcard.
+ Remove mention of old files from .reuse/dep5
+ add info to .github/dependabot.yml
+ make scripts/copyright.pl warn on non-matching patterns
Closes#13245
- Turn docs/INSTALL.cmake into a proper markdown file,
docs/INSTALL-CMAKE.md
- Move things around to divide the description into configuration,
building and installing sections
- Mention the more modern cmake options to configure, build and install,
but also retain the older variants as fallbacks
Closes#12772
