diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/target_link_libraries.rst | 16 | ||||
| -rw-r--r-- | Help/generator/Ninja.rst | 2 | ||||
| -rw-r--r-- | Help/generator/Visual Studio 6.rst | 8 | ||||
| -rw-r--r-- | Help/generator/Visual Studio 7.rst | 8 | ||||
| -rw-r--r-- | Help/manual/cmake-developer.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 4 | ||||
| -rw-r--r-- | Help/manual/ctest.1.rst | 4 | ||||
| -rw-r--r-- | Help/policy/CMP0060.rst | 63 | ||||
| -rw-r--r-- | Help/prop_tgt/PDB_NAME.rst | 3 | ||||
| -rw-r--r-- | Help/release/dev/FPHSA-ExactCase-name.rst | 10 | ||||
| -rw-r--r-- | Help/release/dev/link-implicit-libs-full-path.rst | 6 | ||||
| -rw-r--r-- | Help/release/dev/tar-write-format.rst | 6 | ||||
| -rw-r--r-- | Help/release/dev/vs10-no-macros.rst | 9 | ||||
| -rw-r--r-- | Help/release/dev/vs6-deprecate.rst | 5 | ||||
| -rw-r--r-- | Help/release/dev/vs70-deprecate.rst | 5 | ||||
| -rw-r--r-- | Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst | 2 |
17 files changed, 142 insertions, 11 deletions
diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 393c8b4..d903d05 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -34,14 +34,20 @@ Each ``<item>`` may be: automatically be added in the build system to make sure the named library target is up-to-date before the ``<target>`` links. + If an imported library has the :prop_tgt:`IMPORTED_NO_SONAME` + target property set, CMake may ask the linker to search for + the library instead of using the full path + (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``). + * **A full path to a library file**: The generated link line will - normally preserve the full path to the file. However, there are - some cases where CMake must ask the linker to search for the library - (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``), such as when it - appears in a system library directory that the compiler front-end - may replace with an alternative. Either way, the buildsystem will + normally preserve the full path to the file. The buildsystem will have a dependency to re-link ``<target>`` if the library file changes. + There are some cases where CMake may ask the linker to search for + the library (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``), such + as when a shared library is detected to have no ``SONAME`` field. + See policy :policy:`CMP0060` for discussion of another case. + If the library file is in a Mac OSX framework, the ``Headers`` directory of the framework will also be processed as a :ref:`usage requirement <Target Usage Requirements>`. This has the same diff --git a/Help/generator/Ninja.rst b/Help/generator/Ninja.rst index 08f74fb..920abcb 100644 --- a/Help/generator/Ninja.rst +++ b/Help/generator/Ninja.rst @@ -1,7 +1,7 @@ Ninja ----- -Generates build.ninja files (experimental). +Generates build.ninja files. A build.ninja file is generated into the build tree. Recent versions of the ninja program can build the project through the "all" target. diff --git a/Help/generator/Visual Studio 6.rst b/Help/generator/Visual Studio 6.rst index d619354..855589c 100644 --- a/Help/generator/Visual Studio 6.rst +++ b/Help/generator/Visual Studio 6.rst @@ -1,4 +1,10 @@ Visual Studio 6 --------------- -Generates Visual Studio 6 project files. +Deprected. Generates Visual Studio 6 project files. + +.. note:: + This generator is deprecated and will be removed + in a future version of CMake. It will still be + possible to build with VS 6 tools using the + :generator:`NMake Makefiles` generator. diff --git a/Help/generator/Visual Studio 7.rst b/Help/generator/Visual Studio 7.rst index d0eb719..eb426f4 100644 --- a/Help/generator/Visual Studio 7.rst +++ b/Help/generator/Visual Studio 7.rst @@ -1,4 +1,10 @@ Visual Studio 7 --------------- -Generates Visual Studio .NET 2002 project files. +Deprected. Generates Visual Studio .NET 2002 project files. + +.. note:: + This generator is deprecated and will be removed + in a future version of CMake. It will still be + possible to build with VS 7.0 tools using the + :generator:`NMake Makefiles` generator. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 7bffa42..ab74140 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -605,6 +605,7 @@ have a .cmake file in this directory NOT show up in the modules documentation, simply leave out the ``Help/module/<module-name>.rst`` file and the ``Help/manual/cmake-modules.7.rst`` toctree entry. +.. _`Find Modules`: Find Modules ------------ diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index d2960de..aff696d 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -117,3 +117,4 @@ All Policies /policy/CMP0057 /policy/CMP0058 /policy/CMP0059 + /policy/CMP0060 diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index da41bbb..b2f7e9d 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -215,6 +215,10 @@ Available commands are: names start in ``-``. ``--mtime=<date>`` Specify modification time recorded in tarball entries. + ``--format=<format>`` + Specify the format of the archive to be created. + Supported formats are: ``7zip``, ``gnutar``, ``pax``, + ``paxr`` (restricted pax, default), and ``zip``. ``time <command> [<args>...]`` Run command and return elapsed time. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index dd3bcfb..584786f 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -573,7 +573,7 @@ Configuration settings to specify the version control tool include: * :module:`CTest` module variable: ``GITCOMMAND`` ``GITUpdateCustom`` - Specify a semicolon-separated list of custom command lines to run + Specify a custom command line (as a semicolon-separated list) to run in the source tree (Git work tree) to update it instead of running the ``GITCommand``. @@ -617,7 +617,7 @@ Configuration settings to specify the version control tool include: * :module:`CTest` module variable: ``CTEST_P4_OPTIONS`` ``P4UpdateCustom`` - Specify a semicolon-separated list of custom command lines to run + Specify a custom command line (as a semicolon-separated list) to run in the source tree (Perforce tree) to update it instead of running the ``P4Command``. diff --git a/Help/policy/CMP0060.rst b/Help/policy/CMP0060.rst new file mode 100644 index 0000000..cc37b1b --- /dev/null +++ b/Help/policy/CMP0060.rst @@ -0,0 +1,63 @@ +CMP0060 +------- + +Link libraries by full path even in implicit directories. + +Policy :policy:`CMP0003` was introduced with the intention of always +linking library files by full path when a full path is given to the +:command:`target_link_libraries` command. However, on some platforms +(e.g. HP-UX) the compiler front-end adds alternative library search paths +for the current architecture (e.g. ``/usr/lib/<arch>`` has alternatives +to libraries in ``/usr/lib`` for the current architecture). +On such platforms the :command:`find_library` may find a library such as +``/usr/lib/libfoo.so`` that does not belong to the current architecture. + +Prior to policy :policy:`CMP0003` projects would still build in such +cases because the incorrect library path would be converted to ``-lfoo`` +on the link line and the linker would find the proper library in the +arch-specific search path provided by the compiler front-end implicitly. +At the time we chose to remain compatible with such projects by always +converting library files found in implicit link directories to ``-lfoo`` +flags to ask the linker to search for them. This approach allowed existing +projects to continue to build while still linking to libraries outside +implicit link directories via full path (such as those in the build tree). + +CMake does allow projects to override this behavior by using an +:ref:`IMPORTED library target <Imported Targets>` with its +:prop_tgt:`IMPORTED_LOCATION` property set to the desired full path to +a library file. In fact, many :ref:`Find Modules` are learning to provide +:ref:`Imported Targets` instead of just the traditional ``Foo_LIBRARIES`` +variable listing library files. However, this makes the link line +generated for a library found by a Find Module depend on whether it +is linked through an imported target or not, which is inconsistent. +Furthermore, this behavior has been a source of confusion because the +generated link line for a library file depends on its location. It is +also problematic for projects trying to link statically because flags +like ``-Wl,-Bstatic -lfoo -Wl,-Bdynamic`` may be used to help the linker +select ``libfoo.a`` instead of ``libfoo.so`` but then leak dynamic linking +to following libraries. (See the :prop_tgt:`LINK_SEARCH_END_STATIC` +target property for a solution typically used for that problem.) + +When the special case for libraries in implicit link directories was first +introduced the list of implicit link directories was simply hard-coded +(e.g. ``/lib``, ``/usr/lib``, and a few others). Since that time, CMake +has learned to detect the implicit link directories used by the compiler +front-end. If necessary, the :command:`find_library` command could be +taught to use this information to help find libraries of the proper +architecture. + +For these reasons, CMake 3.3 and above prefer to drop the special case +and link libraries by full path even when they are in implicit link +directories. Policy ``CMP0060`` provides compatibility for existing +projects. + +The OLD behavior for this policy is to ask the linker to search for +libraries whose full paths are known to be in implicit link directories. +The NEW behavior for this policy is to link libraries by full path even +if they are in implicit link directories. + +This policy was introduced in CMake version 3.3. Unlike most policies, +CMake version |release| does *not* warn by default when this policy +is not set and simply uses OLD behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0060 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. diff --git a/Help/prop_tgt/PDB_NAME.rst b/Help/prop_tgt/PDB_NAME.rst index 479dec3..3a65796 100644 --- a/Help/prop_tgt/PDB_NAME.rst +++ b/Help/prop_tgt/PDB_NAME.rst @@ -5,7 +5,8 @@ Output name for the MS debug symbol ``.pdb`` file generated by the linker for an executable or shared library target. This property specifies the base name for the debug symbols file. -If not set, the logical target name is used by default. +If not set, the :prop_tgt:`OUTPUT_NAME` target property value or +logical target name is used by default. .. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_NAME` .. include:: PDB_NOTE.txt diff --git a/Help/release/dev/FPHSA-ExactCase-name.rst b/Help/release/dev/FPHSA-ExactCase-name.rst new file mode 100644 index 0000000..675547c --- /dev/null +++ b/Help/release/dev/FPHSA-ExactCase-name.rst @@ -0,0 +1,10 @@ +FPHSA-ExactCase-name +-------------------- + +* The :module:`FindPackageHandleStandardArgs` module + ``FIND_PACKAGE_HANDLE_STANDARD_ARGS`` function now + always populates the both ``<PackageName>_FOUND`` + and ``<UPPERCASE_NAME>_FOUND`` variables (the latter + for backwards compatibility). The ``FOUND_VAR`` + option is now ignored except to enforce its allowed + values. diff --git a/Help/release/dev/link-implicit-libs-full-path.rst b/Help/release/dev/link-implicit-libs-full-path.rst new file mode 100644 index 0000000..7ed7245 --- /dev/null +++ b/Help/release/dev/link-implicit-libs-full-path.rst @@ -0,0 +1,6 @@ +link-implicit-libs-full-path +---------------------------- + +* Linking to library files by a full path in an implicit linker search + directory (e.g. ``/usr/lib/libfoo.a``) no longer asks the linker to + search for the library (e.g. ``-lfoo``). See policy :policy:`CMP0060`. diff --git a/Help/release/dev/tar-write-format.rst b/Help/release/dev/tar-write-format.rst new file mode 100644 index 0000000..004df21 --- /dev/null +++ b/Help/release/dev/tar-write-format.rst @@ -0,0 +1,6 @@ +tar-write-format +---------------- + +* The :manual:`cmake(1)` ``-E tar`` command learned a new + ``--format<format>`` option to specify the archive format to + be written. diff --git a/Help/release/dev/vs10-no-macros.rst b/Help/release/dev/vs10-no-macros.rst new file mode 100644 index 0000000..89377dc --- /dev/null +++ b/Help/release/dev/vs10-no-macros.rst @@ -0,0 +1,9 @@ +vs10-no-macros +-------------- + +* The :generator:`Visual Studio 10 2010` generator no longer checks + for running VS IDEs with the project open or asks them to reload. + This was originally done for VS 10 because it had been done for + VS 7 through 9 to avoid prompting for every project in a solution. + Since VS >= 10 allow the whole solution to reload at once they + do not need CMake to help them. diff --git a/Help/release/dev/vs6-deprecate.rst b/Help/release/dev/vs6-deprecate.rst new file mode 100644 index 0000000..83f9afb --- /dev/null +++ b/Help/release/dev/vs6-deprecate.rst @@ -0,0 +1,5 @@ +vs6-deprecate +------------- + +* The :generator:`Visual Studio 6` generator is now deprecated + and will be removed in a future version of CMake. diff --git a/Help/release/dev/vs70-deprecate.rst b/Help/release/dev/vs70-deprecate.rst new file mode 100644 index 0000000..fb94110 --- /dev/null +++ b/Help/release/dev/vs70-deprecate.rst @@ -0,0 +1,5 @@ +vs70-deprecate +-------------- + +* The :generator:`Visual Studio 7` generator (.NET 2002) is now + deprecated and will be removed in a future version of CMake. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index a83c807..092fe3e 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -11,6 +11,8 @@ warn by default: policy :policy:`CMP0047`. * ``CMAKE_POLICY_WARNING_CMP0056`` controls the warning for policy :policy:`CMP0056`. +* ``CMAKE_POLICY_WARNING_CMP0060`` controls the warning for + policy :policy:`CMP0060`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to |