docs/INSTALL.cmake

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