README.rst

   1 CMake
   2 *****
   3
   4 Introduction
   5 ============
   6
   7 CMake is a cross-platform, open-source build system generator.
   8 For full documentation visit the `CMake Home Page`_ and the
   9 `CMake Documentation Page`_. The `CMake Community Wiki`_ also
  10 references useful guides and recipes.
  11
  12 .. _`CMake Home Page`: https://cmake.org
  13 .. _`CMake Documentation Page`: https://cmake.org/documentation
  14 .. _`CMake Community Wiki`: https://gitlab.kitware.com/cmake/community/-/wikis/home
  15
  16 CMake is maintained and supported by `Kitware`_ and developed in
  17 collaboration with a productive community of contributors.
  18
  19 .. _`Kitware`: https://www.kitware.com/cmake
  20
  21 License
  22 =======
  23
  24 CMake is distributed under the OSI-approved BSD 3-clause License.
  25 See `Copyright.txt`_ for details.
  26
  27 .. _`Copyright.txt`: Copyright.txt
  28
  29 Building CMake
  30 ==============
  31
  32 Supported Platforms
  33 -------------------
  34
  35 * Microsoft Windows
  36 * Apple macOS
  37 * Linux
  38 * FreeBSD
  39 * OpenBSD
  40 * Solaris
  41 * AIX
  42
  43 Other UNIX-like operating systems may work too out of the box, if not
  44 it should not be a major problem to port CMake to this platform.
  45 Please post to the `CMake Discourse Forum`_ to ask if others have
  46 had experience with the platform.
  47
  48 .. _`CMake Discourse Forum`: https://discourse.cmake.org
  49
  50 Building CMake with CMake
  51 -------------------------
  52
  53 You can build CMake as any other project with a CMake-based build system:
  54 run an already-installed CMake on this source tree with your preferred
  55 generator and options.  Then build it and install it.
  56
  57 To build the documentation, install `Sphinx`_ and configure CMake with
  58 ``-DSPHINX_HTML=ON`` and/or ``-DSPHINX_MAN=ON`` to enable the "html" or
  59 "man" builder.  Add ``-DSPHINX_EXECUTABLE=/path/to/sphinx-build`` if the
  60 tool is not found automatically.
  61
  62 To run the test suite, run ``ctest`` in the CMake build directory after
  63 building.  See the `CMake Testing Guide`_ for details.
  64
  65 .. _`Sphinx`: https://sphinx-doc.org
  66 .. _`CMake Testing Guide`: Help/dev/testing.rst
  67
  68 Building CMake from Scratch
  69 ---------------------------
  70
  71 UNIX/Mac OSX/MinGW/MSYS/Cygwin
  72 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  73
  74 You need to have a C++ compiler (supporting C++11) and a ``make`` installed.
  75 Run the ``bootstrap`` script you find in the source directory of CMake.
  76 You can use the ``--help`` option to see the supported options.
  77 You may use the ``--prefix=<install_prefix>`` option to specify a custom
  78 installation directory for CMake.  Once this has finished successfully,
  79 run ``make`` and ``make install``.
  80
  81 For example, if you simply want to build and install CMake from source,
  82 you can build directly in the source tree::
  83
  84   $ ./bootstrap && make && sudo make install
  85
  86 Or, if you plan to develop CMake or otherwise run the test suite, create
  87 a separate build tree::
  88
  89   $ mkdir build && cd build
  90   $ ../bootstrap && make
  91
  92 Windows
  93 ^^^^^^^
  94
  95 There are two ways for building CMake under Windows:
  96
  97 1. Compile with MSVC from VS 2015 or later.
  98    You need to download and install a binary release of CMake.  You can get
  99    these releases from the `CMake Download Page`_.  Then proceed with the
 100    instructions above for `Building CMake with CMake`_.
 101
 102 2. Bootstrap with MinGW under MSYS2.
 103    Download and install `MSYS2`_.  Then install the required build tools::
 104
 105      $ pacman -S --needed git base-devel mingw-w64-x86_64-gcc
 106
 107    and bootstrap as above.
 108
 109 .. _`CMake Download Page`: https://cmake.org/download
 110 .. _`MSYS2`: https://www.msys2.org/
 111
 112 Reporting Bugs
 113 ==============
 114
 115 If you have found a bug:
 116
 117 1. If you have a patch, please read the `CONTRIBUTING.rst`_ document.
 118
 119 2. Otherwise, please post to the `CMake Discourse Forum`_ and ask about
 120    the expected and observed behaviors to determine if it is really
 121    a bug.
 122
 123 3. Finally, if the issue is not resolved by the above steps, open
 124    an entry in the `CMake Issue Tracker`_.
 125
 126 .. _`CMake Issue Tracker`: https://gitlab.kitware.com/cmake/cmake/-/issues
 127
 128 Contributing
 129 ============
 130
 131 See `CONTRIBUTING.rst`_ for instructions to contribute.
 132
 133 .. _`CONTRIBUTING.rst`: CONTRIBUTING.rst