Help: Rename 3.x.0 release notes to 3.x

In commit v3.0.0-rc1~9 (Help: Rename 3.0 release notes to 3.0.0,
2014-02-19) we anticipated the possibility of bugfix-only release notes.
However, in practice we have no release notes for bug fix releases
because we do not cover bug fixes in release notes at all, only new
features.  Instead we've been updating the feature-level release notes
document in bug fix releases, treating errors in the document as bugs.

It makes more sense to maintain release notes at the feature-release
level, so rename the documents accordingly.  Also update the document
titles and intro text to refer only to feature versions and not bugfix
versions.

1 files changed, 425 insertions, 0 deletions

diff --git a/Help/release/3.1.rst b/Help/release/3.1.rst
new file mode 100644
index 0000000..dca42cd
--- /dev/null
+++ b/Help/release/3.1.rst
@@ -0,0 +1,425 @@
+CMake 3.1 Release Notes
+***********************
+
+.. only:: html
+
+  .. contents::
+
+Changes made since CMake 3.0 include the following.
+
+Documentation Changes
+=====================
+
+* A new :manual:`cmake-compile-features(7)` manual was added.
+
+New Features
+============
+
+Generators
+----------
+
+* The :generator:`Visual Studio 14 2015` generator was added.
+
+Windows Phone and Windows Store
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Generators for Visual Studio 11 (2012) and above learned to generate
+  projects for Windows Phone and Windows Store.  One may set the
+  :variable:`CMAKE_SYSTEM_NAME` variable to ``WindowsPhone``
+  or ``WindowsStore`` on the :manual:`cmake(1)` command-line
+  or in a :variable:`CMAKE_TOOLCHAIN_FILE` to activate these platforms.
+  Also set :variable:`CMAKE_SYSTEM_VERSION` to ``8.0`` or ``8.1`` to
+  specify the version of Windows to be targeted.
+
+NVIDIA Nsight Tegra
+^^^^^^^^^^^^^^^^^^^
+
+* Generators for Visual Studio 10 (2010) and above learned to generate
+  projects for NVIDIA Nsight Tegra Visual Studio Edition.  One may set
+  the :variable:`CMAKE_SYSTEM_NAME` variable to ``Android`` on the
+  :manual:`cmake(1)` command-line or in a :variable:`CMAKE_TOOLCHAIN_FILE`
+  to activate this platform.
+
+Syntax
+------
+
+* The :manual:`cmake-language(7)` syntax for :ref:`Variable References` and
+  :ref:`Escape Sequences` was simplified in order to allow a much faster
+  implementation.  See policy :policy:`CMP0053`.
+
+* The :command:`if` command no longer automatically dereferences
+  variables named in quoted or bracket arguments.  See policy
+  :policy:`CMP0054`.
+
+Commands
+--------
+
+* The :command:`add_custom_command` command learned to interpret
+  :manual:`cmake-generator-expressions(7)` in arguments to ``DEPENDS``.
+
+* The :command:`export(PACKAGE)` command learned to check the
+  :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable to skip
+  exporting the package.
+
+* The :command:`file(STRINGS)` command gained a new ``ENCODING``
+  option to enable extraction of ``UTF-8`` strings.
+
+* The :command:`find_package` command learned to check the
+  :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` and
+  :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`
+  variables to skip searching the package registries.
+
+* The :command:`get_property` command learned a new ``INSTALL`` scope
+  for properties.
+
+* The :command:`install` command learned a ``MESSAGE_NEVER`` option
+  to avoid output during installation.
+
+* The :command:`set_property` command learned a new ``INSTALL`` scope
+  for properties.
+
+* The :command:`string` command learned a new ``GENEX_STRIP`` subcommand
+  which removes
+  :manual:`generator expression <cmake-generator-expressions(7)>`.
+
+* The :command:`string` command learned a new ``UUID`` subcommand
+  to generate a univerally unique identifier.
+
+* New :command:`target_compile_features` command allows populating the
+  :prop_tgt:`COMPILE_FEATURES` target property, just like any other
+  build variable.
+
+* The :command:`target_sources` command was added to add to the
+  :prop_tgt:`SOURCES` target property.
+
+Variables
+---------
+
+* The Visual Studio generators for versions 8 (2005) and above
+  learned to read the target platform name from a new
+  :variable:`CMAKE_GENERATOR_PLATFORM` variable when it is
+  not specified as part of the generator name.  The platform
+  name may be specified on the :manual:`cmake(1)` command line
+  with the ``-A`` option, e.g. ``-G "Visual Studio 12 2013" -A x64``.
+
+* The :variable:`CMAKE_GENERATOR_TOOLSET` variable may now be
+  initialized in a toolchain file specified by the
+  :variable:`CMAKE_TOOLCHAIN_FILE` variable.  This is useful
+  when cross-compiling with the Xcode or Visual Studio
+  generators.
+
+* The :variable:`CMAKE_INSTALL_MESSAGE` variable was introduced to
+  optionally reduce output installation.
+
+Properties
+----------
+
+* New :prop_tgt:`CXX_STANDARD` and :prop_tgt:`CXX_EXTENSIONS` target
+  properties may specify values which CMake uses to compute required
+  compile options such as ``-std=c++11`` or ``-std=gnu++11``. The
+  :variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_EXTENSIONS`
+  variables may be set to initialize the target properties.
+
+* New :prop_tgt:`C_STANDARD` and :prop_tgt:`C_EXTENSIONS` target
+  properties may specify values which CMake uses to compute required
+  compile options such as ``-std=c11`` or ``-std=gnu11``. The
+  :variable:`CMAKE_C_STANDARD` and :variable:`CMAKE_C_EXTENSIONS`
+  variables may be set to initialize the target properties.
+
+* New :prop_tgt:`COMPILE_FEATURES` target property may contain a list
+  of features required to compile a target.  CMake uses this
+  information to ensure that the compiler in use is capable of building
+  the target, and to add any necessary compile flags to support language
+  features.
+
+* New :prop_tgt:`COMPILE_PDB_NAME` and
+  :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY` target properties
+  were introduced to specify the MSVC compiler program database
+  file location (``cl /Fd``).  This complements the existing
+  :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY`
+  target properties that specify the linker program database
+  file location (``link /pdb``).
+
+* The :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property now supports
+  a ``$<LINK_ONLY:...>``
+  :manual:`generator expression <cmake-generator-expressions(7)>`.
+
+* A new :prop_tgt:`INTERFACE_SOURCES` target property was introduced. This is
+  consumed by dependent targets, which compile and link the listed sources.
+
+* The :prop_tgt:`SOURCES` target property now contains
+  :manual:`generator expression <cmake-generator-expressions(7)>`
+  such as ``TARGET_OBJECTS`` when read at configure time, if
+  policy :policy:`CMP0051` is ``NEW``.
+
+* The :prop_tgt:`SOURCES` target property now generally supports
+  :manual:`generator expression <cmake-generator-expressions(7)>`.  The
+  generator expressions may be used in the :command:`add_library` and
+  :command:`add_executable` commands.
+
+* It is now possible to write and append to the :prop_tgt:`SOURCES` target
+  property.  The :variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable may be
+  used to trace the origin of sources.
+
+* A :prop_sf:`VS_DEPLOYMENT_CONTENT` source file property was added
+  to tell the Visual Studio generators to mark content for deployment
+  in Windows Phone and Windows Store projects.
+
+* A :prop_sf:`VS_DEPLOYMENT_LOCATION` source file property was added
+  to tell the Visual Studio generators the relative location of content
+  marked for deployment in Windows Phone and Windows Store projects.
+
+* The :prop_tgt:`VS_WINRT_COMPONENT` target property was created to
+  tell Visual Studio generators to compile a shared library as a
+  Windows Runtime (WinRT) component.
+
+* The :generator:`Xcode` generator learned to check source
+  file properties  :prop_sf:`XCODE_EXPLICIT_FILE_TYPE` and
+  :prop_sf:`XCODE_LAST_KNOWN_FILE_TYPE` for a custom Xcode
+  file reference type.
+
+Modules
+-------
+
+* The :module:`BundleUtilities` module learned to resolve and replace
+  ``@rpath`` placeholders on OS X to correctly bundle applications
+  using them.
+
+* The :module:`CMakePackageConfigHelpers` module
+  :command:`configure_package_config_file` command learned a new
+  ``INSTALL_PREFIX`` option to generate package configuration files
+  meant for a prefix other than :variable:`CMAKE_INSTALL_PREFIX`.
+
+* The :module:`CheckFortranSourceCompiles` module was added to
+  provide a ``CHECK_Fortran_SOURCE_COMPILES`` macro.
+
+* The :module:`ExternalData` module learned to tolerate a ``DATA{}``
+  reference to a missing source file with a warning instead of
+  rejecting it with an error.  This helps developers write new
+  ``DATA{}`` references to test reference outputs that have not
+  yet been created.
+
+* The :module:`ExternalProject` module learned to support lzma-compressed
+  source tarballs with ``.7z``, ``.tar.xz``, and ``.txz`` extensions.
+
+* The :module:`ExternalProject` module ``ExternalProject_Add`` command
+  learned a new ``BUILD_ALWAYS`` option to cause the external project
+  build step to run every time the host project is built.
+
+* The :module:`ExternalProject` module ``ExternalProject_Add`` command
+  learned a new ``EXCLUDE_FROM_ALL`` option to cause the external
+  project target to have the :prop_tgt:`EXCLUDE_FROM_ALL` target
+  property set.
+
+* The :module:`ExternalProject` module ``ExternalProject_Add_Step`` command
+  learned a new ``EXCLUDE_FROM_MAIN`` option to cause the step to not be
+  a direct dependency of the main external project target.
+
+* The :module:`ExternalProject` module ``ExternalProject_Add`` command
+  learned a new ``DOWNLOAD_NO_PROGRESS`` option to disable progress
+  output while downloading the source tarball.
+
+* The :module:`FeatureSummary` module ``feature_summary`` API
+  learned to accept multiple values for the ``WHAT`` option and
+  combine them appropriately.
+
+* The :module:`FindCUDA` module learned to support ``fatbin`` and ``cubin``
+  modules.
+
+* The :module:`FindGTest` module ``gtest_add_tests`` macro learned
+  a new ``AUTO`` option to automatically read the :prop_tgt:`SOURCES`
+  target property of the test executable and scan the source files
+  for tests to be added.
+
+* The :module:`FindGLEW` module now provides imported targets.
+
+* The :module:`FindGLUT` module now provides imported targets.
+
+* The :module:`FindHg` module gained a new ``Hg_WC_INFO`` macro to
+  help run ``hg`` to extract information about a Mercurial work copy.
+
+* The :module:`FindOpenCL` module was introduced.
+
+* The :module:`FindOpenMP` module learned to support Fortran.
+
+* The :module:`FindPkgConfig` module learned to use the ``PKG_CONFIG``
+  environment variable value as the ``pkg-config`` executable, if set.
+
+* The :module:`FindXercesC` module was introduced.
+
+* The :module:`FindZLIB` module now provides imported targets.
+
+* The :module:`GenerateExportHeader` module ``generate_export_header``
+  function learned to allow use with :ref:`Object Libraries`.
+
+* The :module:`InstallRequiredSystemLibraries` module gained a new
+  ``CMAKE_INSTALL_OPENMP_LIBRARIES`` option to install MSVC OpenMP
+  runtime libraries.
+
+* The :module:`UseSWIG` module learned to detect the module name
+  from ``.i`` source files if possible to avoid the need to set
+  the ``SWIG_MODULE_NAME`` source file property explicitly.
+
+* The :module:`WriteCompilerDetectionHeader` module was added to allow
+  creation of a portable header file for compiler optional feature detection.
+
+Generator Expressions
+---------------------
+
+* New ``COMPILE_FEATURES``
+  :manual:`generator expression <cmake-generator-expressions(7)>` allows
+  setting build properties based on available compiler features.
+
+CTest
+-----
+
+* The :command:`ctest_coverage` command learned to read variable
+  ``CTEST_COVERAGE_EXTRA_FLAGS`` to set ``CoverageExtraFlags``.
+
+* The :command:`ctest_coverage` command learned to support
+  Intel coverage files with the ``codecov`` tool.
+
+* The :command:`ctest_memcheck` command learned to support sanitizer
+  modes, including ``AddressSanitizer``, ``MemorySanitizer``,
+  ``ThreadSanitizer``, and ``UndefinedBehaviorSanitizer``.
+  Options may be set using the new
+  :variable:`CTEST_MEMORYCHECK_SANITIZER_OPTIONS` variable.
+
+CPack
+-----
+
+* :manual:`cpack(1)` gained an ``IFW`` generator to package using
+  Qt Framework Installer tools.  See the :module:`CPackIFW` module.
+
+* :manual:`cpack(1)` gained ``7Z`` and ``TXZ`` generators supporting
+  lzma-compressed archives.
+
+* The :module:`CPackDeb` module learned a new
+  :variable:`CPACK_DEBIAN_COMPRESSION_TYPE` variable to set the
+  tarball compression type.
+
+* The :manual:`cpack(1)` ``WiX`` generator learned to support
+  a :prop_inst:`CPACK_WIX_ACL` installed file property to
+  specify an Access Control List.
+
+Other
+-----
+
+* The :manual:`cmake(1)` ``-E`` option learned a new ``env`` command.
+
+* The :manual:`cmake(1)` ``-E tar`` command learned to support
+  lzma-compressed files.
+
+* :ref:`Object Libraries` may now have extra sources that do not
+  compile to object files so long as they would not affect linking
+  of a normal library (e.g. ``.dat`` is okay but not ``.def``).
+
+* Visual Studio generators for VS 8 and later learned to support
+  the ``ASM_MASM`` language.
+
+* The Visual Studio generators learned to treat ``.hlsl`` source
+  files as High Level Shading Language sources (using ``FXCompile``
+  in ``.vcxproj`` files).  Source file properties
+  :prop_sf:`VS_SHADER_TYPE`, :prop_sf:`VS_SHADER_MODEL`, and
+  :prop_sf:`VS_SHADER_ENTRYPOINT` were added added to specify the
+  shader type, model, and entry point name.
+
+New Diagnostics
+===============
+
+* Policy :policy:`CMP0052` introduced to control directories in the
+  :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of exported targets.
+
+Deprecated and Removed Features
+===============================
+
+* In CMake 3.0 the :command:`target_link_libraries` command
+  accidentally began allowing unquoted arguments to use
+  :manual:`generator expressions <cmake-generator-expressions(7)>`
+  containing a (``;`` separated) list within them.  For example::
+
+    set(libs B C)
+    target_link_libraries(A PUBLIC $<BUILD_INTERFACE:${libs}>)
+
+  This is equivalent to writing::
+
+    target_link_libraries(A PUBLIC $<BUILD_INTERFACE:B C>)
+
+  and was never intended to work.  It did not work in CMake 2.8.12.
+  Such generator expressions should be in quoted arguments::
+
+    set(libs B C)
+    target_link_libraries(A PUBLIC "$<BUILD_INTERFACE:${libs}>")
+
+  CMake 3.1 again requires the quotes for this to work correctly.
+
+* Prior to CMake 3.1 the Makefile generators did not escape ``#``
+  correctly inside make variable assignments used in generated
+  makefiles, causing them to be treated as comments.  This made
+  code like::
+
+    add_compile_options(-Wno-#pragma-messages)
+
+  not work in Makefile generators, but work in other generators.
+  Now it is escaped correctly, making the behavior consistent
+  across generators.  However, some projects may have tried to
+  workaround the original bug with code like::
+
+    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-\\#pragma-messages")
+
+  This added the needed escape for Makefile generators but also
+  caused other generators to pass ``-Wno-\#pragma-messages`` to
+  the shell, which would work only in POSIX shells.
+  Unfortunately the escaping fix could not be made in a compatible
+  way so this platform- and generator-specific workaround no
+  longer works.  Project code may test the :variable:`CMAKE_VERSION`
+  variable value to make the workaround version-specific too.
+
+* Callbacks established by the :command:`variable_watch` command will no
+  longer receive the ``ALLOWED_UNKNOWN_READ_ACCESS`` access type when
+  the undocumented ``CMAKE_ALLOW_UNKNOWN_VARIABLE_READ_ACCESS`` variable is
+  set.  Uninitialized variable accesses will always be reported as
+  ``UNKNOWN_READ_ACCESS``.
+
+* The :module:`CMakeDetermineVSServicePack` module now warns that
+  it is deprecated and should not longer be used.  Use the
+  :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable instead.
+
+* The :module:`FindITK` module has been removed altogether.
+  It was a thin-wrapper around ``find_package(ITK ... NO_MODULE)``.
+  This produces much clearer error messages when ITK is not found.
+
+* The :module:`FindVTK` module has been removed altogether.
+  It was a thin-wrapper around ``find_package(VTK ... NO_MODULE)``.
+  This produces much clearer error messages when VTK is not found.
+
+  The module also provided compatibility support for finding VTK 4.0.
+  This capability has been dropped.
+
+Other Changes
+=============
+
+* The :manual:`cmake-gui(1)` learned to capture output from child
+  processes started by the :command:`execute_process` command
+  and display it in the output window.
+
+* The :manual:`cmake-language(7)` internal implementation of generator
+  expression and list expansion parsers have been optimized and shows
+  non-trivial speedup on large projects.
+
+* The Makefile generators learned to use response files with GNU tools
+  on Windows to pass library directories and names to the linker.
+
+* When generating linker command-lines, CMake now avoids repeating
+  items corresponding to SHARED library targets.
+
+* Support for the Open Watcom compiler has been overhauled.
+  The :variable:`CMAKE_<LANG>_COMPILER_ID` is now ``OpenWatcom``,
+  and the :variable:`CMAKE_<LANG>_COMPILER_VERSION` now uses
+  the Open Watcom external version numbering.  The external
+  version numbers are lower than the internal version number
+  by 11.
+
+* The ``cmake-mode.el`` major Emacs editing mode no longer
+  treats ``_`` as part of words, making it more consistent
+  with other major modes.