From 0f4c19b66ad5c646ebc3c4268a0f3ad9c15bf57c Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Wed, 24 Jan 2024 13:07:00 +0100 Subject: [PATCH] cmake: freshen up docs/INSTALL.cmake - 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 --- .github/scripts/spellcheck.words | 2 + docs/INSTALL-CMAKE.md | 133 +++++++++++++++++++++++++++++++ docs/INSTALL.cmake | 89 --------------------- docs/Makefile.am | 2 +- 4 files changed, 136 insertions(+), 90 deletions(-) create mode 100644 docs/INSTALL-CMAKE.md delete mode 100644 docs/INSTALL.cmake diff --git a/.github/scripts/spellcheck.words b/.github/scripts/spellcheck.words index 974f02926..4495454e1 100644 --- a/.github/scripts/spellcheck.words +++ b/.github/scripts/spellcheck.words @@ -111,6 +111,7 @@ clientp cliget closesocket CMake +CMake's cmake cmake's CMakeLists @@ -288,6 +289,7 @@ GSS GSSAPI GTFO Guenter +GUIs Gunderson Gustafsson gzip diff --git a/docs/INSTALL-CMAKE.md b/docs/INSTALL-CMAKE.md new file mode 100644 index 000000000..6dad38740 --- /dev/null +++ b/docs/INSTALL-CMAKE.md @@ -0,0 +1,133 @@ + _ _ ____ _ + ___| | | | _ \| | + / __| | | | |_) | | + | (__| |_| | _ <| |___ + \___|\___/|_| \_\_____| + + How To Compile with CMake + +# Building with CMake + +This document describes how to configure, build and install curl and libcurl +from source code using the CMake build tool. To build with CMake, you will +of course have to first install CMake. The minimum required version of CMake +is specified in the file `CMakeLists.txt` found in the top of the curl +source tree. Once the correct version of CMake is installed you can follow +the instructions below for the platform you are building on. + +CMake builds can be configured either from the command line, or from one of +CMake's GUIs. + +# Current flaws in the curl CMake build + +Missing features in the CMake build: + + - Builds libcurl without large file support + - Does not support all SSL libraries (only OpenSSL, Schannel, Secure + Transport, and mbedTLS, WolfSSL) + - Does not allow different resolver backends (no c-ares build support) + - No RTMP support built + - Does not allow build curl and libcurl debug enabled + - Does not allow a custom CA bundle path + - Does not allow you to disable specific protocols from the build + - Does not find or use krb4 or GSS + - Rebuilds test files too eagerly, but still cannot run the tests + - Does not detect the correct `strerror_r` flavor when cross-compiling + (issue #1123) + +# Configuring + +A CMake configuration of curl is similar to the autotools build of curl. +It consists of the following steps after you have unpacked the source. + +## Using `cmake` + +You can configure for in source tree builds or for a build tree +that is apart from the source tree. + + - Build in the source tree. + + $ cmake -B . + + - Build in a separate directory (parallel to the curl source tree in this + example). The build directory will be created for you. + + $ cmake -B ../curl-build + +### Fallback for CMake before version 3.13 + +CMake before version 3.13 does not support the `-B` option. In that case, +you must create the build directory yourself, `cd` to it and run `cmake` +from there: + + $ mkdir ../curl-build + $ cd ../curl-build + $ cmake ../curl + +If you want to build in the source tree, it is enough to do this: + + $ cmake . + +## Using `ccmake` + +CMake comes with a curses based interface called `ccmake`. To run `ccmake` +on a curl use the instructions for the command line cmake, but substitute +`ccmake` for `cmake`. + +This will bring up a curses interface with instructions on the bottom of the +screen. You can press the "c" key to configure the project, and the "g" key +to generate the project. After the project is generated, you can run make. + +## Using `cmake-gui` + +CMake also comes with a Qt based GUI called `cmake-gui`. To configure with +`cmake-gui`, you run `cmake-gui` and follow these steps: + + 1. Fill in the "Where is the source code" combo box with the path to + the curl source tree. + 2. Fill in the "Where to build the binaries" combo box with the path to + the directory for your build tree, ideally this should not be the same + as the source tree, but a parallel directory called curl-build or + something similar. + 3. Once the source and binary directories are specified, press the + "Configure" button. + 4. Select the native build tool that you want to use. + 5. At this point you can change any of the options presented in the GUI. + Once you have selected all the options you want, click the "Generate" + button. + +# Building + +Build (you have to specify the build directory). + + $ cmake --build ../curl-build + +### Fallback for CMake before version 3.13 + +CMake before version 3.13 does not support the `--build` option. In that +case, you have to `cd` to the build directory and use the building tool that +corresponds to the build files that CMake generated for you. This example +assumes that CMake generates `Makefile`: + + $ cd ../curl-build + $ make + +# Testing + +(The test suite does not yet work with the cmake build) + +# Installing + +Install to default location (you have to specify the build directory). + + $ cmake --install ../curl-build + +### Fallback for CMake before version 3.15 + +CMake before version 3.15 does not support the `--install` option. In that +case, you have to `cd` to the build directory and use the building tool that +corresponds to the build files that CMake generated for you. This example +assumes that CMake generates `Makefile`: + + $ cd ../curl-build + $ make install diff --git a/docs/INSTALL.cmake b/docs/INSTALL.cmake deleted file mode 100644 index 4e7f706a9..000000000 --- a/docs/INSTALL.cmake +++ /dev/null @@ -1,89 +0,0 @@ - _ _ ____ _ - ___| | | | _ \| | - / __| | | | |_) | | - | (__| |_| | _ <| |___ - \___|\___/|_| \_\_____| - - How To Compile with CMake - -Building with CMake -========================== - This document describes how to compile, build and install curl and libcurl - from source code using the CMake build tool. To build with CMake, you will - of course have to first install CMake. The minimum required version of - CMake is specified in the file CMakeLists.txt found in the top of the curl - source tree. Once the correct version of CMake is installed you can follow - the instructions below for the platform you are building on. - - CMake builds can be configured either from the command line, or from one - of CMake's GUI's. - -Current flaws in the curl CMake build -===================================== - - Missing features in the cmake build: - - - Builds libcurl without large file support - - Does not support all SSL libraries (only OpenSSL, Schannel, - Secure Transport, and mbedTLS, WolfSSL) - - Does not allow different resolver backends (no c-ares build support) - - No RTMP support built - - Does not allow build curl and libcurl debug enabled - - Does not allow a custom CA bundle path - - Does not allow you to disable specific protocols from the build - - Does not find or use krb4 or GSS - - Rebuilds test files too eagerly, but still cannot run the tests - - Does not detect the correct strerror_r flavor when cross-compiling (issue #1123) - - -Command Line CMake -================== - A CMake build of curl is similar to the autotools build of curl. It - consists of the following steps after you have unpacked the source. - - 1. Create an out of source build tree parallel to the curl source - tree and change into that directory - - $ mkdir curl-build - $ cd curl-build - - 2. Run CMake from the build tree, giving it the path to the top of - the curl source tree. CMake will pick a compiler for you. If you - want to specify the compile, you can set the CC environment - variable prior to running CMake. - - $ cmake ../curl - $ make - - 3. Install to default location: - - $ make install - - (The test suite does not work with the cmake build) - -ccmake -========= - CMake comes with a curses based interface called ccmake. To run ccmake on - a curl use the instructions for the command line cmake, but substitute - ccmake ../curl for cmake ../curl. This will bring up a curses interface - with instructions on the bottom of the screen. You can press the "c" key - to configure the project, and the "g" key to generate the project. After - the project is generated, you can run make. - -cmake-gui -========= - CMake also comes with a Qt based GUI called cmake-gui. To configure with - cmake-gui, you run cmake-gui and follow these steps: - 1. Fill in the "Where is the source code" combo box with the path to - the curl source tree. - 2. Fill in the "Where to build the binaries" combo box with the path - to the directory for your build tree, ideally this should not be the - same as the source tree, but a parallel directory called curl-build or - something similar. - 3. Once the source and binary directories are specified, press the - "Configure" button. - 4. Select the native build tool that you want to use. - 5. At this point you can change any of the options presented in the - GUI. Once you have selected all the options you want, click the - "Generate" button. - 6. Run the native build tool that you used CMake to generate. diff --git a/docs/Makefile.am b/docs/Makefile.am index b3f2b07c8..fbe94c40e 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -72,7 +72,7 @@ EXTRA_DIST = \ HTTP3.md \ HYPER.md \ INSTALL \ - INSTALL.cmake \ + INSTALL-CMAKE.md \ INSTALL.md \ INTERNALS.md \ KNOWN_BUGS \