[cmake-developers] Ideas on Properties

[Ken Martin]

Here are some thoughts I've been having on address the abundance of
undocumented global variables and some scoping issues. I am still chewing on
these issues but wanted to throw out my thoughts so far and get any ideas
etc from you all.

Thanks
Ken


Ideas on properties
----------------------

The Issue
---------
CMake's behavior is impacted by a very large number of mostly undocumented
variables. The users do not know what these variables are or what they do in
general. There are very limited mechanisms for scoping variables or
documenting them. This shows up when we talk about the notion of setting a
value for all source files of a target, but than can be overridden on
specific source files.

Ideas to address this
-----------------------

One idea is to make properties member variables and then basically wrap the
C++ classes into CMake. Effective I'm guessing this boils down to

add_target(fubar foo.c bar.c)

fubar(METHOD ARG ARG ARG)
foo(METHOD ARG ARG)

or maybe

invoke(fubar METHOD ARG ARG ARG)
invoke(foo METHOD ARG ARG)

depending on how you like to wrap objects. Then each property could be added
as a Set/Get method on the C++ object what would get wrapped into CMake. But
it doesn't fit well with properties that may be added and used by CMake
scripts at Configure time and i doesn't really fit with the rest of the
language.

Another idea is to add CMake commands to work with properties. For example

# this records the name of the property, and provides help without setting
it
DEFINE_PROPERTY(SCOPE NAME "help string comment" [TYPE] [CHAIN])

where scope is GLOBAL, CACHE, DIRECTORY, TARGET, FILE

chain indicates if the property is not found in the current scope if it
should then check the broader scopes in order File, target, directory, cmake

# retrieve the value of a property
GET_PROPERTY(VAR SCOPE PROPNAME)

SCOPE would be GLOBAL, CACHE, DIRECTORY dirname, TARGET tgtname, SOURCE
srcname

# and set values
SET_PROPERTIES(SCOPE [SCOPE 2] ... [SCOPE N] 
                 PROPERTIES NAME1 VALUE1 NAME2 VALUE2 ...)

Then CMake can be run to produce help for all the properties that have been
defined (using DEFINE_PROPERTY) which provides a mechanism for
documentation. On the down side it is effectively gluing on a bit of OO onto
a language that is clearly not OO. Also it overlaps a tad with the notion of
a variable so there could be some confusion between properties and
variables. We also have a bunch of SET_TARGET_PROPERTIES type commands


Currently we have for variables ....

SET(VAR [VALUE] [CACHE TYPE DOCSTRING [FORCE]])

and

${VAR} which is effectively GET(VAR)