1<!-- 2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 4SPDX-License-Identifier: curl 5--> 6 7# Building with CMake 8 9This document describes how to configure, build and install curl and libcurl 10from source code using the CMake build tool. To build with CMake, you of 11course first have to install CMake. The minimum required version of CMake is 12specified in the file `CMakeLists.txt` found in the top of the curl source 13tree. Once the correct version of CMake is installed you can follow the 14instructions below for the platform you are building on. 15 16CMake builds can be configured either from the command line, or from one of 17CMake's GUIs. 18 19# Current flaws in the curl CMake build 20 21Missing features in the CMake build: 22 23 - Builds libcurl without large file support 24 - Does not support all SSL libraries (only OpenSSL, Schannel, Secure 25 Transport, and mbedTLS, WolfSSL) 26 - Does not allow different resolver backends (no c-ares build support) 27 - No RTMP support built 28 - Does not allow build curl and libcurl debug enabled 29 - Does not allow a custom CA bundle path 30 - Does not allow you to disable specific protocols from the build 31 - Does not find or use krb4 or GSS 32 - Rebuilds test files too eagerly, but still cannot run the tests 33 - Does not detect the correct `strerror_r` flavor when cross-compiling 34 (issue #1123) 35 36# Configuring 37 38A CMake configuration of curl is similar to the autotools build of curl. 39It consists of the following steps after you have unpacked the source. 40 41## Using `cmake` 42 43You can configure for in source tree builds or for a build tree 44that is apart from the source tree. 45 46 - Build in the source tree. 47 48 $ cmake -B . 49 50 - Build in a separate directory (parallel to the curl source tree in this 51 example). The build directory is created for you. 52 53 $ cmake -B ../curl-build 54 55### Fallback for CMake before version 3.13 56 57CMake before version 3.13 does not support the `-B` option. In that case, 58you must create the build directory yourself, `cd` to it and run `cmake` 59from there: 60 61 $ mkdir ../curl-build 62 $ cd ../curl-build 63 $ cmake ../curl 64 65If you want to build in the source tree, it is enough to do this: 66 67 $ cmake . 68 69### Build system generator selection 70 71You can override CMake's default by using `-G <generator-name>`. For example 72on Windows with multiple build systems if you have MinGW-w64 then you could use 73`-G "MinGW Makefiles"`. 74[List of generator names](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html). 75 76## Using `ccmake` 77 78CMake comes with a curses based interface called `ccmake`. To run `ccmake` 79on a curl use the instructions for the command line cmake, but substitute 80`ccmake` for `cmake`. 81 82This brings up a curses interface with instructions on the bottom of the 83screen. You can press the "c" key to configure the project, and the "g" key to 84generate the project. After the project is generated, you can run make. 85 86## Using `cmake-gui` 87 88CMake also comes with a Qt based GUI called `cmake-gui`. To configure with 89`cmake-gui`, you run `cmake-gui` and follow these steps: 90 91 1. Fill in the "Where is the source code" combo box with the path to 92 the curl source tree. 93 2. Fill in the "Where to build the binaries" combo box with the path to 94 the directory for your build tree, ideally this should not be the same 95 as the source tree, but a parallel directory called curl-build or 96 something similar. 97 3. Once the source and binary directories are specified, press the 98 "Configure" button. 99 4. Select the native build tool that you want to use. 100 5. At this point you can change any of the options presented in the GUI. 101 Once you have selected all the options you want, click the "Generate" 102 button. 103 104# Building 105 106Build (you have to specify the build directory). 107 108 $ cmake --build ../curl-build 109 110### Fallback for CMake before version 3.13 111 112CMake before version 3.13 does not support the `--build` option. In that 113case, you have to `cd` to the build directory and use the building tool that 114corresponds to the build files that CMake generated for you. This example 115assumes that CMake generates `Makefile`: 116 117 $ cd ../curl-build 118 $ make 119 120# Testing 121 122(The test suite does not yet work with the cmake build) 123 124# Installing 125 126Install to default location (you have to specify the build directory). 127 128 $ cmake --install ../curl-build 129 130### Fallback for CMake before version 3.15 131 132CMake before version 3.15 does not support the `--install` option. In that 133case, you have to `cd` to the build directory and use the building tool that 134corresponds to the build files that CMake generated for you. This example 135assumes that CMake generates `Makefile`: 136 137 $ cd ../curl-build 138 $ make install 139
