diff options
Diffstat (limited to 'Help/manual/cmake.1.rst')
| -rw-r--r-- | Help/manual/cmake.1.rst | 441 |
1 files changed, 441 insertions, 0 deletions
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst new file mode 100644 index 0000000..1147ab8 --- /dev/null +++ b/Help/manual/cmake.1.rst @@ -0,0 +1,441 @@ +cmake(1) +******** + +:: + + cmake - Cross-Platform Makefile Generator. + +:: + + cmake [options] <path-to-source> + cmake [options] <path-to-existing-build> + +The "cmake" executable is the CMake command-line interface. It may be +used to configure projects in scripts. Project configuration settings +may be specified on the command line with the -D option. The -i +option will cause cmake to interactively prompt for such settings. + +CMake is a cross-platform build system generator. Projects specify +their build process with platform-independent CMake listfiles included +in each directory of a source tree with the name CMakeLists.txt. +Users build a project by using CMake to generate a build system for a +native tool on their platform. + + +* ``-C <initial-cache>``: Pre-load a script to populate the cache. + + When cmake is first run in an empty build tree, it creates a + CMakeCache.txt file and populates it with customizable settings for + the project. This option may be used to specify a file from which + to load cache entries before the first pass through the project's + cmake listfiles. The loaded entries take priority over the + project's default values. The given file should be a CMake script + containing SET commands that use the CACHE option, not a + cache-format file. + +* ``-D <var>:<type>=<value>``: Create a cmake cache entry. + + When cmake is first run in an empty build tree, it creates a + CMakeCache.txt file and populates it with customizable settings for + the project. This option may be used to specify a setting that + takes priority over the project's default value. The option may be + repeated for as many cache entries as desired. + +* ``-U <globbing_expr>``: Remove matching entries from CMake cache. + + This option may be used to remove one or more variables from the + CMakeCache.txt file, globbing expressions using * and ? are + supported. The option may be repeated for as many cache entries as + desired. + + Use with care, you can make your CMakeCache.txt non-working. + +* ``-G <generator-name>``: Specify a build system generator. + + CMake may support multiple native build systems on certain + platforms. A generator is responsible for generating a particular + build system. Possible generator names are specified in the + Generators section. + +* ``-T <toolset-name>``: Specify toolset name if supported by generator. + + Some CMake generators support a toolset name to be given to the + native build system to choose a compiler. This is supported only on + specific generators: + + :: + + Visual Studio >= 10 + Xcode >= 3.0 + + See native build system documentation for allowed toolset names. + +* ``-Wno-dev``: Suppress developer warnings. + + Suppress warnings that are meant for the author of the + CMakeLists.txt files. + +* ``-Wdev``: Enable developer warnings. + + Enable warnings that are meant for the author of the CMakeLists.txt + files. + +* ``-E``: CMake command mode. + + For true platform independence, CMake provides a list of commands + that can be used on all systems. Run with -E help for the usage + information. Commands available are: chdir, compare_files, copy, + copy_directory, copy_if_different, echo, echo_append, environment, + make_directory, md5sum, remove, remove_directory, rename, tar, time, + touch, touch_nocreate. In addition, some platform specific commands + are available. On Windows: comspec, delete_regv, write_regv. On + UNIX: create_symlink. + +* ``-i``: Run in wizard mode. + + Wizard mode runs cmake interactively without a GUI. The user is + prompted to answer questions about the project configuration. The + answers are used to set cmake cache values. + +* ``-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 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. + +* ``--build <dir>``: Build a CMake-generated project binary tree. + + This abstracts a native build tool's command-line interface with the + following options: + + :: + + <dir> = Project binary directory to be built. + --target <tgt> = Build <tgt> instead of default targets. + --config <cfg> = For multi-configuration tools, choose <cfg>. + --clean-first = Build target 'clean' first, then build. + (To clean only, use --target 'clean'.) + --use-stderr = Don't merge stdout/stderr output and pass the + original stdout/stderr handles to the native + tool so it can use the capabilities of the + calling terminal (e.g. colored output). + -- = Pass remaining options to the native tool. + + Run cmake --build with no options for quick help. + +* ``-N``: View mode only. + + Only load the cache. Do not actually run configure and generate + steps. + +* ``-P <file>``: Process script mode. + + 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. + +* ``--find-package``: Run in pkg-config like mode. + + Search a package using find_package() and print the resulting flags + to stdout. This can be used to use cmake instead of pkg-config to + find installed libraries in plain Makefile-based projects or in + autoconf-based projects (via share/aclocal/cmake.m4). + +* ``--graphviz=[file]``: Generate graphviz of dependencies, see CMakeGraphVizOptions.cmake for more. + + Generate a graphviz input file that will contain all the library and + executable dependencies in the project. See the documentation for + CMakeGraphVizOptions.cmake 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. + +* ``--debug-trycompile``: Do not delete the try_compile build tree. Only useful on one try_compile at a time. + + Do not delete the files and directories created for 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 stuff during the cmake run like stack traces with + message(send_error ) calls. + +* ``--trace``: Put cmake in trace mode. + + Print a trace of all calls made and from where with + message(send_error ) calls. + +* ``--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 CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR. This flag tells CMake to + warn about other files as well. + +* ``--help-command cmd [file]``: Print help for a single command and exit. + + Full documentation specific to the given command is displayed. If a + file is specified, the documentation is written into and the output + format is determined depending on the filename suffix. Supported + are man page, HTML, DocBook and plain text. + +* ``--help-command-list [file]``: List available listfile commands and exit. + + The list contains all commands for which help may be obtained by + using the --help-command argument followed by a command name. If a + file is specified, the documentation is written into and the output + format is determined depending on the filename suffix. Supported + are man page, HTML, DocBook and plain text. + +* ``--help-commands [file]``: Print help for all commands and exit. + + Full documentation specific for all current commands is displayed.If + a file is specified, the documentation is written into and the + output format is determined depending on the filename suffix. + Supported are man page, HTML, DocBook and plain text. + +* ``--help-compatcommands [file]``: Print help for compatibility commands. + + Full documentation specific for all compatibility commands is + displayed.If a file is specified, the documentation is written into + and the output format is determined depending on the filename + suffix. Supported are man page, HTML, DocBook and plain text. + +* ``--help-module module [file]``: Print help for a single module and exit. + + Full documentation specific to the given module is displayed.If a + file is specified, the documentation is written into and the output + format is determined depending on the filename suffix. Supported + are man page, HTML, DocBook and plain text. + +* ``--help-module-list [file]``: List available modules and exit. + + The list contains all modules for which help may be obtained by + using the --help-module argument followed by a module name. If a + file is specified, the documentation is written into and the output + format is determined depending on the filename suffix. Supported + are man page, HTML, DocBook and plain text. + +* ``--help-modules [file]``: Print help for all modules and exit. + + Full documentation for all modules is displayed. If a file is + specified, the documentation is written into and the output format + is determined depending on the filename suffix. Supported are man + page, HTML, DocBook and plain text. + +* ``--help-custom-modules [file]``: Print help for all custom modules and exit. + + Full documentation for all custom modules is displayed. If a file + is specified, the documentation is written into and the output + format is determined depending on the filename suffix. Supported + are man page, HTML, DocBook and plain text. + +* ``--help-policy cmp [file]``: Print help for a single policy and exit. + + Full documentation specific to the given policy is displayed.If a + file is specified, the documentation is written into and the output + format is determined depending on the filename suffix. Supported + are man page, HTML, DocBook and plain text. + +* ``--help-policy-list [file]``: List available policies and exit. + + The list contains all policies for which help may be obtained by + using the --help-policy argument followed by a policy name. If a + file is specified, the documentation is written into and the output + format is determined depending on the filename suffix. Supported + are man page, HTML, DocBook and plain text. + +* ``--help-policies [file]``: Print help for all policies and exit. + + Full documentation for all policies is displayed.If a file is + specified, the documentation is written into and the output format + is determined depending on the filename suffix. Supported are man + page, HTML, DocBook and plain text. + +* ``--help-property prop [file]``: Print help for a single property and exit. + + Full documentation specific to the given property is displayed.If a + file is specified, the documentation is written into and the output + format is determined depending on the filename suffix. Supported + are man page, HTML, DocBook and plain text. + +* ``--help-property-list [file]``: List available properties and exit. + + The list contains all properties for which help may be obtained by + using the --help-property argument followed by a property name. If + a file is specified, the help is written into it.If a file is + specified, the documentation is written into and the output format + is determined depending on the filename suffix. Supported are man + page, HTML, DocBook and plain text. + +* ``--help-properties [file]``: Print help for all properties and exit. + + Full documentation for all properties is displayed.If a file is + specified, the documentation is written into and the output format + is determined depending on the filename suffix. Supported are man + page, HTML, DocBook and plain text. + +* ``--help-variable var [file]``: Print help for a single variable and exit. + + Full documentation specific to the given variable is displayed.If a + file is specified, the documentation is written into and the output + format is determined depending on the filename suffix. Supported + are man page, HTML, DocBook and plain text. + +* ``--help-variable-list [file]``: List documented variables and exit. + + The list contains all variables for which help may be obtained by + using the --help-variable argument followed by a variable name. If + a file is specified, the help is written into it.If a file is + specified, the documentation is written into and the output format + is determined depending on the filename suffix. Supported are man + page, HTML, DocBook and plain text. + +* ``--help-variables [file]``: Print help for all variables and exit. + + Full documentation for all variables is displayed.If a file is + specified, the documentation is written into and the output format + is determined depending on the filename suffix. Supported are man + page, HTML, DocBook and plain text. + +* ``--copyright [file]``: Print the CMake copyright and exit. + + If a file is specified, the copyright is written into it. + +* ``--help,-help,-usage,-h,-H,/?``: Print usage information and exit. + + Usage describes the basic command line interface and its options. + +* ``--help-full [file]``: Print full help and exit. + + Full help displays most of the documentation provided by the UNIX + man page. It is provided for use on non-UNIX platforms, but is also + convenient if the man page is not installed. If a file is + specified, the help is written into it. + +* ``--help-html [file]``: Print full help in HTML format. + + This option is used by CMake authors to help produce web pages. If + a file is specified, the help is written into it. + +* ``--help-man [file]``: Print full help as a UNIX man page and exit. + + This option is used by the cmake build to generate the UNIX man + page. If a file is specified, the help is written into it. + +* ``--version,-version,/V [file]``: Show program name/version banner and exit. + + If a file is specified, the version is written into it. +The following generators are available on this platform: + +:: + + CMake Properties - Properties supported by CMake, the Cross-Platform Makefile Generator. + +This is the documentation for the properties supported by CMake. +Properties can have different scopes. They can either be assigned to +a source file, a directory, a target or globally to CMake. By +modifying the values of properties the behaviour of the build system +can be customized. + +:: + + CMake Compatibility Listfile Commands - Obsolete commands supported by CMake for compatibility. + +This is the documentation for now obsolete listfile commands from +previous CMake versions, which are still supported for compatibility +reasons. You should instead use the newer, faster and shinier new +commands. ;-) + +The following modules are provided with CMake. They can be used with +INCLUDE(ModuleName). + +:: + + CMake Modules - Modules coming with CMake, the Cross-Platform Makefile Generator. + +This is the documentation for the modules and scripts coming with +CMake. Using these modules you can check the computer system for +installed software packages, features of the compiler and the +existence of headers to name just a few. + +variables defined by cmake, that give information about the project, +and cmake + +Copyright 2000-2012 Kitware, Inc., Insight Software Consortium. All +rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +Redistributions of source code must retain the above copyright notice, +this list of conditions and the following disclaimer. + +Redistributions in binary form must reproduce the above copyright +notice, this list of conditions and the following disclaimer in the +documentation and/or other materials provided with the distribution. + +Neither the names of Kitware, Inc., the Insight Software Consortium, +nor the names of their contributors may be used to endorse or promote +products derived from this software without specific prior written +permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +The following resources are available to get help using CMake: + + +* ``Home Page``: http://www.cmake.org + + The primary starting point for learning about CMake. + +* ``Frequently Asked Questions``: http://www.cmake.org/Wiki/CMake_FAQ + + A Wiki is provided containing answers to frequently asked questions. + +* ``Online Documentation``: http://www.cmake.org/HTML/Documentation.html + + Links to available documentation may be found on this web page. + +* ``Mailing List``: http://www.cmake.org/HTML/MailingLists.html + + For help and discussion about using cmake, a mailing list is + provided at cmake@cmake.org. The list is member-post-only but one + may sign up on the CMake web page. Please first read the full + documentation at http://www.cmake.org before posting questions to + the list. |