what's the meaing of this sentence?

Usage
1

Hi guys,

in this page https://cmake.org/cmake/help/latest/command/set_directory_properties.html there is a sentence

Sets properties of the current directory and its subdirectories in key-value pairs.

I’m trying to verify it by (in parent CMakeLists.txt)

set_directory_properties(PROPERTIES prop1 value1)
add_subdirectory(sub)

and

add_subdirectory(sub)
set_directory_properties(PROPERTIES prop1 value1)

in sub/CMakeLists.txt

get_directory_property(x prop1)
message("prop1 `${x}`")

in both case I cannot read prop1 , any suggestion?

2

OK, so it turns out that statement is a bit misleading.

CMake will propagate some properties to subdirectories, but only when they are:

  1. on the list of Properties on Directories (i.e. not the ones you define yourself)
  2. Not documented as read-only, on that list
  3. And, documented as also affecting subdirectories, on that list

LABELS, for example, is documented as allowing you to:

Specify a list of text labels associated with a directory and all of its subdirectories.

So, if you run this in a parent directory (BEFORE the add_subdirectory(), that part’s important):

set_directory_properties(PROPERTIES
    CLEAN_NO_CUSTOM TRUE
    LABELS "test"
    MY_SPECIAL_PROP "is a special prop"
)
add_subdirectory(sub)

Then, in your subdirectory LABELSwill be set, but neither CLEAN_NO_CUSTOM nor MY_SPECIAL_PROP will be.

The list of propagated directory properties is actually very short, LABELS is the only one I’ve found so far.

Note that you can also set properties on subdirectories, directly, using set_property():

# In the root CMakeLists.txt
add_subdirectory(sub)
set_property(DIRECTORY sub
  PROPERTY
    CLEAN_NO_CUSTOM TRUE
)

Then, CLEAN_NO_CUSTOM will be set in sub/. Note that in that case, though, the set_property() has to come after the add_subdirectory().

3

Aha! You can, however, create your own properties that will be propagated to subdirectories, using define_property() with the INHERITED argument.

define_property(DIRECTORY
  PROPERTY MY_SPECIAL_PROP
  INHERITED
  BRIEF_DOCS "A propagated special property"
)
set_directory_properties(PROPERTIES
  LABELS "test"
  MY_SPECIAL_PROP "is a special prop"
)
add_subdirectory(sub)

…Will result in MY_SPECIAL_PROP being set in sub/ as well.

(Interestingly, the documentation for INHERITED describes it as working in completely the opposite way — it’s not that MY_SPECIAL_PROP will also be set in sub/ when you set it at the root level, it’s that requests for MY_SPECIAL_PROP in sub/ will automatically look for properties in the parent scope when they’re not defined in the current scope, as long as they’re marked INHERITED.

I don’t know if that really means INHERITED properties are different from the propagating ones like LABELS, or if LABELS is also an INHERITED property that’s just described more simplistically in the documentation. I also don’t know if it really makes any practical difference whether they work the same way or not.)