Help/fileAPI: Add version modified directives

Extend (part of) commit f26e9fcbae (Help: Generate presets JSON schema,
documentation, 2026-04-08) to the `cmake-file-api(7)` page, for each of
the currently applicable object kinds (i.e., only those which have
undergone changes, which is predominantly the codemodel).

This standardization helps to improve both the readability and
maintainability of the document.

Help/manual/cmake-file-api.7.rst

@@ -636,14 +636,14 @@ The members specific to ``codemodel`` objects are:
       ``targets`` array.
 
     ``abstractTargetIndexes``
+      .. codemodel-versionadded:: 2.9
+
       Optional member that is present when the directory itself has abstract
       targets, excluding those belonging to subdirectories.
       The value is a JSON array of entries corresponding to the abstract
       targets.  Each entry is an unsigned integer 0-based index into the main
       ``abstractTargets`` array.
 
-      This field was added in codemodel version 2.9.
-
     ``minimumCMakeVersion``
       Optional member present when a minimum required version of CMake is
       known for the directory.  This is the ``<min>`` version given to the
@@ -666,12 +666,12 @@ The members specific to ``codemodel`` objects are:
       or equivalent rule is available.
 
     ``jsonFile``
+      .. codemodel-versionadded:: 2.3
+
       A JSON string specifying a path relative to the codemodel file
       to another JSON file containing a
       `"codemodel" version 2 "directory" object`_.
 
-      This field was added in codemodel version 2.3.
-
   ``projects``
     A JSON array of entries corresponding to the top-level project
     and sub-projects defined in the build system.  Each (sub-)project
@@ -711,14 +711,14 @@ The members specific to ``codemodel`` objects are:
       ``targets`` array.
 
     ``abstractTargetIndexes``
+      .. codemodel-versionadded:: 2.9
+
       Optional member that is present when the project itself has
       abstract targets, excluding those belonging to sub-projects.
       The value is a JSON array of entries corresponding to the abstract
       targets.  Each entry is an unsigned integer 0-based index into the main
       ``abstractTargets`` array.
 
-      This field was added in codemodel version 2.9.
-
   ``targets``
     A JSON array of entries corresponding to the build system targets.
     Such targets are created by calls to :command:`add_executable`,
@@ -747,6 +747,8 @@ The members specific to ``codemodel`` objects are:
       `"codemodel" version 2 "target" object`_.
 
   ``abstractTargets``
+    .. codemodel-versionadded:: 2.9
+
     A JSON array of entries corresponding to targets that are not present
     in the build system.  These are imported targets or interface libraries
     created by calls to :command:`add_executable` or :command:`add_library`.
@@ -777,8 +779,6 @@ The members specific to ``codemodel`` objects are:
       to another JSON file containing a
       `"codemodel" version 2 "target" object`_.
 
-    This field was added in codemodel version 2.9.
-
 "codemodel" version 2 "directory" object
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -791,6 +791,8 @@ object's ``directories`` array.  Each "directory" object is a JSON object
 with members:
 
 ``codemodelVersion``
+  .. codemodel-versionadded:: 2.9
+
   This specifies the codemodel version this file is part of.  It will match
   the ``version`` field of the codemodel object kind that references this file.
   It is a JSON object with the following members:
@@ -801,8 +803,6 @@ with members:
   ``minor``
     The codemodel minor version.
 
-  This field was added in codemodel version 2.9.
-
 ``paths``
   A JSON object containing members:
 
@@ -913,21 +913,21 @@ with members:
       ``runtimeDependencySetName`` and ``runtimeDependencySetType``.
 
     ``fileSet``
+      .. codemodel-versionadded:: 2.4
+
       An :command:`install(TARGETS)` call with ``FILE_SET``.
       The ``destination`` and ``paths`` members are populated.
       The ``isOptional`` member may exist.
       This type has additional members ``fileSetName``, ``fileSetType``,
       ``fileSetDirectories``, and ``fileSetTarget``.
 
-      This type was added in codemodel version 2.4.
-
     ``cxxModuleBmi``
+      .. codemodel-versionadded:: 2.5
+
       An :command:`install(TARGETS)` call with ``CXX_MODULES_BMI``.
       The ``destination`` member is populated and the ``isOptional`` member
       may exist.  This type has an additional ``cxxModuleBmiTarget`` member.
 
-      This type was added in codemodel version 2.5.
-
   ``isExcludeFromAll``
     Optional member that is present with boolean value ``true`` when
     :command:`install` is called with the ``EXCLUDE_FROM_ALL`` option.
@@ -1006,29 +1006,32 @@ with members:
       frameworks.
 
   ``fileSetName``
+    .. codemodel-versionadded:: 2.4
+
     Optional member that is present when ``type`` is ``fileSet``. The value is
     a string with the name of the file set.
 
-    This field was added in codemodel version 2.4.
-
   ``fileSetType``
+    .. codemodel-versionadded:: 2.4
+
     Optional member that is present when ``type`` is ``fileSet``. The value is
     a string with the type of the file set.
 
-    This field was added in codemodel version 2.4.
+    .. codemodel-versionchanged:: 2.11
 
-    Since codemodel version 2.11, this field additionally accounts for
+      This field additionally accounts for ``SOURCES`` file sets.
-    ``SOURCES`` file sets.
 
   ``fileSetDirectories``
+    .. codemodel-versionadded:: 2.4
+
     Optional member that is present when ``type`` is ``fileSet``. The value
     is a list of strings with the file set's base directories (determined by
     genex-evaluation of :prop_tgt:`HEADER_DIRS` or
     :prop_tgt:`HEADER_DIRS_<NAME>`).
 
-    This field was added in codemodel version 2.4.
-
   ``fileSetTarget``
+    .. codemodel-versionadded:: 2.4
+
     Optional member that is present when ``type`` is ``fileSet``. The value
     is a JSON object with members:
 
@@ -1041,9 +1044,9 @@ with members:
       An unsigned integer 0-based index into the main "codemodel"
       object's ``targets`` array for the target.
 
-    This field was added in codemodel version 2.4.
-
   ``cxxModuleBmiTarget``
+    .. codemodel-versionadded:: 2.5
+
     Optional member that is present when ``type`` is ``cxxModuleBmi``.
     The value is a JSON object with members:
 
@@ -1056,8 +1059,6 @@ with members:
       An unsigned integer 0-based index into the main "codemodel"
       object's ``targets`` array for the target.
 
-    This field was added in codemodel version 2.5.
-
   ``scriptFile``
     Optional member that is present when ``type`` is ``script``.
     The value is a string specifying the path to the script file on disk,
@@ -1087,6 +1088,8 @@ object's ``targets`` array.  Each "target" object is a JSON object
 with members:
 
 ``codemodelVersion``
+  .. codemodel-versionadded:: 2.9
+
   This specifies the codemodel version this file is part of.  It will match
   the ``version`` field of the codemodel object kind that references this file.
   It is a JSON object with the following members:
@@ -1097,8 +1100,6 @@ with members:
   ``minor``
     The codemodel minor version.
 
-  This field was added in codemodel version 2.9.
-
 ``name``
   A string specifying the logical name of the target.
 
@@ -1113,19 +1114,21 @@ with members:
   or ``UTILITY``.
 
 ``imported``
+  .. codemodel-versionadded:: 2.9
+
   Optional member that is present with boolean value ``true`` if the
   target is an imported target.
 
-  This field was added in codemodel version 2.9.
-
 ``local``
+  .. codemodel-versionadded:: 2.9
+
   Optional member that is present with boolean value ``true`` if the
   target is only defined with local scope rather than being a global target.
   Currently, only imported targets will potentially have this field.
 
-  This field was added in codemodel version 2.9.
-
 ``abstract``
+  .. codemodel-versionadded:: 2.9
+
   Optional member that is present with boolean value ``true`` if the
   target is an abstract target.  Abstract targets are not part of the build
   system, they only exist to describe dependencies or to provide usage
@@ -1134,17 +1137,17 @@ with members:
   cannot be built, so they should not be presented to the user as a buildable
   target.
 
-  This field was added in codemodel version 2.9.  Abstract targets were not
+  Abstract targets were not included in codemodel version 2.8 and earlier.
-  included in codemodel version 2.8 and earlier.
 
 ``symbolic``
+  .. codemodel-versionadded:: 2.9
+
   Optional member that is present with boolean value ``true`` if the target
   is :prop_tgt:`SYMBOLIC`.  Symbolic targets are created by calls to
   :command:`add_library(INTERFACE SYMBOLIC) <add_library(INTERFACE-SYMBOLIC)>`,
   and are also abstract targets that are not part of the build system.
 
-  This field was added in codemodel version 2.9.  Symbolic targets were not
+  Symbolic targets were not included in codemodel version 2.8 and earlier.
-  included in codemodel version 2.8 and earlier.
 
 ``backtrace``
   Optional member that is present when a CMake language backtrace to
@@ -1223,6 +1226,8 @@ with members:
       index into the ``backtraceGraph`` member's ``nodes`` array.
 
 ``launchers``
+  .. codemodel-versionadded:: 2.7
+
   Optional member that is present on executable targets that have
   at least one launcher specified by the project.  The value is a
   JSON array of entries corresponding to the specified launchers.
@@ -1250,8 +1255,6 @@ with members:
       A start program for the execution of tests.
       See the :prop_tgt:`TEST_LAUNCHER` target property.
 
-  This field was added in codemodel version 2.7.
-
 ``link``
   Optional member that is present for non-imported executables and shared
   library targets that link into a runtime binary.  The value is a JSON object
@@ -1323,21 +1326,19 @@ with members:
     or link-time code generation) is enabled.
 
 ``debugger``
+  .. codemodel-versionadded:: 2.8
+
   Optional member that is present when the target has one of the
   following fields set.
   The value is a JSON object of entries corresponding to
   debugger specific values set.
 
-  This field was added in codemodel version 2.8.
-
   ``workingDirectory``
     Optional member that is present when the
     :prop_tgt:`DEBUGGER_WORKING_DIRECTORY` target property is set.
     The member will also be present in :ref:`Visual Studio Generators`
     when :prop_tgt:`VS_DEBUGGER_WORKING_DIRECTORY` is set.
 
-    This field was added in codemodel version 2.8.
-
 ``dependencies``
   Optional member that is present when the target depends on other targets.
   It is only present if the target is part of the build system.
@@ -1367,6 +1368,8 @@ with members:
     the ``backtraceGraph`` member's ``nodes`` array.
 
 ``linkLibraries``
+  .. codemodel-versionadded:: 2.9
+
   Optional member that may be present when the target links directly to one or
   more other targets or libraries.  It contains items that are used when
   linking this target.  These come from the target's
@@ -1416,9 +1419,9 @@ with members:
       :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` property created the
       relationship.  The value matches the main ``id`` member of that target.
 
-  This field was added in codemodel version 2.9.
-
 ``interfaceLinkLibraries``
+  .. codemodel-versionadded:: 2.9
+
   Optional member that may be present when the target has one or more interface
   link libraries.  It contains items that are used when linking consumers of
   this target.  These come from the target's
@@ -1456,9 +1459,9 @@ with members:
     The value is an unsigned integer 0-based index into the
     ``backtraceGraph`` member's ``nodes`` array.
 
-  This field was added in codemodel version 2.9.
-
 ``compileDependencies``
+  .. codemodel-versionadded:: 2.9
+
   Optional member that may be present when the target links directly to one or
   more other targets that may provide usage requirements to this one.  They
   affect how this target's sources are compiled.  These relationships are
@@ -1498,9 +1501,9 @@ with members:
       :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` property created the
       relationship.  The value matches the main ``id`` member of that target.
 
-  This field was added in codemodel version 2.9.
-
 ``interfaceCompileDependencies``
+  .. codemodel-versionadded:: 2.9
+
   Optional member that may be present when the target has one or more interface
   linking relationships to other targets.  It contains items that affect how
   consumers' sources are compiled.  These relationships are defined by the
@@ -1528,9 +1531,9 @@ with members:
     The value is an unsigned integer 0-based index into the
     ``backtraceGraph`` member's ``nodes`` array.
 
-  This field was added in codemodel version 2.9.
-
 ``objectDependencies``
+  .. codemodel-versionadded:: 2.9
+
   Optional member that is present when the target has one or more entries in
   its :prop_tgt:`SOURCES` property where the entry is specified using
   :genex:`$<TARGET_OBJECTS:...>`, and where no other generator expression is
@@ -1550,9 +1553,9 @@ with members:
     The value is an unsigned integer 0-based index into the
     ``backtraceGraph`` member's ``nodes`` array.
 
-  This field was added in codemodel version 2.9.
-
 ``orderDependencies``
+  .. codemodel-versionadded:: 2.9
+
   Optional member that is present when the target has one or more direct order
   dependencies on other targets.  Such dependencies may arise from calls to
   :command:`add_dependencies` or from internal CMake processing.
@@ -1574,9 +1577,9 @@ with members:
     The value is an unsigned integer 0-based index into the
     ``backtraceGraph`` member's ``nodes`` array.
 
-  This field was added in codemodel version 2.9.
-
 ``fileSets``
+  .. codemodel-versionadded:: 2.5
+
   An optional member that is present when a target defines one or more
   file sets.  The value is a JSON array of entries corresponding to the
   target's file sets.  Each entry is a JSON object with members:
@@ -1598,8 +1601,6 @@ with members:
     directory then the path is specified relative to that directory.
     Otherwise the path is absolute.
 
-  This field was added in codemodel version 2.5.
-
 ``sources``
   A JSON array of entries corresponding to the target's source files.
   Each entry is a JSON object with members:
@@ -1626,6 +1627,8 @@ with members:
     the source is :prop_sf:`GENERATED`.
 
   ``fileSetIndex``
+    .. codemodel-versionadded:: 2.5
+
     .. deprecated:: 4.4
       Use the ``fileSetIndexes`` field instead, which is an array, and
       accounts for sources assigned to multiple file sets.
@@ -1634,15 +1637,13 @@ with members:
     The value is an unsigned integer 0-based index into the ``fileSets``
     array representing the file set to which the source was most recently added.
 
-    This field was added in codemodel version 2.5.
-
   ``fileSetIndexes``
+    .. codemodel-versionadded:: 2.11
+
     Optional member that is present when the source is part of at least one
     file set; see also policy :policy:`CMP0211`. The value is
     an array of unsigned integer 0-based indexes inte the ``fileSets`` array.
 
-    This field was added in codemodel version 2.11.
-
   ``backtrace``
     .. deprecated:: 4.4
       Use the ``backtraces`` field instead, which is an array, and
@@ -1657,6 +1658,7 @@ with members:
     the ``backtraceGraph`` member's ``nodes`` array.
 
   ``backtraces``
+    .. codemodel-versionadded:: 2.11
 
     Optional member that is present when CMake language backtraces to
     the :command:`target_sources`, :command:`add_executable`,
@@ -1669,9 +1671,9 @@ with members:
     unsigned integer 0-based index into the ``backtraceGraph`` member's
     ``nodes`` array.
 
-    This field was added in codemodel version 2.11.
-
 ``interfaceSources``
+  .. codemodel-versionadded:: 2.10
+
   An optional member that is present when a target defines one or more
   interface sources.  The value is a JSON array of entries corresponding
   to the target's interface source files.  Each entry is a JSON object
@@ -1703,14 +1705,12 @@ with members:
     array representing the file set to which the source was most recently added.
 
   ``fileSetIndexes``
+    .. codemodel-versionadded:: 2.11
+
     Optional member that is present when the source is part of at least one
     file set; see also policy :policy:`CMP0211`. The value is
     an array of unsigned integer 0-based indexes inte the ``fileSets`` array.
 
-    This field was added in codemodel version 2.11.
-
-  This field was added in codemodel version 2.10.
-
 ``sourceGroups``
   Optional member that is present when sources are grouped together by
   the :command:`source_group` command or by default.  The value is a
@@ -1726,14 +1726,14 @@ with members:
     main ``sources`` array for the target.
 
   ``interfaceSourceIndexes``
+    .. codemodel-versionadded:: 2.10
+
     Optional member that is present when at least one interface source file
     is part of the source group.  The value is a JSON array listing the
     interface sources belonging to the group.  Each entry is an unsigned
     integer 0-based index into the main ``interfaceSources`` array for the
     target.
 
-    This field was added in codemodel version 2.10.
-
 ``compileGroups``
   Optional member that is present when the target has sources that compile.
   The value is a JSON array of entries corresponding to groups of sources
@@ -1750,6 +1750,8 @@ with members:
     of the toolchain is used to compile the source file.
 
   ``languageStandard``
+    .. codemodel-versionadded:: 2.2
+
     Optional member that is present when the language standard is set
     explicitly (e.g. via :prop_tgt:`CXX_STANDARD`) or implicitly by
     compile features.  Each entry is a JSON object with two members:
@@ -1767,8 +1769,6 @@ with members:
     ``standard``
       String representing the language standard.
 
-    This field was added in codemodel version 2.2.
-
   ``compileCommandFragments``
     Optional member that is present when fragments of the compiler command
     line invocation are available.  The value is a JSON array of entries
@@ -1806,6 +1806,8 @@ with members:
       member's ``nodes`` array.
 
   ``frameworks``
+    .. codemodel-versionadded:: 2.6
+
     Optional member that is present when, on Apple platforms, there are
     frameworks. The value is a JSON array with an entry for each directory.
     Each entry is a JSON object with members:
@@ -1825,9 +1827,9 @@ with members:
       an unsigned integer 0-based index into the ``backtraceGraph``
       member's ``nodes`` array.
 
-    This field was added in codemodel version 2.6.
-
   ``precompileHeaders``
+    .. codemodel-versionadded:: 2.1
+
     Optional member that is present when :command:`target_precompile_headers`
     or other command invocations set :prop_tgt:`PRECOMPILE_HEADERS` on the
     target.  The value is a JSON array with an entry for each header.  Each
@@ -1843,8 +1845,6 @@ with members:
       unsigned integer 0-based index into the ``backtraceGraph`` member's
       ``nodes`` array.
 
-    This field was added in codemodel version 2.1.
-
   ``defines``
     Optional member that is present when there are preprocessor definitions.
     The value is a JSON array with an entry for each definition.  Each
@@ -2134,6 +2134,8 @@ The members specific to ``cmakeFiles`` objects are:
     if the path specifies a file in the CMake installation.
 
 ``globsDependent``
+  .. cmakefiles-versionadded:: 1.1
+
   Optional member that is present when the project calls :command:`file(GLOB)`
   or :command:`file(GLOB_RECURSE)` with the ``CONFIGURE_DEPENDS`` option.
   The value is a JSON array of JSON objects, each specifying a globbing
@@ -2141,8 +2143,6 @@ The members specific to ``cmakeFiles`` objects are:
   no longer matches the same list of paths, CMake considers the build system
   to be out of date.
 
-  This field was added in ``cmakeFiles`` version 1.1.
-
   The members of each entry are:
 
   ``expression``
@@ -2278,6 +2278,8 @@ The members specific to ``toolchains`` objects are:
       language. Its value is a JSON string holding the path to the compiler.
 
     ``commandFragment``
+      .. toolchains-versionadded:: 1.1
+
       Optional member that is present when the
       :variable:`CMAKE_<LANG>_COMPILER` variable is a list containing multiple
       elements or the :envvar:`CC` or similar environment variable contains
@@ -2285,8 +2287,6 @@ The members specific to ``toolchains`` objects are:
       Its value is a JSON string holding the second and further elements
       (mandatory arguments to the compiler) as a command line fragment.
 
-      This field was added in toolchains version 1.1.
-
     ``id``
       Optional member that is present when the
       :variable:`CMAKE_<LANG>_COMPILER_ID` variable is defined for the current

Utilities/Sphinx/cmake.py

@@ -896,20 +896,25 @@ def setup(app):
     app.add_transform(CMakeXRefTransform)
     app.add_domain(CMakeDomain)
 
-    versionlabels.update({
+    version_directives = {
-        'presets-versionadded':   'Added in presets version %s',
+        'cmakefiles': 'cmakeFiles',
-        'presets-versionchanged': 'Changed in presets version %s',
+        'codemodel': 'codemodel',
-        'presets-versionremoved': 'Removed in presets version %s',
+        'presets': 'presets',
-    })
+        'toolchains': 'toolchains',
-
+    }
-    versionlabel_classes.update({
+    for directive, name in version_directives.items():
-        'presets-versionadded':     'added',
+        versionlabels.update({
-        'presets-versionchanged':   'changed',
+            f'{directive}-versionadded':   f'Added in {name} version %s',
-        'presets-versionremoved':   'removed',
+            f'{directive}-versionchanged': f'Changed in {name} version %s',
-    })
+            f'{directive}-versionremoved': f'Removed in {name} version %s',
-
+        })
-    app.add_directive('presets-versionadded', VersionChange)
+        versionlabel_classes.update({
-    app.add_directive('presets-versionchanged', VersionChange)
+            f'{directive}-versionadded':   'added',
-    app.add_directive('presets-versionremoved', VersionChange)
+            f'{directive}-versionchanged': 'changed',
+            f'{directive}-versionremoved': 'removed',
+        })
+        app.add_directive(f'{directive}-versionadded', VersionChange)
+        app.add_directive(f'{directive}-versionchanged', VersionChange)
+        app.add_directive(f'{directive}-versionremoved', VersionChange)
 
     return {"parallel_read_safe": True}