From d4faed2f7ffa1267b52e0cce9c0c32d8f88b6abc Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 10 May 2016 09:35:48 -0400 Subject: [PATCH 1/2] Help: Document `cmake --find-package` as a separate command mode --- Help/manual/cmake.1.rst | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 3ae2bafc5..12b401244 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -82,12 +82,7 @@ Options 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). + See `Find-Package Tool Mode`_. ``--graphviz=[file]`` Generate graphviz of dependencies, see CMakeGraphVizOptions.cmake for more. @@ -278,6 +273,24 @@ The following ``cmake -E`` commands are available only on Windows: ``write_regv `` Write Windows registry value. +Find-Package Tool Mode +====================== + +CMake provides a helper for Makefile-based projects with the signature:: + + cmake --find-package ... + +This runs in a pkg-config like mode. + +Search a package using :command:`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``). + +.. 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. + See Also ======== From 3e503fe1acc7f341a160db30cd2d2db4ab0e8b8e Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 10 May 2016 09:42:37 -0400 Subject: [PATCH 2/2] Help: Document `cmake --build` as a separate command mode (#16093) The `--build` mode was confusingly documented among other options, falsely implying that it can be used anywhere on the command line. Move the documentation to a dedicated section and clarify its usage as s separate command line mode. --- Help/manual/cmake.1.rst | 52 +++++++++++++++++++++++++++-------------- 1 file changed, 34 insertions(+), 18 deletions(-) diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 12b401244..65153af41 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -10,7 +10,7 @@ Synopsis cmake [] ( | ) cmake [(-D =)...] -P - cmake --build [] [-- ...] + cmake --build [...] [-- ...] cmake -E [...] cmake --find-package ... @@ -49,23 +49,7 @@ Options display help for each variable. ``--build `` - Build a CMake-generated project binary tree. - - This abstracts a native build tool's command-line interface with the - following options: - - :: - - = Project binary directory to be built. - --target = Build instead of default targets. - May only be specified once. - --config = For multi-configuration tools, choose . - --clean-first = Build target 'clean' first, then build. - (To clean only, use --target 'clean'.) - --use-stderr = Ignored. Behavior is default in CMake >= 3.0. - -- = Pass remaining options to the native tool. - - Run ``cmake --build`` with no options for quick help. + See `Build Tool Mode`_. ``-N`` View mode only. @@ -149,6 +133,38 @@ Options .. include:: OPTIONS_HELP.txt +Build Tool Mode +=============== + +CMake provides a command-line signature to build an already-generated +project binary tree:: + + cmake --build [...] [-- ...] + +This abstracts a native build tool's command-line interface with the +following options: + +``--build `` + Project binary directory to be built. This is required and must be first. + +``--target `` + Build ```` instead of default targets. May only be specified once. + +``--config `` + For multi-configuration tools, choose configuration ````. + +``--clean-first`` + Build target ``clean`` first, then build. + (To clean only, use ``--target clean``.) + +``--use-stderr`` + Ignored. Behavior is default in CMake >= 3.0. + +``--`` + Pass remaining options to the native tool. + +Run ``cmake --build`` with no options for quick help. + Command-Line Tool Mode ======================