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, 0 insertions, 781 deletions
diff --git a/share/cmake-3.17/Help/manual/cmake.1.rst b/share/cmake-3.17/Help/manual/cmake.1.rst deleted file mode 100644 index 28a081f..0000000 --- a/share/cmake-3.17/Help/manual/cmake.1.rst +++ /dev/null @@ -1,781 +0,0 @@ -.. 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 |