Browse Source

Help: cmake (1): put modern configure signature first

recommend compact, most robust signature first. So many people are
still using the multi-step pre-3.13 way of initializing a build.
Rather than simply

  cmake -Bbuild

which is one step instead of 3 just to configure a new project.
scivision 2 years ago
parent
commit
f0e60ea867
3 changed files with 20 additions and 19 deletions
  1. 1 0
      Help/manual/ccmake.1.rst
  2. 1 1
      Help/manual/cmake-gui.1.rst
  3. 18 18
      Help/manual/cmake.1.rst

+ 1 - 0
Help/manual/ccmake.1.rst

@@ -8,6 +8,7 @@ Synopsis
 
 
 .. parsed-literal::
 .. parsed-literal::
 
 
+ ccmake [<options>] -B <path-to-build> [-S <path-to-source>]
  ccmake [<options>] <path-to-source | path-to-existing-build>
  ccmake [<options>] <path-to-source | path-to-existing-build>
 
 
 Description
 Description

+ 1 - 1
Help/manual/cmake-gui.1.rst

@@ -9,8 +9,8 @@ Synopsis
 .. parsed-literal::
 .. parsed-literal::
 
 
  cmake-gui [<options>]
  cmake-gui [<options>]
+ cmake-gui [<options>] -B <path-to-build> [-S <path-to-source>]
  cmake-gui [<options>] <path-to-source | path-to-existing-build>
  cmake-gui [<options>] <path-to-source | path-to-existing-build>
- cmake-gui [<options>] -S <path-to-source> -B <path-to-build>
  cmake-gui [<options>] --browse-manual [<filename>]
  cmake-gui [<options>] --browse-manual [<filename>]
 
 
 Description
 Description

+ 18 - 18
Help/manual/cmake.1.rst

@@ -9,8 +9,8 @@ Synopsis
 .. parsed-literal::
 .. parsed-literal::
 
 
  `Generate a Project Buildsystem`_
  `Generate a Project Buildsystem`_
+  cmake [<options>] -B <path-to-build> [-S <path-to-source>]
   cmake [<options>] <path-to-source | path-to-existing-build>
   cmake [<options>] <path-to-source | path-to-existing-build>
-  cmake [<options>] -S <path-to-source> -B <path-to-build>
 
 
  `Build a Project`_
  `Build a Project`_
   cmake --build <dir> [<options>] [-- <build-tool-options>]
   cmake --build <dir> [<options>] [-- <build-tool-options>]
@@ -116,6 +116,20 @@ Generate a Project Buildsystem
 Run CMake with one of the following command signatures to specify the
 Run CMake with one of the following command signatures to specify the
 source and build trees and generate a buildsystem:
 source and build trees and generate a buildsystem:
 
 
+``cmake [<options>] -B <path-to-build> [-S <path-to-source>]``
+
+  .. versionadded:: 3.13
+
+  Uses ``<path-to-build>`` as the build tree and ``<path-to-source>``
+  as the source tree.  The specified paths may be absolute or relative
+  to the current working directory.  The source tree must contain a
+  ``CMakeLists.txt`` file.  The build tree will be created automatically
+  if it does not already exist.  For example:
+
+  .. code-block:: console
+
+    $ cmake -S src -B build
+
 ``cmake [<options>] <path-to-source>``
 ``cmake [<options>] <path-to-source>``
   Uses the current working directory as the build tree, and
   Uses the current working directory as the build tree, and
   ``<path-to-source>`` as the source tree.  The specified path may
   ``<path-to-source>`` as the source tree.  The specified path may
@@ -141,20 +155,6 @@ source and build trees and generate a buildsystem:
     $ cd build
     $ cd build
     $ cmake .
     $ cmake .
 
 
-``cmake [<options>] -S <path-to-source> -B <path-to-build>``
-
-  .. versionadded:: 3.13
-
-  Uses ``<path-to-build>`` as the build tree and ``<path-to-source>``
-  as the source tree.  The specified paths may be absolute or relative
-  to the current working directory.  The source tree must contain a
-  ``CMakeLists.txt`` file.  The build tree will be created automatically
-  if it does not already exist.  For example:
-
-  .. code-block:: console
-
-    $ cmake -S src -B build
-
 In all cases the ``<options>`` may be zero or more of the `Options`_ below.
 In all cases the ``<options>`` may be zero or more of the `Options`_ below.
 
 
 The above styles for specifying the source and build trees may be mixed.
 The above styles for specifying the source and build trees may be mixed.
@@ -167,14 +167,14 @@ the current working directory (cwd) is used for the other.  For example:
 ============================== ============ ===========
 ============================== ============ ===========
  Command Line                   Source Dir   Build Dir
  Command Line                   Source Dir   Build Dir
 ============================== ============ ===========
 ============================== ============ ===========
+ ``cmake -B build``             `cwd`        ``build``
+ ``cmake -B build src``         ``src``      ``build``
+ ``cmake -B build -S src``      ``src``      ``build``
  ``cmake src``                  ``src``      `cwd`
  ``cmake src``                  ``src``      `cwd`
  ``cmake build`` (existing)     `loaded`     ``build``
  ``cmake build`` (existing)     `loaded`     ``build``
  ``cmake -S src``               ``src``      `cwd`
  ``cmake -S src``               ``src``      `cwd`
  ``cmake -S src build``         ``src``      ``build``
  ``cmake -S src build``         ``src``      ``build``
  ``cmake -S src -B build``      ``src``      ``build``
  ``cmake -S src -B build``      ``src``      ``build``
- ``cmake -B build``             `cwd`        ``build``
- ``cmake -B build src``         ``src``      ``build``
- ``cmake -B build -S src``      ``src``      ``build``
 ============================== ============ ===========
 ============================== ============ ===========
 
 
 .. versionchanged:: 3.23
 .. versionchanged:: 3.23