1                                  _   _ ____  _
2                              ___| | | |  _ \| |
3                             / __| | | | |_) | |
4                            | (__| |_| |  _ <| |___
5                             \___|\___/|_| \_\_____|
6
7                                How To Compile with CMake
8
9Building with CMake
10==========================
11   This document describes how to compile, build and install curl and libcurl
12   from source code using the CMake build tool. To build with CMake, you will
13   of course have to first install CMake.  The minimum required version of
14   CMake is specified in the file CMakeLists.txt found in the top of the curl
15   source tree. Once the correct version of CMake is installed you can follow
16   the instructions below for the platform you are building on.
17
18   CMake builds can be configured either from the command line, or from one
19   of CMake's GUI's.
20
21Current flaws in the curl CMake build
22=====================================
23
24   Missing features in the cmake build:
25
26   - Builds libcurl without large file support
27   - Can't select which SSL library to build with, only OpenSSL
28   - Doesn't build with SCP and SFTP support (libssh2)
29   - Doesn't allow different resolver backends (no c-ares build support)
30   - No RTMP support built
31   - Doesn't allow build curl and libcurl debug enabled
32   - Doesn't allow a custom CA bundle path
33   - Doesn't allow you to disable specific protocols from the build
34   - Doesn't find or use krb4 or GSS
35   - Rebuilds test files too eagerly, but still can't run the tests
36
37
38Important notice
39==================
40   If you got your curl sources from a distribution tarball, make sure to
41   delete the generic 'include/curl/curlbuild.h' file that comes with it:
42       rm -f curl/include/curl/curlbuild.h
43
44   The purpose of this file is to provide reasonable definitions for systems
45   where autoconfiguration is not available. CMake will create its own
46   version of this file in its build directory. If the "generic" version
47   is not deleted, weird build errors may occur on some systems.
48
49Command Line CMake
50==================
51   A CMake build of curl is similar to the autotools build of curl. It
52   consists of the following steps after you have unpacked the source.
53
54    1. Create an out of source build tree parallel to the curl source
55       tree and change into that directory
56
57    $ mkdir curl-build
58    $ cd curl-build
59
60    2. Run CMake from the build tree, giving it the path to the top of
61       the curl source tree.  CMake will pick a compiler for you. If you
62       want to specify the compile, you can set the CC environment
63       variable prior to running CMake.
64
65    $ cmake ../curl
66    $ make
67
68    3. Install to default location:
69
70    $ make install
71
72    (The test suite does not work with the cmake build)
73
74ccmake
75=========
76     CMake comes with a curses based interface called ccmake.  To run ccmake on
77     a curl use the instructions for the command line cmake, but substitute
78     ccmake ../curl for cmake ../curl.  This will bring up a curses interface
79     with instructions on the bottom of the screen. You can press the "c" key
80     to configure the project, and the "g" key to generate the project. After
81     the project is generated, you can run make.
82
83cmake-gui
84=========
85     CMake also comes with a Qt based GUI called cmake-gui. To configure with
86     cmake-gui, you run cmake-gui and follow these steps:
87        1. Fill in the "Where is the source code" combo box with the path to
88        the curl source tree.
89        2. Fill in the "Where to build the binaries" combo box with the path
90        to the directory for your build tree, ideally this should not be the
91        same as the source tree, but a parallel directory called curl-build or
92        something similar.
93        3. Once the source and binary directories are specified, press the
94        "Configure" button.
95        4. Select the native build tool that you want to use.
96        5. At this point you can change any of the options presented in the
97        GUI.  Once you have selected all the options you want, click the
98        "Generate" button.
99        6. Run the native build tool that you used CMake to generate.
100
101