From 0bdb1a77d1ffe78da317c5fc724a8c4d8d5e0ae0 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sat, 11 Jul 2020 19:10:00 +1000 Subject: Help: Clarify wording of dir-related source property options --- Help/command/get_property.rst | 31 +++++++++++++-------- Help/command/get_source_file_property.rst | 41 +++++++++++++++++----------- Help/command/set_property.rst | 32 +++++++++++++--------- Help/command/set_source_files_properties.rst | 36 +++++++++++++----------- 4 files changed, 84 insertions(+), 56 deletions(-) diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst index 123cd45258..06025183ee 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst @@ -10,7 +10,7 @@ Get a property. DIRECTORY [] | TARGET | SOURCE | - [TARGET_DIRECTORY | DIRECTORY ] | + [DIRECTORY | TARGET_DIRECTORY ] | INSTALL | TEST | CACHE | @@ -31,18 +31,36 @@ It must be one of the following: Scope defaults to the current directory but another directory (already processed by CMake) may be named by the full or relative path ````. + See also the :command:`get_directory_property` command. ``TARGET`` Scope must name one existing target. + See also the :command:`get_target_property` command. ``SOURCE`` - Scope must name one source file. + Scope must name one source file. By default, the source file's property + will be read from the current source directory's scope, but this can be + overridden with one of the following sub-options: + + ``DIRECTORY `` + The source file property will be read from the ```` directory's + scope. CMake must already know about that source directory, either by + having added it through a call to :command:`add_subdirectory` or ```` + being the top level source directory. Relative paths are treated as + relative to the current source directory. + + ``TARGET_DIRECTORY `` + The source file property will be read from the directory scope in which + ```` was created (```` must therefore already exist). + + See also the :command:`get_source_file_property` command. ``INSTALL`` Scope must name one installed file path. ``TEST`` Scope must name one existing test. + See also the :command:`get_test_property` command. ``CACHE`` Scope must name one cache entry. @@ -50,15 +68,6 @@ It must be one of the following: ``VARIABLE`` Scope is unique and does not accept a name. -In the ``SOURCE`` case, the queried source file scope can be changed by -specifying one of the additional options: ``DIRECTORY`` or ``TARGET_DIRECTORY``. - -``DIRECTORY`` takes a path to a processed directory, and the source file property -will be read from that directory scope. - -``TARGET_DIRECTORY`` takes the name of an existing target. The source file -property will be read from this target's directory scope. - The required ``PROPERTY`` option is immediately followed by the name of the property to get. If the property is not set an empty value is returned, although some properties support inheriting from a parent scope diff --git a/Help/command/get_source_file_property.rst b/Help/command/get_source_file_property.rst index 1060251b47..76ed776c03 100644 --- a/Help/command/get_source_file_property.rst +++ b/Help/command/get_source_file_property.rst @@ -5,24 +5,33 @@ Get a property for a source file. .. code-block:: cmake - get_source_file_property(VAR file [TARGET_DIRECTORY | DIRECTORY ] property) + get_source_file_property( + [DIRECTORY | TARGET_DIRECTORY ] + ) Gets a property from a source file. The value of the property is -stored in the variable ``VAR``. If the source property is not found, the -behavior depends on whether it has been defined to be an ``INHERITED`` property -or not (see :command:`define_property`). Non-inherited properties will set -``VAR`` to "NOTFOUND", whereas inherited properties will search the relevant -parent scope as described for the :command:`define_property` command and -if still unable to find the property, ``VAR`` will be set to an empty string. - -The queried source file scope can be changed by specifying one of the -additional options: ``DIRECTORY`` or ``TARGET_DIRECTORY``. - -``DIRECTORY`` takes a path to a processed directory, and the source file property -will be read from that directory scope. - -``TARGET_DIRECTORY`` takes the name of an existing target. The source file -property will be read from this target's directory scope. +stored in the specified ````. If the source property is not found, +the behavior depends on whether it has been defined to be an ``INHERITED`` +property or not (see :command:`define_property`). Non-inherited properties +will set ``variable`` to ``NOTFOUND``, whereas inherited properties will search +the relevant parent scope as described for the :command:`define_property` +command and if still unable to find the property, ``variable`` will be set to +an empty string. + +By default, the source file's property will be read from the current source +directory's scope, but this can be overridden with one of the following +sub-options: + +``DIRECTORY `` + The source file property will be read from the ```` directory's + scope. CMake must already know about that source directory, either by + having added it through a call to :command:`add_subdirectory` or ```` + being the top level source directory. Relative paths are treated as + relative to the current source directory. + +``TARGET_DIRECTORY `` + The source file property will be read from the directory scope in which + ```` was created (```` must therefore already exist). Use :command:`set_source_files_properties` to set property values. Source file properties usually control how the file is built. One property that is diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index ccbd635fc9..93c2d9cf28 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -9,13 +9,13 @@ Set a named property in a given scope. DIRECTORY [] | TARGET [ ...] | SOURCE [ ...] - [TARGET_DIRECTORY ...] - [DIRECTORY ...] | + [DIRECTORY ...] | + [TARGET_DIRECTORY ...] INSTALL [ ...] | TEST [ ...] | CACHE [ ...] > [APPEND] [APPEND_STRING] - PROPERTY [value1 ...]) + PROPERTY [ ...]) Sets one property on zero or more objects of a scope. @@ -35,17 +35,23 @@ It must be one of the following: See also the :command:`set_target_properties` command. ``SOURCE`` - Scope may name zero or more source files. Note that source - file properties are by default visible only to targets added in the same - directory (``CMakeLists.txt``). - The file properties can be made visible in a different directory by specifying - one or both of the additional options: ``TARGET_DIRECTORY`` and ``DIRECTORY``. + Scope may name zero or more source files. By default, source file properties + are only visible to targets added in the same directory (``CMakeLists.txt``). + Visibility can be set in other directory scopes using one or both of the + following sub-options: + + ``DIRECTORY ...`` + The source file property will be set in each of the ```` + directories' scopes. CMake must already know about each of these + source directories, either by having added them through a call to + :command:`add_subdirectory` or it being the top level source directory. + Relative paths are treated as relative to the current source directory. + + ``TARGET_DIRECTORY ...`` + The source file property will be set in each of the directory scopes + where any of the specified ```` were created (the ```` + must therefore already exist). - ``DIRECTORY`` takes a list of processed directories paths, and sets the file - properties in those directory scopes. - - ``TARGET_DIRECTORY`` takes a list of existing targets. The file - properties will be set in these targets' directory scopes. See also the :command:`set_source_files_properties` command. ``INSTALL`` diff --git a/Help/command/set_source_files_properties.rst b/Help/command/set_source_files_properties.rst index 59d5ba3dfa..9558b4036b 100644 --- a/Help/command/set_source_files_properties.rst +++ b/Help/command/set_source_files_properties.rst @@ -5,29 +5,33 @@ Source files can have properties that affect how they are built. .. code-block:: cmake - set_source_files_properties([file1 [file2 [...]]] - [TARGET_DIRECTORY ...] - [DIRECTORY ...] - PROPERTIES prop1 value1 - [prop2 value2 [...]]) + set_source_files_properties( ... + [DIRECTORY ...] + [TARGET_DIRECTORY ...] + PROPERTIES + [ ] ...) Sets properties associated with source files using a key/value paired list. -Note that source file properties are by default visible only to -targets added in the same directory (``CMakeLists.txt``). +By default, source file properties are only visible to targets added in the +same directory (``CMakeLists.txt``). Visibility can be set in other directory +scopes using one or both of the following options: -The file properties can be made visible in a different directory by specifying -one or both of the additional options: ``TARGET_DIRECTORY`` and ``DIRECTORY``. +``DIRECTORY ...`` + The source file properties will be set in each of the ```` + directories' scopes. CMake must already know about each of these + source directories, either by having added them through a call to + :command:`add_subdirectory` or it being the top level source directory. + Relative paths are treated as relative to the current source directory. -``DIRECTORY`` takes a list of processed directories paths, and sets the file -properties in those directory scopes. - -``TARGET_DIRECTORY`` takes a list of existing targets. The file -properties will be set in these targets' directory scopes. +``TARGET_DIRECTORY ...`` + The source file properties will be set in each of the directory scopes + where any of the specified ```` were created (the ```` + must therefore already exist). +Use :command:`get_source_file_property` to get property values. See also the :command:`set_property(SOURCE)` command. See :ref:`Source File Properties` for the list of properties known -to CMake. Source file properties are visible only to targets added -in the same directory (``CMakeLists.txt``). +to CMake. -- cgit v1.2.1