From 8fa9858e206c02c697ec65eab8c12f0925df8afc Mon Sep 17 00:00:00 2001 From: Nikita Nemkin Date: Sun, 9 Feb 2025 23:14:09 +0500 Subject: Help: Improve VS_SETTINGS and VS_TOOL_OVERRIDE documentation Reorder paragraphs, adjust version notes, add cross-references, note the ability to exclude files from the build. Fixes: #11902 --- Help/prop_sf/VS_SETTINGS.rst | 32 +++++++++++++++++++++----------- Help/prop_sf/VS_TOOL_OVERRIDE.rst | 12 ++++++++++-- 2 files changed, 31 insertions(+), 13 deletions(-) diff --git a/Help/prop_sf/VS_SETTINGS.rst b/Help/prop_sf/VS_SETTINGS.rst index 871e36e..da85f12 100644 --- a/Help/prop_sf/VS_SETTINGS.rst +++ b/Help/prop_sf/VS_SETTINGS.rst @@ -3,15 +3,11 @@ VS_SETTINGS .. versionadded:: 3.18 -Set any item metadata on a file. +Add arbitrary MSBuild item metadata to a file. -.. versionadded:: 3.22 - - This property is honored for all source file types. - Previously it worked only for non-built files. - -Takes a list of ``Key=Value`` pairs. Tells the Visual Studio generator to set -``Key`` to ``Value`` as item metadata on the file. +This property accepts a list of ``Key=Value`` pairs. The Visual Studio +generator will add these key-value pairs as item metadata to the file. +:manual:`Generator expressions ` are supported. For example: @@ -19,7 +15,21 @@ For example: set_property(SOURCE file.hlsl PROPERTY VS_SETTINGS "Key=Value" "Key2=Value2") -will set ``Key`` to ``Value`` and ``Key2`` to ``Value2`` on the -``file.hlsl`` item as metadata. +will set the ``file.hlsl`` item metadata as follows: -:manual:`Generator expressions ` are supported. +.. code-block:: xml + + + Value + Value2 + + +Together with :prop_sf:`VS_TOOL_OVERRIDE`, this property can be used to +configure items for custom MSBuild tasks. + +Adding the metadata ``ExcludedFromBuild=true`` will exclude the file from +the build. + +.. versionchanged:: 3.22 + This property is honored for all source file types. + Previously, it only worked for source types unknown to CMake. diff --git a/Help/prop_sf/VS_TOOL_OVERRIDE.rst b/Help/prop_sf/VS_TOOL_OVERRIDE.rst index b2f4112..57172b6 100644 --- a/Help/prop_sf/VS_TOOL_OVERRIDE.rst +++ b/Help/prop_sf/VS_TOOL_OVERRIDE.rst @@ -3,5 +3,13 @@ VS_TOOL_OVERRIDE .. versionadded:: 3.7 -Override the default Visual Studio tool that will be applied to the source file -with a new tool not based on the extension of the file. +Override the MSBuild item type of a source file in a Visual Studio project. + +Together with :prop_sf:`VS_SETTINGS`, this property can be used to configure +items for custom MSBuild tasks. + +Setting the item type to ``None`` will exclude the file from the build. + +.. versionchanged:: 3.31 + This property is honored for all source file types. + Previously, it only worked for source types unknown to CMake. -- cgit v0.12 From 9955a3bb735c482845b8ec4170bb8f3bfe032d66 Mon Sep 17 00:00:00 2001 From: Nikita Nemkin Date: Sun, 16 Feb 2025 14:13:29 +0500 Subject: Help: Clarify EXCLUDE_FROM_DEFAULT_BUILD behavior Note that solution build configurations ignore dependencies, unlike the ALL_BUILD target. Fixes: #12379 --- Help/prop_tgt/EXCLUDE_FROM_ALL.rst | 9 +++++++++ Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst | 18 ++++++++++++++---- 2 files changed, 23 insertions(+), 4 deletions(-) diff --git a/Help/prop_tgt/EXCLUDE_FROM_ALL.rst b/Help/prop_tgt/EXCLUDE_FROM_ALL.rst index f0200f3..240fcd1 100644 --- a/Help/prop_tgt/EXCLUDE_FROM_ALL.rst +++ b/Help/prop_tgt/EXCLUDE_FROM_ALL.rst @@ -26,3 +26,12 @@ the :manual:`cmake-generator-expressions(7)` manual for available expressions. Only the "Ninja Multi-Config" generator supports a property value that varies by configuration. For all other generators the value of this property must be the same for all configurations. + +See Also +^^^^^^^^ + +* To exclude targets from the whole directory subtree, see the + :prop_dir:`EXCLUDE_FROM_ALL` directory property. + +* To exclude targets from the Visual Studio solution build, use + :prop_tgt:`EXCLUDE_FROM_DEFAULT_BUILD`. diff --git a/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst b/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst index 664704b..71b36e8 100644 --- a/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst +++ b/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst @@ -1,8 +1,18 @@ EXCLUDE_FROM_DEFAULT_BUILD -------------------------- -Exclude target from ``Build Solution``. +Exclude a target from the solution build configuration. -This property is only used by Visual Studio generators. -When set to ``TRUE``, the target will not be built when you press -``Build Solution``. +This property is only used by Visual Studio generators. When set to ``TRUE``, +the target will be excluded from the build when the "Build Solution" command +is run. + +This property has a per-configuration version: +:prop_tgt:`EXCLUDE_FROM_DEFAULT_BUILD_`. + +.. note:: + Solution build configurations do not take project dependencies into account. + If a target is excluded, it will not be built, even if another target + included in the configuration depends on it. This behavior differs from the + CMake-generated ``ALL_BUILD`` target and the :prop_tgt:`EXCLUDE_FROM_ALL` + property. -- cgit v0.12