INSTALL-CMAKE.md (35252B)
1 <!-- 2 Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 4 SPDX-License-Identifier: curl 5 --> 6 7 # Building with CMake 8 9 This document describes how to configure, build and install curl and libcurl 10 from source code using the CMake build tool. To build with CMake, you of 11 course first have to install CMake. The minimum required version of CMake is 12 specified in the file `CMakeLists.txt` found in the top of the curl source 13 tree. Once the correct version of CMake is installed you can follow the 14 instructions below for the platform you are building on. 15 16 CMake builds can be configured either from the command line, or from one of 17 CMake's GUIs. 18 19 # Configuring 20 21 A CMake configuration of curl is similar to the autotools build of curl. 22 It consists of the following steps after you have unpacked the source. 23 24 We recommend building with CMake on Windows. For instructions on migrating 25 from the `projects/Windows` Visual Studio solution files, see 26 [this section](#migrating-from-visual-studio-ide-project-files). For 27 instructions on migrating from the winbuild builds, see 28 [the following section](#migrating-from-winbuild-builds). 29 30 ## Using `cmake` 31 32 You can configure for in source tree builds or for a build tree 33 that is apart from the source tree. 34 35 - Build in the source tree. 36 37 $ cmake -B . 38 39 - Build in a separate directory (parallel to the curl source tree in this 40 example). The build directory is created for you. This is recommended over 41 building in the source tree to separate source and build artifacts. 42 43 $ cmake -B ../curl-build 44 45 For the full list of CMake build configuration variables see 46 [the corresponding section](#cmake-build-options). 47 48 ### Fallback for CMake before version 3.13 49 50 CMake before version 3.13 does not support the `-B` option. In that case, 51 you must create the build directory yourself, `cd` to it and run `cmake` 52 from there: 53 54 $ mkdir ../curl-build 55 $ cd ../curl-build 56 $ cmake ../curl 57 58 If you want to build in the source tree, it is enough to do this: 59 60 $ cmake . 61 62 ### Build system generator selection 63 64 You can override CMake's default by using `-G <generator-name>`. For example 65 on Windows with multiple build systems if you have MinGW-w64 then you could use 66 `-G "MinGW Makefiles"`. 67 [List of generator names](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html). 68 69 ## Using `ccmake` 70 71 CMake comes with a curses based interface called `ccmake`. To run `ccmake` 72 on a curl use the instructions for the command line cmake, but substitute 73 `ccmake` for `cmake`. 74 75 This brings up a curses interface with instructions on the bottom of the 76 screen. You can press the "c" key to configure the project, and the "g" key to 77 generate the project. After the project is generated, you can run make. 78 79 ## Using `cmake-gui` 80 81 CMake also comes with a Qt based GUI called `cmake-gui`. To configure with 82 `cmake-gui`, you run `cmake-gui` and follow these steps: 83 84 1. Fill in the "Where is the source code" combo box with the path to 85 the curl source tree. 86 2. Fill in the "Where to build the binaries" combo box with the path to 87 the directory for your build tree, ideally this should not be the same 88 as the source tree, but a parallel directory called curl-build or 89 something similar. 90 3. Once the source and binary directories are specified, press the 91 "Configure" button. 92 4. Select the native build tool that you want to use. 93 5. At this point you can change any of the options presented in the GUI. 94 Once you have selected all the options you want, click the "Generate" 95 button. 96 97 # Building 98 99 Build (you have to specify the build directory). 100 101 $ cmake --build ../curl-build 102 103 ## Static builds 104 105 The CMake build setup is primarily done to work with shared/dynamic third 106 party dependencies. When linking with shared libraries, the dependency "chain" 107 is handled automatically by the library loader - on all modern systems. 108 109 If you instead link with a static library, you need to provide all the 110 dependency libraries already at the link command line. 111 112 Figuring out all the dependency libraries for a given library is hard, as it 113 might involve figuring out the dependencies of the dependencies and they vary 114 between platforms and can change between versions. 115 116 When using static dependencies, the build scripts mostly assume that you, the 117 user, provide all the necessary additional dependency libraries as additional 118 arguments in the build. 119 120 Building statically is not for the faint of heart. 121 122 ### Fallback for CMake before version 3.13 123 124 CMake before version 3.13 does not support the `--build` option. In that 125 case, you have to `cd` to the build directory and use the building tool that 126 corresponds to the build files that CMake generated for you. This example 127 assumes that CMake generates `Makefile`: 128 129 $ cd ../curl-build 130 $ make 131 132 # Testing 133 134 (The test suite does not yet work with the cmake build) 135 136 # Installing 137 138 Install to default location (you have to specify the build directory). 139 140 $ cmake --install ../curl-build 141 142 Do not use `--prefix` to change the installation prefix as the output produced 143 by the `curl-config` script is determined at CMake configure time. If you want 144 to set a custom install prefix for curl, set 145 [`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) 146 when configuring the CMake build. 147 148 ### Fallback for CMake before version 3.15 149 150 CMake before version 3.15 does not support the `--install` option. In that 151 case, you have to `cd` to the build directory and use the building tool that 152 corresponds to the build files that CMake generated for you. This example 153 assumes that CMake generates `Makefile`: 154 155 $ cd ../curl-build 156 $ make install 157 158 # CMake usage 159 160 Just as curl can be built and installed using CMake, it can also be used from 161 CMake. 162 163 ## Using `find_package` 164 165 To locate libcurl from CMake, one can use the standard 166 [`find_package`](https://cmake.org/cmake/help/latest/command/find_package.html) 167 command in the typical fashion: 168 169 ```cmake 170 find_package(CURL 8.12.0 REQUIRED) # FATAL_ERROR if CURL is not found 171 ``` 172 173 This invokes the CMake-provided 174 [FindCURL](https://cmake.org/cmake/help/latest/module/FindCURL.html) find module, 175 which first performs a search using the `find_package` 176 [config mode](https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure). 177 This is supported by the `CURLConfig.cmake` CMake config script which is 178 available if the given CURL was built and installed using CMake. 179 180 ### Detecting CURL features/protocols 181 182 Since version 8.12.0, `CURLConfig.cmake` publishes the supported CURL features 183 and protocols (see [release notes](https://curl.se/ch/8.12.0.html)). These can 184 be specified using the `find_package` keywords `COMPONENTS` and 185 `OPTIONAL_COMPONENTS`, with protocols in all caps, e.g. `HTTPS`, `LDAP`, while 186 features should be in their original sentence case, e.g. `AsynchDNS`, 187 `UnixSockets`. If any of the `COMPONENTS` are missing, then CURL is considered 188 as *not* found. 189 190 Here is an example of using `COMPONENTS` and `OPTIONAL_COMPONENTS` in 191 `find_package` with CURL: 192 193 ```cmake 194 # CURL_FOUND is FALSE if no HTTPS but brotli and zstd can be missing 195 find_package(CURL 8.12.0 COMPONENTS HTTPS OPTIONAL_COMPONENTS brotli zstd) 196 ``` 197 198 One can also check the defined `CURL_SUPPORTS_<feature-or-protocol>` variables 199 if a particular feature/protocol is supported. For example: 200 201 ```cmake 202 # check HTTPS 203 if(CURL_SUPPORTS_HTTPS) 204 message(STATUS "CURL supports HTTPS") 205 else() 206 message(STATUS "CURL does NOT support HTTPS") 207 endif() 208 ``` 209 210 ### Linking against libcurl 211 212 To link a CMake target against libcurl one can use 213 [`target_link_libraries`](https://cmake.org/cmake/help/latest/command/target_link_libraries.html) 214 as usual: 215 216 ```cmake 217 target_link_libraries(my_target PRIVATE CURL::libcurl) 218 ``` 219 220 # CMake build options 221 222 - `BUILD_CURL_EXE`: Build curl executable. Default: `ON` 223 - `BUILD_EXAMPLES`: Build libcurl examples. Default: `ON` 224 - `BUILD_LIBCURL_DOCS`: Build libcurl man pages. Default: `ON` 225 - `BUILD_MISC_DOCS`: Build misc man pages (e.g. `curl-config` and `mk-ca-bundle`). Default: `ON` 226 - `BUILD_SHARED_LIBS`: Build shared libraries. Default: `ON` 227 - `BUILD_STATIC_CURL`: Build curl executable with static libcurl. Default: `OFF` 228 - `BUILD_STATIC_LIBS`: Build static libraries. Default: `OFF` 229 - `BUILD_TESTING`: Build tests. Default: `ON` 230 - `CURL_CLANG_TIDY`: Run the build through `clang-tidy`. Default: `OFF` 231 - `CURL_CLANG_TIDYFLAGS`: Custom options to pass to `clang-tidy`. Default: (empty) 232 - `CURL_COMPLETION_FISH`: Install fish completions. Default: `OFF` 233 - `CURL_COMPLETION_FISH_DIR`: Custom fish completion install directory. 234 - `CURL_COMPLETION_ZSH`: Install zsh completions. Default: `OFF` 235 - `CURL_COMPLETION_ZSH_DIR`: Custom zsh completion install directory. 236 - `CURL_DEFAULT_SSL_BACKEND`: Override default TLS backend in MultiSSL builds. 237 Accepted values in order of default priority: 238 `wolfssl`, `gnutls`, `mbedtls`, `openssl`, `schannel`, `rustls` 239 - `CURL_ENABLE_EXPORT_TARGET`: Enable CMake export target. Default: `ON` 240 - `CURL_HIDDEN_SYMBOLS`: Hide libcurl internal symbols (=hide all symbols that are not officially external). Default: `ON` 241 - `CURL_LIBCURL_SOVERSION`: Enable libcurl SOVERSION. Default: `ON` for supported platforms 242 - `CURL_LIBCURL_VERSIONED_SYMBOLS`: Enable libcurl versioned symbols. Default: `OFF` 243 - `CURL_LIBCURL_VERSIONED_SYMBOLS_PREFIX`: Override default versioned symbol prefix. Default: `<TLS-BACKEND>_` or `MULTISSL_` 244 - `CURL_LTO`: Enable compiler Link Time Optimizations. Default: `OFF` 245 - `CURL_STATIC_CRT`: Build libcurl with static CRT with MSVC (`/MT`) (requires UCRT, static libcurl or no curl executable). Default: `OFF` 246 - `CURL_TARGET_WINDOWS_VERSION`: Minimum target Windows version as hex string. 247 - `CURL_WERROR`: Turn compiler warnings into errors. Default: `OFF` 248 - `ENABLE_CURLDEBUG`: Enable TrackMemory debug feature. Default: =`ENABLE_DEBUG` 249 - `ENABLE_CURL_MANUAL`: Build the man page for curl and enable its `-M`/`--manual` option. Default: `ON` 250 - `ENABLE_DEBUG`: Enable curl debug features (for developing curl itself). Default: `OFF` 251 - `IMPORT_LIB_SUFFIX`: Import library suffix. Default: `_imp` for MSVC-like toolchains, otherwise empty. 252 - `LIBCURL_OUTPUT_NAME`: Basename of the curl library. Default: `libcurl` 253 - `PICKY_COMPILER`: Enable picky compiler options. Default: `ON` 254 - `SHARE_LIB_OBJECT`: Build shared and static libcurl in a single pass (requires CMake 3.12 or newer). Default: `ON` for Windows 255 - `STATIC_LIB_SUFFIX`: Static library suffix. Default: (empty) 256 257 ## CA bundle options 258 259 - `CURL_CA_BUNDLE`: Path to the CA bundle. Set `none` to disable or `auto` for auto-detection. Default: `auto` 260 - `CURL_CA_EMBED`: Path to the CA bundle to embed in the curl tool. Default: (disabled) 261 - `CURL_CA_FALLBACK`: Use built-in CA store of TLS backend. Default: `OFF` 262 - `CURL_CA_PATH`: Location of default CA path. Set `none` to disable or `auto` for auto-detection. Default: `auto` 263 - `CURL_CA_SEARCH_SAFE`: Enable safe CA bundle search (within the curl tool directory) on Windows. Default: `OFF` 264 265 ## Enabling features 266 267 - `CURL_ENABLE_SSL`: Enable SSL support. Default: `ON` 268 - `CURL_WINDOWS_SSPI`: Enable SSPI on Windows. Default: =`CURL_USE_SCHANNEL` 269 - `ENABLE_IPV6`: Enable IPv6 support. Default: `ON` if target supports IPv6. 270 - `ENABLE_THREADED_RESOLVER`: Enable threaded DNS lookup. Default: `ON` if c-ares is not enabled and target supports threading. 271 - `ENABLE_UNICODE`: Use the Unicode version of the Windows API functions. Default: `OFF` 272 - `ENABLE_UNIX_SOCKETS`: Enable Unix domain sockets support. Default: `ON` 273 - `USE_ECH`: Enable ECH support. Default: `OFF` 274 - `USE_HTTPSRR`: Enable HTTPS RR support. Default: `OFF` 275 - `USE_OPENSSL_QUIC`: Use OpenSSL and nghttp3 libraries for HTTP/3 support. Default: `OFF` 276 - `USE_SSLS_EXPORT`: Enable experimental SSL session import/export. Default: `OFF` 277 278 ## Disabling features 279 280 - `CURL_DISABLE_ALTSVC`: Disable alt-svc support. Default: `OFF` 281 - `CURL_DISABLE_AWS`: Disable **aws-sigv4**. Default: `OFF` 282 - `CURL_DISABLE_BASIC_AUTH`: Disable Basic authentication. Default: `OFF` 283 - `CURL_DISABLE_BEARER_AUTH`: Disable Bearer authentication. Default: `OFF` 284 - `CURL_DISABLE_BINDLOCAL`: Disable local binding support. Default: `OFF` 285 - `CURL_DISABLE_CA_SEARCH`: Disable unsafe CA bundle search in PATH on Windows. Default: `OFF` 286 - `CURL_DISABLE_COOKIES`: Disable cookies support. Default: `OFF` 287 - `CURL_DISABLE_DICT`: Disable DICT. Default: `OFF` 288 - `CURL_DISABLE_DIGEST_AUTH`: Disable Digest authentication. Default: `OFF` 289 - `CURL_DISABLE_DOH`: Disable DNS-over-HTTPS. Default: `OFF` 290 - `CURL_DISABLE_FILE`: Disable FILE. Default: `OFF` 291 - `CURL_DISABLE_FORM_API`: Disable **form-api**. Default: =`CURL_DISABLE_MIME` 292 - `CURL_DISABLE_FTP`: Disable FTP. Default: `OFF` 293 - `CURL_DISABLE_GETOPTIONS`: Disable `curl_easy_options` API for existing options to `curl_easy_setopt`. Default: `OFF` 294 - `CURL_DISABLE_GOPHER`: Disable Gopher. Default: `OFF` 295 - `CURL_DISABLE_HEADERS_API`: Disable **headers-api** support. Default: `OFF` 296 - `CURL_DISABLE_HSTS`: Disable HSTS support. Default: `OFF` 297 - `CURL_DISABLE_HTTP`: Disable HTTP. Default: `OFF` 298 - `CURL_DISABLE_HTTP_AUTH`: Disable all HTTP authentication methods. Default: `OFF` 299 - `CURL_DISABLE_IMAP`: Disable IMAP. Default: `OFF` 300 - `CURL_DISABLE_INSTALL`: Disable installation targets. Default: `OFF` 301 - `CURL_DISABLE_IPFS`: Disable IPFS. Default: `OFF` 302 - `CURL_DISABLE_KERBEROS_AUTH`: Disable Kerberos authentication. Default: `OFF` 303 - `CURL_DISABLE_LDAP`: Disable LDAP. Default: `OFF` 304 - `CURL_DISABLE_LDAPS`: Disable LDAPS. Default: =`CURL_DISABLE_LDAP` 305 - `CURL_DISABLE_LIBCURL_OPTION`: Disable `--libcurl` option from the curl tool. Default: `OFF` 306 - `CURL_DISABLE_MIME`: Disable MIME support. Default: `OFF` 307 - `CURL_DISABLE_MQTT`: Disable MQTT. Default: `OFF` 308 - `CURL_DISABLE_NEGOTIATE_AUTH`: Disable negotiate authentication. Default: `OFF` 309 - `CURL_DISABLE_NETRC`: Disable netrc parser. Default: `OFF` 310 - `CURL_DISABLE_NTLM`: Disable NTLM support. Default: `OFF` 311 - `CURL_DISABLE_OPENSSL_AUTO_LOAD_CONFIG`: Disable automatic loading of OpenSSL configuration. Default: `OFF` 312 - `CURL_DISABLE_PARSEDATE`: Disable date parsing. Default: `OFF` 313 - `CURL_DISABLE_POP3`: Disable POP3. Default: `OFF` 314 - `CURL_DISABLE_PROGRESS_METER`: Disable built-in progress meter. Default: `OFF` 315 - `CURL_DISABLE_PROXY`: Disable proxy support. Default: `OFF` 316 - `CURL_DISABLE_RTSP`: Disable RTSP. Default: `OFF` 317 - `CURL_DISABLE_SHA512_256`: Disable SHA-512/256 hash algorithm. Default: `OFF` 318 - `CURL_DISABLE_SHUFFLE_DNS`: Disable shuffle DNS feature. Default: `OFF` 319 - `CURL_DISABLE_SMB`: Disable SMB. Default: `OFF` 320 - `CURL_DISABLE_SMTP`: Disable SMTP. Default: `OFF` 321 - `CURL_DISABLE_SOCKETPAIR`: Disable use of socketpair for curl_multi_poll. Default: `OFF` 322 - `CURL_DISABLE_SRP`: Disable TLS-SRP support. Default: `OFF` 323 - `CURL_DISABLE_TELNET`: Disable Telnet. Default: `OFF` 324 - `CURL_DISABLE_TFTP`: Disable TFTP. Default: `OFF` 325 - `CURL_DISABLE_VERBOSE_STRINGS`: Disable verbose strings. Default: `OFF` 326 - `CURL_DISABLE_WEBSOCKETS`: Disable WebSocket. Default: `OFF` 327 - `HTTP_ONLY`: Disable all protocols except HTTP (This overrides all `CURL_DISABLE_*` options). Default: `OFF` 328 329 ## Environment 330 331 - `CI`: Assume running under CI if set. 332 - `CURL_BUILDINFO`: Print `buildinfo.txt` if set. 333 - `CURL_CI`: Assume running under CI if set. 334 335 ## CMake options 336 337 - `CMAKE_BUILD_TYPE`: (see CMake) 338 - `CMAKE_DEBUG_POSTFIX`: Default: `-d` 339 - `CMAKE_IMPORT_LIBRARY_SUFFIX` (see CMake) 340 - `CMAKE_INSTALL_BINDIR` (see CMake) 341 - `CMAKE_INSTALL_INCLUDEDIR` (see CMake) 342 - `CMAKE_INSTALL_LIBDIR` (see CMake) 343 - `CMAKE_INSTALL_PREFIX` (see CMake) 344 - `CMAKE_STATIC_LIBRARY_SUFFIX` (see CMake) 345 - `CMAKE_UNITY_BUILD_BATCH_SIZE`: Set the number of sources in a "unity" unit. Default: `0` (all) 346 - `CMAKE_UNITY_BUILD`: Enable "unity" (aka jumbo) builds. Default: `OFF` 347 348 Details via CMake 349 [variables](https://cmake.org/cmake/help/latest/manual/cmake-variables.7.html) and 350 [install directories](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html). 351 352 ## Dependencies 353 354 - `CURL_BROTLI`: Use brotli (`ON`, `OFF` or `AUTO`). Default: `AUTO` 355 - `CURL_USE_GNUTLS`: Enable GnuTLS for SSL/TLS. Default: `OFF` 356 - `CURL_USE_GSASL`: Use libgsasl. Default: `OFF` 357 - `CURL_USE_GSSAPI`: Use GSSAPI implementation. Default: `OFF` 358 - `CURL_USE_LIBPSL`: Use libpsl. Default: `ON` 359 - `CURL_USE_LIBSSH2`: Use libssh2. Default: `ON` 360 - `CURL_USE_LIBSSH`: Use libssh. Default: `OFF` 361 - `CURL_USE_LIBUV`: Use libuv for event-based tests. Default: `OFF` 362 - `CURL_USE_MBEDTLS`: Enable mbedTLS for SSL/TLS. Default: `OFF` 363 - `CURL_USE_OPENSSL`: Enable OpenSSL for SSL/TLS. Default: `ON` if no other TLS backend was enabled. 364 - `CURL_USE_PKGCONFIG`: Enable `pkg-config` to detect dependencies. Default: `ON` for Unix (except Android, Apple devices), vcpkg, MinGW if not cross-compiling. 365 - `CURL_USE_RUSTLS`: Enable Rustls for SSL/TLS. Default: `OFF` 366 - `CURL_USE_SCHANNEL`: Enable Windows native SSL/TLS (Schannel). Default: `OFF` 367 - `CURL_USE_WOLFSSH`: Use wolfSSH. Default: `OFF` 368 - `CURL_USE_WOLFSSL`: Enable wolfSSL for SSL/TLS. Default: `OFF` 369 - `CURL_ZLIB`: Use zlib (`ON`, `OFF` or `AUTO`). Default: `AUTO` 370 - `CURL_ZSTD`: Use zstd (`ON`, `OFF` or `AUTO`). Default: `AUTO` 371 - `ENABLE_ARES`: Enable c-ares support. Default: `OFF` 372 - `USE_APPLE_IDN`: Use Apple built-in IDN support. Default: `OFF` 373 - `USE_LIBIDN2`: Use libidn2 for IDN support. Default: `ON` 374 - `USE_LIBRTMP`: Enable librtmp from rtmpdump. Default: `OFF` 375 - `USE_MSH3`: Use msh3/msquic library for HTTP/3 support. Default: `OFF` 376 - `USE_NGHTTP2`: Use nghttp2 library. Default: `ON` 377 - `USE_NGTCP2`: Use ngtcp2 and nghttp3 libraries for HTTP/3 support. Default: `OFF` 378 - `USE_QUICHE`: Use quiche library for HTTP/3 support. Default: `OFF` 379 - `USE_WIN32_IDN`: Use WinIDN for IDN support. Default: `OFF` 380 - `USE_WIN32_LDAP`: Use Windows LDAP implementation. Default: `ON` 381 382 ## Dependency options (via CMake) 383 384 - `OPENSSL_ROOT_DIR`: Set this variable to the root installation of OpenSSL (and forks). 385 - `OPENSSL_INCLUDE_DIR`: The OpenSSL include directory. 386 - `OPENSSL_SSL_LIBRARY`: Path to `ssl` library. With MSVC, CMake uses variables `SSL_EAY_DEBUG`/`SSL_EAY_RELEASE` instead. 387 - `OPENSSL_CRYPTO_LIBRARY`: Path to `crypto` library. With MSVC, CMake uses variables `LIB_EAY_DEBUG`/`LIB_EAY_RELEASE` instead. 388 - `OPENSSL_USE_STATIC_LIBS`: Look for static OpenSSL libraries. 389 - `ZLIB_INCLUDE_DIR`: The zlib include directory. 390 - `ZLIB_LIBRARY`: Path to `zlib` library. 391 - `ZLIB_USE_STATIC_LIBS`: Look for static ZLIB library (requires CMake v3.24). 392 393 ## Dependency options (tools) 394 395 - `CLANG_TIDY`: `clang-tidy` tool used with `CURL_CLANG_TIDY=ON`. Default: `clang-tidy` 396 - `PERL_EXECUTABLE`: Perl binary used throughout the build and tests. 397 398 ## Dependency options (libraries) 399 400 - `AMISSL_INCLUDE_DIR`: The AmiSSL include directory. 401 - `AMISSL_STUBS_LIBRARY`: Path to `amisslstubs` library. 402 - `AMISSL_AUTO_LIBRARY`: Path to `amisslauto` library. 403 - `BROTLI_INCLUDE_DIR`: The brotli include directory. 404 - `BROTLICOMMON_LIBRARY`: Path to `brotlicommon` library. 405 - `BROTLIDEC_LIBRARY`: Path to `brotlidec` library. 406 - `CARES_INCLUDE_DIR`: The c-ares include directory. 407 - `CARES_LIBRARY`: Path to `cares` library. 408 - `DL_LIBRARY`: Path to `dl` library. (for Rustls) 409 - `GSS_ROOT_DIR`: Set this variable to the root installation of GSS. (also supported as environment) 410 - `LDAP_LIBRARY`: Name or full path to `ldap` library. Default: `ldap` 411 - `LDAP_LBER_LIBRARY`: Name or full path to `lber` library. Default: `lber` 412 - `LDAP_INCLUDE_DIR`: Path to LDAP include directory. 413 - `LIBGSASL_INCLUDE_DIR`: The libgsasl include directory. 414 - `LIBGSASL_LIBRARY`: Path to `libgsasl` library. 415 - `LIBIDN2_INCLUDE_DIR`: The libidn2 include directory. 416 - `LIBIDN2_LIBRARY`: Path to `libidn2` library. 417 - `LIBPSL_INCLUDE_DIR`: The libpsl include directory. 418 - `LIBPSL_LIBRARY`: Path to `libpsl` library. 419 - `LIBRTMP_INCLUDE_DIR`: The librtmp include directory. 420 - `LIBRTMP_LIBRARY`: Path to `librtmp` library. 421 - `LIBSSH_INCLUDE_DIR`: The libssh include directory. 422 - `LIBSSH_LIBRARY`: Path to `libssh` library. 423 - `LIBSSH2_INCLUDE_DIR`: The libssh2 include directory. 424 - `LIBSSH2_LIBRARY`: Path to `libssh2` library. 425 - `LIBUV_INCLUDE_DIR`: The libuv include directory. 426 - `LIBUV_LIBRARY`: Path to `libuv` library. 427 - `MATH_LIBRARY`: Path to `m` library. (for Rustls, wolfSSL) 428 - `MBEDTLS_INCLUDE_DIR`: The mbedTLS include directory. 429 - `MBEDTLS_LIBRARY`: Path to `mbedtls` library. 430 - `MBEDX509_LIBRARY`: Path to `mbedx509` library. 431 - `MBEDCRYPTO_LIBRARY`: Path to `mbedcrypto` library. 432 - `MSH3_INCLUDE_DIR`: The msh3 include directory. 433 - `MSH3_LIBRARY`: Path to `msh3` library. 434 - `NGHTTP2_INCLUDE_DIR`: The nghttp2 include directory. 435 - `NGHTTP2_LIBRARY`: Path to `nghttp2` library. 436 - `NGHTTP3_INCLUDE_DIR`: The nghttp3 include directory. 437 - `NGHTTP3_LIBRARY`: Path to `nghttp3` library. 438 - `NGTCP2_INCLUDE_DIR`: The ngtcp2 include directory. 439 - `NGTCP2_LIBRARY`: Path to `ngtcp2` library. 440 - `NGTCP2_CRYPTO_BORINGSSL_LIBRARY`: Path to `ngtcp2_crypto_boringssl` library. 441 - `NGTCP2_CRYPTO_GNUTLS_LIBRARY`: Path to `ngtcp2_crypto_gnutls` library. 442 - `NGTCP2_CRYPTO_OSSL_LIBRARY`: Path to `ngtcp2_crypto_ossl` library. 443 - `NGTCP2_CRYPTO_QUICTLS_LIBRARY`: Path to `ngtcp2_crypto_quictls` library. 444 - `NGTCP2_CRYPTO_WOLFSSL_LIBRARY`: Path to `ngtcp2_crypto_wolfssl` library. 445 - `NETTLE_INCLUDE_DIR`: The nettle include directory. 446 - `NETTLE_LIBRARY`: Path to `nettle` library. 447 - `PTHREAD_LIBRARY`: Path to `pthread` library. (for Rustls) 448 - `QUICHE_INCLUDE_DIR`: The quiche include directory. 449 - `QUICHE_LIBRARY`: Path to `quiche` library. 450 - `RUSTLS_INCLUDE_DIR`: The Rustls include directory. 451 - `RUSTLS_LIBRARY`: Path to `rustls` library. 452 - `WATT_ROOT`: Set this variable to the root installation of Watt-32. 453 - `WOLFSSH_INCLUDE_DIR`: The wolfSSH include directory. 454 - `WOLFSSH_LIBRARY`: Path to `wolfssh` library. 455 - `WOLFSSL_INCLUDE_DIR`: The wolfSSL include directory. 456 - `WOLFSSL_LIBRARY`: Path to `wolfssl` library. 457 - `ZSTD_INCLUDE_DIR`: The zstd include directory. 458 - `ZSTD_LIBRARY`: Path to `zstd` library. 459 460 ## Test tools 461 462 - `APXS`: Default: `apxs` 463 - `CADDY`: Default: `caddy` 464 - `HTTPD_NGHTTPX`: Default: `nghttpx` 465 - `HTTPD`: Default: `apache2` 466 - `TEST_NGHTTPX`: Default: `nghttpx` 467 - `VSFTPD`: Default: `vsftps` 468 469 ## Feature detection variables 470 471 By default this CMake build script detects the version of some dependencies 472 using `check_symbol_exists`. Those checks do not work in the case that both 473 CURL and its dependency are included as sub-projects in a larger build using 474 `FetchContent`. To support that case, additional variables may be defined by 475 the parent project, ideally in the "extra" find package redirect file: 476 <https://cmake.org/cmake/help/latest/module/FetchContent.html#integrating-with-find-package> 477 478 Available variables: 479 480 - `HAVE_GNUTLS_SRP`: `gnutls_srp_verifier` present in GnuTLS. 481 - `HAVE_GSS_C_NT_HOSTBASED_SERVICE`: `GSS_C_NT_HOSTBASED_SERVICE` present in GSS/Heimdal/Kerberos. 482 - `HAVE_LDAP_INIT_FD`: `ldap_init_fd` present in LDAP library. 483 - `HAVE_LDAP_URL_PARSE`: `ldap_url_parse` present in LDAP library. 484 - `HAVE_OPENSSL_SRP`: `SSL_CTX_set_srp_username` present in OpenSSL (or fork). 485 - `HAVE_QUICHE_CONN_SET_QLOG_FD`: `quiche_conn_set_qlog_fd` present in quiche. 486 - `HAVE_RUSTLS_SUPPORTED_HPKE`: `rustls_supported_hpke` present in Rustls (unused if Rustls is detected via `pkg-config`). 487 - `HAVE_SSL_SET0_WBIO`: `SSL_set0_wbio` present in OpenSSL (or fork). 488 - `HAVE_SSL_SET1_ECH_CONFIG_LIST`: `SSL_set1_ech_config_list` present in OpenSSL (or fork). 489 - `HAVE_SSL_SET_QUIC_TLS_CBS`: `SSL_set_quic_tls_cbs` in OpenSSL. 490 - `HAVE_SSL_SET_QUIC_USE_LEGACY_CODEPOINT`: `SSL_set_quic_use_legacy_codepoint` in OpenSSL fork. 491 - `HAVE_WOLFSSL_BIO_NEW`: `wolfSSL_BIO_new` present in wolfSSL. 492 - `HAVE_WOLFSSL_BIO_SET_SHUTDOWN`: `wolfSSL_BIO_set_shutdown` present in wolfSSL. 493 - `HAVE_WOLFSSL_CTX_GENERATEECHCONFIG`: `wolfSSL_CTX_GenerateEchConfig` present in wolfSSL. 494 - `HAVE_WOLFSSL_DES_ECB_ENCRYPT`: `wolfSSL_DES_ecb_encrypt` present in wolfSSL. 495 - `HAVE_WOLFSSL_GET_PEER_CERTIFICATE`: `wolfSSL_get_peer_certificate` present in wolfSSL. 496 - `HAVE_WOLFSSL_SET_QUIC_USE_LEGACY_CODEPOINT`: 497 `wolfSSL_set_quic_use_legacy_codepoint` present in wolfSSL. 498 - `HAVE_WOLFSSL_USEALPN`: `wolfSSL_UseALPN` present in wolfSSL. 499 500 For each of the above variables, if the variable is *defined* (either to `ON` 501 or `OFF`), the symbol detection is skipped. If the variable is *not defined*, 502 the feature detection is performed. 503 504 Note: These variables are internal and subject to change. 505 506 # Migrating from Visual Studio IDE Project Files 507 508 We recommend using CMake to build curl with MSVC. 509 510 The project build files reside in project/Windows/VC\* for VS2010, VS2012 and 511 VS2013. 512 513 These CMake Visual Studio generators require CMake v3.24 or older. You can 514 download them from <https://cmake.org/files/v3.24/>. 515 516 You can also use `-G "NMake Makefiles"`, which is supported by all CMake 517 versions. 518 519 Configuration element | Equivalent CMake options 520 :-------------------------------- | :-------------------------------- 521 `VC10` | `-G "Visual Studio 10 2010"` 522 `VC11` | `-G "Visual Studio 11 2012"` 523 `VC12` | `-G "Visual Studio 12 2013"` 524 `x64` | `-A x64` 525 `Win32` | `-A Win32` 526 `DLL` | `BUILD_SHARED_LIBS=ON`, `BUILD_STATIC_LIBS=OFF`, (default) 527 `LIB` | `BUILD_SHARED_LIBS=OFF`, `BUILD_STATIC_LIBS=ON` 528 `Debug` | `CMAKE_BUILD_TYPE=Debug` (`-G "NMake Makefiles"` only) 529 `Release` | `CMAKE_BUILD_TYPE=Release` (`-G "NMake Makefiles"` only) 530 `DLL Windows SSPI` | `CURL_USE_SCHANNEL=ON` (with SSPI enabled by default) 531 `DLL OpenSSL` | `CURL_USE_OPENSSL=ON`, optional: `OPENSSL_ROOT_DIR`, `OPENSSL_USE_STATIC_LIBS=ON` 532 `DLL libssh2` | `CURL_USE_LIBSSH2=ON`, optional: `LIBSSH2_INCLUDE_DIR`, `LIBSSH2_LIBRARY` 533 `DLL WinIDN` | `USE_WIN32_IDN=ON` 534 535 For example these commands: 536 537 > cd projects 538 > ./generate.bat VC12 539 > msbuild "-property:Configuration=DLL Debug - DLL Windows SSPI - DLL WinIDN" Windows/VC12/curl-all.sln 540 541 translate to: 542 543 > cmake . -G "Visual Studio 12 2013" -A x64 -DCURL_USE_SCHANNEL=ON -DUSE_WIN32_IDN=ON -DCURL_USE_LIBPSL=OFF 544 > cmake --build . --config Debug --parallel 545 546 We do *not* specify `-DCMAKE_BUILD_TYPE=Debug` here as we might do for the 547 `"NMake Makefiles"` generator because the Visual Studio generators are 548 [multi-config generators](https://cmake.org/cmake/help/latest/prop_gbl/GENERATOR_IS_MULTI_CONFIG.html) 549 and therefore ignore the value of `CMAKE_BUILD_TYPE`. 550 551 # Migrating from winbuild builds 552 553 We recommend CMake to build curl with MSVC. The winbuild build system is 554 deprecated and is going to be removed in September 2025 in favor of the CMake 555 build system. 556 557 In CMake you can customize the path of dependencies by passing the absolute 558 header path and the full path of the library via `*_INCLUDE_DIR` and 559 `*_LIBRARY` options (see the complete list in the option listing above). 560 The full path to the library can point to a static library or an import 561 library, which defines if the dependency is linked as a dll or statically. 562 For OpenSSL this works 563 [differently](https://cmake.org/cmake/help/latest/module/FindOpenSSL.html): 564 You can pass the root directory of the OpenSSL installation via 565 `OPENSSL_ROOT_DIR`, then pass `OPENSSL_USE_STATIC_LIBS=ON` to select static 566 libs. 567 568 winbuild options | Equivalent CMake options 569 :-------------------------------- | :-------------------------------- 570 `DEBUG` | `CMAKE_BUILD_TYPE=Debug` 571 `GEN_PDB` | `CMAKE_EXE_LINKER_FLAGS=/Fd<path>`, `CMAKE_SHARED_LINKER_FLAGS=/Fd<path>` 572 `LIB_NAME_DLL`, `LIB_NAME_STATIC` | `IMPORT_LIB_SUFFIX`, `LIBCURL_OUTPUT_NAME`, `STATIC_LIB_SUFFIX` 573 `VC`: `<N>` | see the CMake [Visual Studio generators](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators) 574 `MACHINE`: `x64`, `x86` | `-A x64`, `-A Win32` 575 `MODE`: `dll`, `static` | `BUILD_SHARED_LIBS=ON/OFF`, `BUILD_STATIC_LIBS=ON/OFF`, `BUILD_STATIC_CURL=ON/OFF` (default: dll) 576 `RTLIBCFG`: `static` | `CURL_STATIC_CRT=ON` 577 `ENABLE_IDN` | `USE_WIN32_IDN=ON` 578 `ENABLE_IPV6` | `ENABLE_IPV6=ON` 579 `ENABLE_MSH3` | `USE_MSH3=ON` 580 `ENABLE_NGHTTP2` | `USE_NGHTTP2=ON` 581 `ENABLE_OPENSSL_AUTO_LOAD_CONFIG` | `CURL_DISABLE_OPENSSL_AUTO_LOAD_CONFIG=OFF` (default) 582 `ENABLE_SCHANNEL` | `CURL_USE_SCHANNEL=ON` 583 `ENABLE_SSPI` | `CURL_WINDOWS_SSPI=ON` (default with Schannel) 584 `ENABLE_UNICODE` | `ENABLE_UNICODE=ON` 585 `WITH_PREFIX` | `CMAKE_INSTALL_PREFIX=<path>` 586 `WITH_DEVEL` | see individual `*_INCLUDE_DIR` and `*_LIBRARY` options and `OPENSSL_ROOT_DIR` 587 `WITH_CARES`, `CARES_PATH` | `ENABLE_ARES=ON`, optional: `CARES_INCLUDE_DIR`, `CARES_LIBRARY` 588 `WITH_MBEDTLS`, `MBEDTLS_PATH` | `CURL_USE_MBEDTLS=ON`, optional: `MBEDTLS_INCLUDE_DIR`, `MBEDTLS_LIBRARY`, `MBEDX509_LIBRARY`, `MBEDCRYPTO_LIBRARY` 589 `WITH_MSH3`, `MSH_PATH` | `USE_MSH3=ON`, optional: `MSH3_INCLUDE_DIR`, `MSH3_LIBRARY` 590 `WITH_NGHTTP2`, `NGHTTP2_PATH` | `USE_NGHTTP2=ON`, optional: `NGHTTP2_INCLUDE_DIR`, `NGHTTP2_LIBRARY` 591 `WITH_SSH`, `SSH_PATH` | `CURL_USE_LIBSSH=ON`, optional: `LIBSSH_INCLUDE_DIR`, `LIBSSH_LIBRARY` 592 `WITH_SSH2`, `SSH2_PATH` | `CURL_USE_LIBSSH2=ON`, optional: `LIBSSH2_INCLUDE_DIR`, `LIBSSH2_LIBRARY` 593 `WITH_SSL`, `SSL_PATH` | `CURL_USE_OPENSSL=ON`, optional: `OPENSSL_ROOT_DIR`, `OPENSSL_USE_STATIC_LIBS=ON` 594 `WITH_WOLFSSL`, `WOLFSSL_PATH` | `CURL_USE_WOLFSSL=ON`, optional: `WOLFSSL_INCLUDE_DIR`, `WOLFSSL_LIBRARY` 595 `WITH_ZLIB`, `ZLIB_PATH` | `CURL_ZLIB=ON`, optional: `ZLIB_INCLUDE_DIR`, `ZLIB_LIBRARY` 596 597 For example this command-line: 598 599 > nmake -f Makefile.vc VC=17 MACHINE=x64 DEBUG=ON mode=dll SSL_PATH=C:\OpenSSL WITH_SSL=dll ENABLE_UNICODE=ON 600 601 translates to: 602 603 > cmake . -G "Visual Studio 17 2022" -A x64 -DBUILD_SHARED_LIBS=ON -DOPENSSL_ROOT_DIR=C:\OpenSSL -DCURL_USE_OPENSSL=ON -DENABLE_UNICODE=ON -DCURL_USE_LIBPSL=OFF 604 > cmake --build . --config Debug 605 606 We use `--config` with `cmake --build` because the Visual Studio CMake 607 generators are multi-config and therefore ignore `CMAKE_BUILD_TYPE`.