diff options
Diffstat (limited to 'share/cmake-3.17/Help/manual/cmake.1.rst')
| -rw-r--r-- | share/cmake-3.17/Help/manual/cmake.1.rst | 781 |
1 files changed, 781 insertions, 0 deletions
diff --git a/share/cmake-3.17/Help/manual/cmake.1.rst b/share/cmake-3.17/Help/manual/cmake.1.rst new file mode 100644 index 0000000..28a081f --- /dev/null +++ b/share/cmake-3.17/Help/manual/cmake.1.rst @@ -0,0 +1,781 @@ +.. cmake-manual-description: CMake Command-Line Reference + +cmake(1) +******** + +Synopsis +======== + +.. parsed-literal:: + + `Generate a Project Buildsystem`_ + cmake [<options>] <path-to-source> + cmake [<options>] <path-to-existing-build> + cmake [<options>] -S <path-to-source> -B <path-to-build> + + `Build a Project`_ + cmake --build <dir> [<options>] [-- <build-tool-options>] + + `Install a Project`_ + cmake --install <dir> [<options>] + + `Open a Project`_ + cmake --open <dir> + + `Run a Script`_ + cmake [{-D <var>=<value>}...] -P <cmake-script-file> + + `Run a Command-Line Tool`_ + cmake -E <command> [<options>] + + `Run the Find-Package Tool`_ + cmake --find-package [<options>] + + `View Help`_ + cmake --help[-<topic>] + +Description +=========== + +The **cmake** executable is the command-line interface of the cross-platform +buildsystem generator CMake. The above `Synopsis`_ lists various actions +the tool can perform as described in sections below. + +To build a software project with CMake, `Generate a Project Buildsystem`_. +Optionally use **cmake** to `Build a Project`_, `Install a Project`_ or just +run the corresponding build tool (e.g. ``make``) directly. **cmake** can also +be used to `View Help`_. + +The other actions are meant for use by software developers writing +scripts in the :manual:`CMake language <cmake-language(7)>` to support +their builds. + +For graphical user interfaces that may be used in place of **cmake**, +see :manual:`ccmake <ccmake(1)>` and :manual:`cmake-gui <cmake-gui(1)>`. +For command-line interfaces to the CMake testing and packaging facilities, +see :manual:`ctest <ctest(1)>` and :manual:`cpack <cpack(1)>`. + +For more information on CMake at large, `see also`_ the links at the end +of this manual. + + +Introduction to CMake Buildsystems +================================== + +A *buildsystem* describes how to build a project's executables and libraries +from its source code using a *build tool* to automate the process. For +example, a buildsystem may be a ``Makefile`` for use with a command-line +``make`` tool or a project file for an Integrated Development Environment +(IDE). In order to avoid maintaining multiple such buildsystems, a project +may specify its buildsystem abstractly using files written in the +:manual:`CMake language <cmake-language(7)>`. From these files CMake +generates a preferred buildsystem locally for each user through a backend +called a *generator*. + +To generate a buildsystem with CMake, the following must be selected: + +Source Tree + The top-level directory containing source files provided by the project. + The project specifies its buildsystem using files as described in the + :manual:`cmake-language(7)` manual, starting with a top-level file named + ``CMakeLists.txt``. These files specify build targets and their + dependencies as described in the :manual:`cmake-buildsystem(7)` manual. + +Build Tree + The top-level directory in which buildsystem files and build output + artifacts (e.g. executables and libraries) are to be stored. + CMake will write a ``CMakeCache.txt`` file to identify the directory + as a build tree and store persistent information such as buildsystem + configuration options. + + To maintain a pristine source tree, perform an *out-of-source* build + by using a separate dedicated build tree. An *in-source* build in + which the build tree is placed in the same directory as the source + tree is also supported, but discouraged. + +Generator + This chooses the kind of buildsystem to generate. See the + :manual:`cmake-generators(7)` manual for documentation of all generators. + Run ``cmake --help`` to see a list of generators available locally. + Optionally use the ``-G`` option below to specify a generator, or simply + accept the default CMake chooses for the current platform. + + When using one of the :ref:`Command-Line Build Tool Generators` + CMake expects that the environment needed by the compiler toolchain + is already configured in the shell. When using one of the + :ref:`IDE Build Tool Generators`, no particular environment is needed. + + +Generate a Project Buildsystem +============================== + +Run CMake with one of the following command signatures to specify the +source and build trees and generate a buildsystem: + +``cmake [<options>] <path-to-source>`` + Uses the current working directory as the build tree, and + ``<path-to-source>`` as the source tree. The specified path may + be absolute or relative to the current working directory. + The source tree must contain a ``CMakeLists.txt`` file and must + *not* contain a ``CMakeCache.txt`` file because the latter + identifies an existing build tree. For example: + + .. code-block:: console + + $ mkdir build ; cd build + $ cmake ../src + +``cmake [<options>] <path-to-existing-build>`` + Uses ``<path-to-existing-build>`` as the build tree, and loads the + path to the source tree from its ``CMakeCache.txt`` file, which must + have already been generated by a previous run of CMake. The specified + path may be absolute or relative to the current working directory. + For example: + + .. code-block:: console + + $ cd build + $ cmake . + +``cmake [<options>] -S <path-to-source> -B <path-to-build>`` + 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. + +After generating a buildsystem one may use the corresponding native +build tool to build the project. For example, after using the +:generator:`Unix Makefiles` generator one may run ``make`` directly: + + .. code-block:: console + + $ make + $ make install + +Alternatively, one may use **cmake** to `Build a Project`_ by +automatically choosing and invoking the appropriate native build tool. + +.. _`CMake Options`: + +Options +------- + +.. include:: OPTIONS_BUILD.txt + +``-L[A][H]`` + List non-advanced cached variables. + + List ``CACHE`` variables will run CMake and list all the variables from + the CMake ``CACHE`` that are not marked as ``INTERNAL`` or :prop_cache:`ADVANCED`. + This will effectively display current CMake settings, which can then be + changed with ``-D`` option. Changing some of the variables may result + in more variables being created. If ``A`` is specified, then it will + display also advanced variables. If ``H`` is specified, it will also + display help for each variable. + +``-N`` + View mode only. + + Only load the cache. Do not actually run configure and generate + steps. + +``--graphviz=[file]`` + Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more. + + Generate a graphviz input file that will contain all the library and + executable dependencies in the project. See the documentation for + :module:`CMakeGraphVizOptions` for more details. + +``--system-information [file]`` + Dump information about this system. + + Dump a wide range of information about the current system. If run + from the top of a binary tree for a CMake project it will dump + additional information such as the cache, log files etc. + +``--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>`` + Set the log level. + + The :command:`message` command will only output messages of the specified + log level or higher. The default log level is ``STATUS``. + + To make a log level persist between CMake runs, set + :variable:`CMAKE_MESSAGE_LOG_LEVEL` as a cache variable instead. + If both the command line option and the variable are given, the command line + option takes precedence. + + For backward compatibility reasons, ``--loglevel`` is also accepted as a + synonym for this option. + +``--log-context`` + Enable the :command:`message` command outputting context attached to each + message. + + This option turns on showing context for the current CMake run only. + To make showing the context persistent for all subsequent CMake runs, set + :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` as a cache variable instead. + When this command line option is given, :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` + is ignored. + +``--debug-trycompile`` + Do not delete the :command:`try_compile` build tree. + Only useful on one :command:`try_compile` at a time. + + Do not delete the files and directories created for :command:`try_compile` + calls. This is useful in debugging failed try_compiles. It may + however change the results of the try-compiles as old junk from a + previous try-compile may cause a different test to either pass or + fail incorrectly. This option is best used for one try-compile at a + time, and only when debugging. + +``--debug-output`` + Put cmake in a debug mode. + + Print extra information during the cmake run like stack traces with + :command:`message(SEND_ERROR)` calls. + +``--debug-find`` + Put cmake find in a debug mode. + + Print extra find call information during the cmake run to standard + error. Output is designed for human consumption and not for parsing. + +``--trace`` + Put cmake in trace mode. + + Print a trace of all calls made and from where. + +``--trace-expand`` + Put cmake in trace mode. + + Like ``--trace``, but with variables expanded. + +``--trace-format=<format>`` + Put cmake in trace mode and sets the trace output format. + + ``<format>`` can be one of the following values. + + ``human`` + Prints each trace line in a human-readable format. This is the + default format. + + ``json-v1`` + Prints each line as a separate JSON document. Each document is + separated by a newline ( ``\n`` ). It is guaranteed that no + newline characters will be present inside a JSON document. + + JSON trace format: + + .. code-block:: json + + { + "file": "/full/path/to/the/CMake/file.txt", + "line": 0, + "cmd": "add_executable", + "args": ["foo", "bar"], + "time": 1579512535.9687231, + "frame": 2 + } + + The members are: + + ``file`` + The full path to the CMake source file where the function + was called. + + ``line`` + The line in ``file`` of the function call. + + ``cmd`` + The name of the function that was called. + + ``args`` + A string list of all function parameters. + + ``time`` + Timestamp (seconds since epoch) of the function call. + + ``frame`` + Stack frame depth of the function that was called. + + Additionally, the first JSON document outputted contains the + ``version`` key for the current major and minor version of the + + JSON trace format: + + .. code-block:: json + + { + "version": { + "major": 1, + "minor": 0 + } + } + + The members are: + + ``version`` + Indicates the version of the JSON format. The version has a + major and minor components following semantic version conventions. + +``--trace-source=<file>`` + Put cmake in trace mode, but output only lines of a specified file. + + Multiple options are allowed. + +``--trace-redirect=<file>`` + Put cmake in trace mode and redirect trace output to a file instead of stderr. + +``--warn-uninitialized`` + Warn about uninitialized values. + + Print a warning when an uninitialized variable is used. + +``--warn-unused-vars`` + Warn about unused variables. + + Find variables that are declared or set, but not used. + +``--no-warn-unused-cli`` + Don't warn about command line options. + + Don't find variables that are declared on the command line, but not + used. + +``--check-system-vars`` + Find problems with variable usage in system files. + + Normally, unused and uninitialized variables are searched for only + in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`. + This flag tells CMake to warn about other files as well. + +.. _`Build Tool Mode`: + +Build a Project +=============== + +CMake provides a command-line signature to build an already-generated +project binary tree: + +.. code-block:: shell + + cmake --build <dir> [<options>] [-- <build-tool-options>] + +This abstracts a native build tool's command-line interface with the +following options: + +``--build <dir>`` + Project binary directory to be built. This is required and must be first. + +``--parallel [<jobs>], -j [<jobs>]`` + The maximum number of concurrent processes to use when building. + If ``<jobs>`` is omitted the native build tool's default number is used. + + The :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment variable, if set, + specifies a default parallel level when this option is not given. + + Some native build tools always build in parallel. The use of ``<jobs>`` + value of ``1`` can be used to limit to a single job. + +``--target <tgt>..., -t <tgt>...`` + Build ``<tgt>`` instead of the default target. Multiple targets may be + given, separated by spaces. + +``--config <cfg>`` + For multi-configuration tools, choose configuration ``<cfg>``. + +``--clean-first`` + Build target ``clean`` first, then build. + (To clean only, use ``--target clean``.) + +``--use-stderr`` + Ignored. Behavior is default in CMake >= 3.0. + +``--verbose, -v`` + Enable verbose output - if supported - including the build commands to be + executed. + + This option can be omitted if :envvar:`VERBOSE` environment variable or + :variable:`CMAKE_VERBOSE_MAKEFILE` cached variable is set. + + +``--`` + Pass remaining options to the native tool. + +Run ``cmake --build`` with no options for quick help. + +Install a Project +================= + +CMake provides a command-line signature to install an already-generated +project binary tree: + +.. code-block:: shell + + cmake --install <dir> [<options>] + +This may be used after building a project to run installation without +using the generated build system or the native build tool. +The options are: + +``--install <dir>`` + Project binary directory to install. This is required and must be first. + +``--config <cfg>`` + For multi-configuration generators, choose configuration ``<cfg>``. + +``--component <comp>`` + Component-based install. Only install component ``<comp>``. + +``--prefix <prefix>`` + Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`. + +``--strip`` + Strip before installing. + +``-v, --verbose`` + Enable verbose output. + + This option can be omitted if :envvar:`VERBOSE` environment variable is set. + +Run ``cmake --install`` with no options for quick help. + +Open a Project +============== + +.. code-block:: shell + + cmake --open <dir> + +Open the generated project in the associated application. This is only +supported by some generators. + + +.. _`Script Processing Mode`: + +Run a Script +============ + +.. code-block:: shell + + cmake [{-D <var>=<value>}...] -P <cmake-script-file> + +Process the given cmake file as a script written in the CMake +language. No configure or generate step is performed and the cache +is not modified. If variables are defined using ``-D``, this must be +done before the ``-P`` argument. + + +Run a Command-Line Tool +======================= + +CMake provides builtin command-line tools through the signature + +.. code-block:: shell + + cmake -E <command> [<options>] + +Run ``cmake -E`` or ``cmake -E help`` for a summary of commands. +Available commands are: + +``capabilities`` + Report cmake capabilities in JSON format. The output is a JSON object + with the following keys: + + ``version`` + A JSON object with version information. Keys are: + + ``string`` + The full version string as displayed by cmake ``--version``. + ``major`` + The major version number in integer form. + ``minor`` + The minor version number in integer form. + ``patch`` + The patch level in integer form. + ``suffix`` + The cmake version suffix string. + ``isDirty`` + A bool that is set if the cmake build is from a dirty tree. + + ``generators`` + A list available generators. Each generator is a JSON object with the + following keys: + + ``name`` + A string containing the name of the generator. + ``toolsetSupport`` + ``true`` if the generator supports toolsets and ``false`` otherwise. + ``platformSupport`` + ``true`` if the generator supports platforms and ``false`` otherwise. + ``extraGenerators`` + A list of strings with all the extra generators compatible with + the generator. + + ``fileApi`` + Optional member that is present when the :manual:`cmake-file-api(7)` + is available. The value is a JSON object with one member: + + ``requests`` + A JSON array containing zero or more supported file-api requests. + Each request is a JSON object with members: + + ``kind`` + Specifies one of the supported :ref:`file-api object kinds`. + + ``version`` + A JSON array whose elements are each a JSON object containing + ``major`` and ``minor`` members specifying non-negative integer + version components. + + ``serverMode`` + ``true`` if cmake supports server-mode and ``false`` otherwise. + +``chdir <dir> <cmd> [<arg>...]`` + Change the current working directory and run a command. + +``compare_files [--ignore-eol] <file1> <file2>`` + Check if ``<file1>`` is same as ``<file2>``. If files are the same, + then returns ``0``, if not it returns ``1``. The ``--ignore-eol`` option + implies line-wise comparison and ignores LF/CRLF differences. + +``copy <file>... <destination>`` + Copy files to ``<destination>`` (either file or directory). + If multiple files are specified, the ``<destination>`` must be + directory and it must exist. Wildcards are not supported. + ``copy`` does follow symlinks. That means it does not copy symlinks, + but the files or directories it point to. + +``copy_directory <dir>... <destination>`` + Copy content of ``<dir>...`` directories to ``<destination>`` directory. + If ``<destination>`` directory does not exist it will be created. + ``copy_directory`` does follow symlinks. + +``copy_if_different <file>... <destination>`` + Copy files to ``<destination>`` (either file or directory) if + they have changed. + If multiple files are specified, the ``<destination>`` must be + directory and it must exist. + ``copy_if_different`` does follow symlinks. + +``create_symlink <old> <new>`` + Create a symbolic link ``<new>`` naming ``<old>``. + + .. note:: + Path to where ``<new>`` symbolic link will be created has to exist beforehand. + +``echo [<string>...]`` + Displays arguments as text. + +``echo_append [<string>...]`` + Displays arguments as text but no new line. + +``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...`` + Run command in a modified environment. + +``environment`` + Display the current environment variables. + +``false`` + Do nothing, with an exit code of 1. + +``make_directory <dir>...`` + Create ``<dir>`` directories. If necessary, create parent + directories too. If a directory already exists it will be + silently ignored. + +``md5sum <file>...`` + Create MD5 checksum of files in ``md5sum`` compatible format:: + + 351abe79cd3800b38cdfb25d45015a15 file1.txt + 052f86c15bbde68af55c7f7b340ab639 file2.txt + +``sha1sum <file>...`` + Create SHA1 checksum of files in ``sha1sum`` compatible format:: + + 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt + 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt + +``sha224sum <file>...`` + Create SHA224 checksum of files in ``sha224sum`` compatible format:: + + b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt + 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt + +``sha256sum <file>...`` + Create SHA256 checksum of files in ``sha256sum`` compatible format:: + + 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt + 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt + +``sha384sum <file>...`` + Create SHA384 checksum of files in ``sha384sum`` compatible format:: + + acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt + 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt + +``sha512sum <file>...`` + Create SHA512 checksum of files in ``sha512sum`` compatible format:: + + 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt + 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt + +``remove [-f] <file>...`` + .. deprecated:: 3.17 + + Remove the file(s). The planned behaviour was that if any of the + listed files already do not exist, the command returns a non-zero exit code, + but no message is logged. The ``-f`` option changes the behavior to return a + zero exit code (i.e. success) in such situations instead. + ``remove`` does not follow symlinks. That means it remove only symlinks + and not files it point to. + + The implementation was buggy and always returned 0. It cannot be fixed without + breaking backwards compatibility. Use ``rm`` instead. + +``remove_directory <dir>...`` + .. deprecated:: 3.17 + + Remove ``<dir>`` directories and their contents. If a directory does + not exist it will be silently ignored. If ``<dir>`` is a symlink to + a directory, just the symlink will be removed. + Use ``rm`` instead. + +``rename <oldname> <newname>`` + Rename a file or directory (on one volume). If file with the ``<newname>`` name + already exists, then it will be silently replaced. + +``rm [-rRf] <file> <dir>...`` + Remove the files ``<file>`` or directories ``dir``. + Use ``-r`` or ``-R`` to remove directories and their contents recursively. + If any of the listed files/directories do not exist, the command returns a + non-zero exit code, but no message is logged. The ``-f`` option changes + the behavior to return a zero exit code (i.e. success) in such + situations instead. + +``server`` + Launch :manual:`cmake-server(7)` mode. + +``sleep <number>...`` + Sleep for given number of seconds. + +``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]`` + Create or extract a tar or zip archive. Options are: + + ``c`` + Create a new archive containing the specified files. + If used, the ``<pathname>...`` argument is mandatory. + ``x`` + Extract to disk from the archive. + The ``<pathname>...`` argument could be used to extract only selected files + or directories. + When extracting selected files or directories, you must provide their exact + names including the path, as printed by list (``-t``). + ``t`` + List archive contents. + The ``<pathname>...`` argument could be used to list only selected files + or directories. + ``v`` + Produce verbose output. + ``z`` + Compress the resulting archive with gzip. + ``j`` + Compress the resulting archive with bzip2. + ``J`` + Compress the resulting archive with XZ. + ``--zstd`` + Compress the resulting archive with Zstandard. + ``--files-from=<file>`` + Read file names from the given file, one per line. + Blank lines are ignored. Lines may not start in ``-`` + except for ``--add-file=<name>`` to add files whose + names start in ``-``. + ``--format=<format>`` + Specify the format of the archive to be created. + Supported formats are: ``7zip``, ``gnutar``, ``pax``, + ``paxr`` (restricted pax, default), and ``zip``. + ``--mtime=<date>`` + Specify modification time recorded in tarball entries. + ``--`` + Stop interpreting options and treat all remaining arguments + as file names, even if they start with ``-``. + + +``time <command> [<args>...]`` + Run command and display elapsed time. + +``touch <file>...`` + Creates ``<file>`` if file do not exist. + If ``<file>`` exists, it is changing ``<file>`` access and modification times. + +``touch_nocreate <file>...`` + Touch a file if it exists but do not create it. If a file does + not exist it will be silently ignored. + +``true`` + Do nothing, with an exit code of 0. + +Windows-specific Command-Line Tools +----------------------------------- + +The following ``cmake -E`` commands are available only on Windows: + +``delete_regv <key>`` + Delete Windows registry value. + +``env_vs8_wince <sdkname>`` + Displays a batch file which sets the environment for the provided + Windows CE SDK installed in VS2005. + +``env_vs9_wince <sdkname>`` + Displays a batch file which sets the environment for the provided + Windows CE SDK installed in VS2008. + +``write_regv <key> <value>`` + Write Windows registry value. + + +Run the Find-Package Tool +========================= + +CMake provides a pkg-config like helper for Makefile-based projects: + +.. code-block:: shell + + cmake --find-package [<options>] + +It searches a package using :command:`find_package()` and prints the +resulting flags to stdout. This can be used instead of pkg-config +to find installed libraries in plain Makefile-based projects or in +autoconf-based projects (via ``share/aclocal/cmake.m4``). + +.. note:: + This mode is not well-supported due to some technical limitations. + It is kept for compatibility but should not be used in new projects. + + +View Help +========= + +To print selected pages from the CMake documentation, use + +.. code-block:: shell + + cmake --help[-<topic>] + +with one of the following options: + +.. include:: OPTIONS_HELP.txt + + +See Also +======== + +.. include:: LINKS.txt |