From 3043c17039b8aa14c1a3ffdaef70ab4010c1be20 Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Thu, 20 Oct 2022 06:56:17 +0400 Subject: Help: Add more CLI `:option:` references to various pages --- Help/command/build_command.rst | 8 ++++---- Help/command/ctest_build.rst | 6 +++--- Help/command/set.rst | 2 +- Help/generator/Xcode.rst | 2 +- .../Adding Usage Requirements for a Library.rst | 4 ++-- Help/guide/tutorial/Installing and Testing.rst | 23 +++++++++++----------- Help/manual/ctest.1.rst | 6 +++--- Help/prop_test/FIXTURES_REQUIRED.rst | 9 +++++---- Help/variable/CMAKE_COMMAND.rst | 2 +- .../CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst | 2 +- Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst | 2 +- Modules/CTest.cmake | 2 +- 12 files changed, 35 insertions(+), 33 deletions(-) diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst index a03979d..3d86a2e 100644 --- a/Help/command/build_command.rst +++ b/Help/command/build_command.rst @@ -24,12 +24,12 @@ options, if any. The trailing ``-- -i`` option is added for :ref:`Makefile Generators` if policy :policy:`CMP0061` is not set to ``NEW``. -When invoked, this ``cmake --build`` command line will launch the +When invoked, this :option:`cmake --build` command line will launch the underlying build system tool. .. versionadded:: 3.21 - The ``PARALLEL_LEVEL`` argument can be used to set the ``--parallel`` - flag. + The ``PARALLEL_LEVEL`` argument can be used to set the + :option:`--parallel ` flag. .. code-block:: cmake @@ -39,7 +39,7 @@ This second signature is deprecated, but still available for backwards compatibility. Use the first signature instead. It sets the given ```` to a command-line string as -above but without the ``--target`` option. +above but without the :option:`--target ` option. The ```` is ignored but should be the full path to devenv, nmake, make or one of the end user build tools for legacy invocations. diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst index e05df1a..8c81f2d 100644 --- a/Help/command/ctest_build.rst +++ b/Help/command/ctest_build.rst @@ -40,8 +40,8 @@ The options are: ``CONFIGURATION `` Specify the build configuration (e.g. ``Debug``). If not specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked. - Otherwise the ``-C `` option given to the :manual:`ctest(1)` - command will be used, if any. + Otherwise the :option:`-C \ ` option given to the + :manual:`ctest(1)` command will be used, if any. ``PARALLEL_LEVEL `` .. versionadded:: 3.21 @@ -54,7 +54,7 @@ The options are: Pass additional arguments to the underlying build command. If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked. This can, e.g., be used to trigger a parallel build using the - ``-j`` option of make. See the :module:`ProcessorCount` module + ``-j`` option of ``make``. See the :module:`ProcessorCount` module for an example. ``PROJECT_NAME `` diff --git a/Help/command/set.rst b/Help/command/set.rst index 5e05d9b..90b57d2 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -83,7 +83,7 @@ option is given then the cache entry will be set to the given value. It is possible for the cache entry to exist prior to the call but have no type set if it was created on the :manual:`cmake(1)` command -line by a user through the ``-D=`` option without +line by a user through the :option:`-D\=\ ` option without specifying a type. In this case the ``set`` command will add the type. Furthermore, if the ```` is ``PATH`` or ``FILEPATH`` and the ```` provided on the command line is a relative path, diff --git a/Help/generator/Xcode.rst b/Help/generator/Xcode.rst index a66f483..9dd5015 100644 --- a/Help/generator/Xcode.rst +++ b/Help/generator/Xcode.rst @@ -34,7 +34,7 @@ Supported pairs are: See the :variable:`CMAKE_XCODE_BUILD_SYSTEM` variable for allowed values. For example, to select the original build system under Xcode 12, - run :manual:`cmake(1)` with the option ``-T buildsystem=1``. + run :manual:`cmake(1)` with the option :option:`-T buildsystem=1 `. Swift Support ^^^^^^^^^^^^^ diff --git a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst index f9dc7cc..4aef050 100644 --- a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst +++ b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst @@ -63,8 +63,8 @@ Build and Run Make a new directory called ``Step3_build``, run the :manual:`cmake ` executable or the :manual:`cmake-gui ` to configure the project and then build it with your chosen build tool or by -using ``cmake --build .`` from the build directory. Here's a refresher of -what that looks like from the command line: +using :option:`cmake --build . ` from the build directory. +Here's a refresher of what that looks like from the command line: .. code-block:: console diff --git a/Help/guide/tutorial/Installing and Testing.rst b/Help/guide/tutorial/Installing and Testing.rst index 3969192..fa13040 100644 --- a/Help/guide/tutorial/Installing and Testing.rst +++ b/Help/guide/tutorial/Installing and Testing.rst @@ -52,17 +52,18 @@ Make a new directory called ``Step5_build``. Run the :manual:`cmake-gui ` to configure the project and then build it with your chosen build tool. -Then, run the install step by using the ``install`` option of the -:manual:`cmake ` command (introduced in 3.15, older versions of -CMake must use ``make install``) from the command line. This step will -install the appropriate header files, libraries, and executables. For example: +Then, run the install step by using the :option:`--install ` +option of the :manual:`cmake ` command (introduced in 3.15, older +versions of CMake must use ``make install``) from the command line. This step +will install the appropriate header files, libraries, and executables. +For example: .. code-block:: console cmake --install . -For multi-configuration tools, don't forget to use the ``--config`` argument to -specify the configuration. +For multi-configuration tools, don't forget to use the +:option:`--config ` argument to specify the configuration. .. code-block:: console @@ -76,9 +77,9 @@ install target from the command line like the following: cmake --build . --target install --config Debug The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the -root of where the files will be installed. If using the ``cmake --install`` -command, the installation prefix can be overridden via the ``--prefix`` -argument. For example: +root of where the files will be installed. If using the :option:`cmake --install` +command, the installation prefix can be overridden via the +:option:`--prefix ` argument. For example: .. code-block:: console @@ -194,9 +195,9 @@ Build and Run ------------- Navigate to the build directory and rebuild the application. Then, run the -:manual:`ctest ` executable: ``ctest -N`` and ``ctest -VV``. For +``ctest`` executable: :option:`ctest -N` and :option:`ctest -VV`. For multi-config generators (e.g. Visual Studio), the configuration type must be -specified with the ``-C `` flag. For example, to run tests in Debug +specified with the :option:`-C \ ` flag. For example, to run tests in Debug mode use ``ctest -C Debug -VV`` from the build directory (not the Debug subdirectory!). Release mode would be executed from the same location but with a ``-C Release``. Alternatively, build the ``RUN_TESTS`` diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index fe81a46..1e691be 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -1627,12 +1627,12 @@ Resource Specification File --------------------------- The resource specification file is a JSON file which is passed to CTest, either -on the :manual:`ctest(1)` command line as ``--resource-spec-file``, or as the +on the command line as :option:`ctest --resource-spec-file`, or as the ``RESOURCE_SPEC_FILE`` argument of :command:`ctest_test`. If a dashboard script is used and ``RESOURCE_SPEC_FILE`` is not specified, the value of :variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script is used instead. -If ``--resource-spec-file``, ``RESOURCE_SPEC_FILE``, and -:variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script are not specified, +If :option:`--resource-spec-file `, ``RESOURCE_SPEC_FILE``, +and :variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script are not specified, the value of :variable:`CTEST_RESOURCE_SPEC_FILE` in the CMake build is used instead. If none of these are specified, no resource spec file is used. diff --git a/Help/prop_test/FIXTURES_REQUIRED.rst b/Help/prop_test/FIXTURES_REQUIRED.rst index f850830..7a05601 100644 --- a/Help/prop_test/FIXTURES_REQUIRED.rst +++ b/Help/prop_test/FIXTURES_REQUIRED.rst @@ -19,10 +19,11 @@ be executed. The cleanup tests for the fixture will always be executed, even if some setup tests fail. When CTest is asked to execute only a subset of tests (e.g. by the use of -regular expressions or when run with the ``--rerun-failed`` command line -option), it will automatically add any setup or cleanup tests for fixtures -required by any of the tests that are in the execution set. This behavior can -be overridden with the ``-FS``, ``-FC`` and ``-FA`` command line options to +regular expressions or when run with the :option:`--rerun-failed ` +command line option), it will automatically add any setup or cleanup tests for +fixtures required by any of the tests that are in the execution set. This +behavior can be overridden with the :option:`-FS `, +:option:`-FC ` and :option:`-FA ` command line options to :manual:`ctest(1)` if desired. Since setup and cleanup tasks are also tests, they can have an ordering diff --git a/Help/variable/CMAKE_COMMAND.rst b/Help/variable/CMAKE_COMMAND.rst index f80b46c..e65ff8c 100644 --- a/Help/variable/CMAKE_COMMAND.rst +++ b/Help/variable/CMAKE_COMMAND.rst @@ -4,5 +4,5 @@ CMAKE_COMMAND The full path to the :manual:`cmake(1)` executable. This is the full path to the CMake executable :manual:`cmake(1)` which is -useful from custom commands that want to use the ``cmake -E`` option for +useful from custom commands that want to use the :option:`cmake -E` option for portable system commands. (e.g. ``/usr/local/bin/cmake``) diff --git a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst index f77e939..58818f4 100644 --- a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst +++ b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst @@ -13,6 +13,6 @@ This switch should be used during the initial CMake run. Otherwise if the package has already been found in a previous CMake run, the variables which have been stored in the cache will still be there. In that case it is recommended to remove the cache variables for this -package from the cache using the cache editor or :manual:`cmake(1)` ``-U`` +package from the cache using the cache editor or :option:`cmake -U`. See also the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_` variable. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst index 5d45fb0..b27a3d9 100644 --- a/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst +++ b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst @@ -25,4 +25,4 @@ CMake configures the project. ``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` is only set in CMake project mode. It is not set when CMake is run in script mode -(i.e. :manual:`cmake -P ... `). +(i.e. :option:`cmake -P`). diff --git a/Modules/CTest.cmake b/Modules/CTest.cmake index 8f8ebb4..16283d6 100644 --- a/Modules/CTest.cmake +++ b/Modules/CTest.cmake @@ -33,7 +33,7 @@ file at the top of the project with content such as:: (the CDash server can provide the file to a project administrator who configures ``MyProject``). Settings in the config file are shared by both this ``CTest`` module and the :manual:`ctest(1)` command-line -:ref:`Dashboard Client` mode (``ctest -S``). +:ref:`Dashboard Client` mode (:option:`ctest -S`). While building a project for submission to CDash, CTest scans the build output for errors and warnings and reports them with surrounding -- cgit v0.12