mirror/curl
2
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2024-12-09 06:30:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

cmake: freshen up docs/INSTALL.cmake

Browse Source 
- 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
This commit is contained in:
Richard Levitte 2024-01-24 13:07:00 +01:00 committed by Daniel Stenberg
parent 5b286c2508
commit 0f4c19b66a
No known key found for this signature in database
GPG Key ID: 5CC908FDB71E12C2
4 changed files with 136 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/scripts/spellcheck.words vendored
View File

@ -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

133
docs/INSTALL-CMAKE.md Normal file
View File

@ -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

89
docs/INSTALL.cmake
View File

@ -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.

2
docs/Makefile.am
View File

@ -72,7 +72,7 @@ EXTRA_DIST = \
HTTP3.md \
HYPER.md \
INSTALL \
INSTALL.cmake \
INSTALL-CMAKE.md \
INSTALL.md \
INTERNALS.md \
KNOWN_BUGS \