MantisBT - CMake
View Issue Details
IDProjectCategoryView StatusDate SubmittedLast Update
0013269CMakeDocumentationpublic2012-06-04 14:552012-11-05 14:33
Reportersleske 
Assigned ToBrad King 
PrioritynormalSeverityminorReproducibilityN/A
StatusclosedResolutionfixed 
PlatformOSOS Version
Product VersionCMake 2.8.8 
Target VersionCMake 2.8.9Fixed in VersionCMake 2.8.9 
Summary0013269: Improved documentation for "set" command
DescriptionThe documentation of the "set" command is incomplete and somewhat confusing (as shown by problems like those described in 0009008).

I have tried to improve the documentation; see attached patch.

Disclaimer: I'm new to CMake, so there may still be errors; feel free to correct them, or point them out so I can fix them.

Steps To Reproduce
Additional InformationThe attached patch is against CMake master HEAD from today (2012-06-04).
TagsNo tags attached.
Relationships
related to 0009008closed  modify behaviour of "normal" and cache variables 
Attached Filesdiff set-doc-2012-06-04.diff (3,282) 2012-06-04 14:55
https://public.kitware.com/Bug/file/4342/set-doc-2012-06-04.diff
diff set-doc-2012-06-11.diff (7,058) 2012-06-11 15:30
https://public.kitware.com/Bug/file/4353/set-doc-2012-06-11.diff
Issue History
Date ModifiedUsernameFieldChange
2012-06-04 14:55sleskeNew Issue
2012-06-04 14:55sleskeFile Added: set-doc-2012-06-04.diff
2012-06-04 15:58David ColeRelationship addedrelated to 0009008
2012-06-05 10:45Brad KingNote Added: 0029612
2012-06-05 11:06Brad KingNote Added: 0029613
2012-06-07 13:57sleskeNote Added: 0029629
2012-06-11 15:30sleskeFile Added: set-doc-2012-06-11.diff
2012-06-11 15:34sleskeNote Edited: 0029629bug_revision_view_page.php?bugnote_id=29629#r666
2012-06-17 16:19sleskeNote Added: 0029712
2012-06-18 08:52Brad KingNote Added: 0029716
2012-06-18 08:52Brad KingAssigned To => Brad King
2012-06-18 08:52Brad KingStatusnew => resolved
2012-06-18 08:52Brad KingResolutionopen => fixed
2012-06-18 08:52Brad KingFixed in Version => CMake 2.8.9
2012-06-18 08:52Brad KingTarget Version => CMake 2.8.9
2012-06-18 10:03Brad KingNote Edited: 0029716bug_revision_view_page.php?bugnote_id=29716#r682
2012-11-05 14:33David ColeNote Added: 0031454
2012-11-05 14:33David ColeStatusresolved => closed

Notes
(0029612)
Brad King   
2012-06-05 10:45   
I've resolved 0009008 as "won't fix" because the current behavior is perfectly justifiable. In this issue we can discuss how to document it more clearly.
(0029613)
Brad King   
2012-06-05 11:06   
The proposed documentation is not quite correct. Also, it shouldn't have to reference a CMake bug tracker issue to be complete.

There are two types of variables: normal variables and cache variables. Both types can exist at the same time with the same name but different values. When ${FOO} is evaluated, CMake first looks for a normal variable "FOO" in scope and uses it if set. If and only if no normal variable exists then it falls back to the cache variable "FOO".

The code

 set(FOO "x")

sets the normal variable "FOO". It does not touch the cache but it can *hide* any existing cache value "FOO".

The code

 set(FOO "x" CACHE ...)

checks for "FOO" in the cache, ignoring any normal variable of the same name. If "FOO" is in the cache then nothing happens to either the normal variable or the cache variable. If "FOO" is not in the cache, then it is added to the cache. This also triggers the behavior in the next paragraph.

Finally, whenever a cache variable is added or modified by a command, CMake also *removes* the normal variable of the same name from the current scope so that an immediately following evaluation of it will expose the newly cached value.

The documentation should be updated to clarify the above rules.

If projects avoid using normal and cache variables of the same name then there is no interaction. It's only when they start doing something fancy internally with options that the user normally sets that things get tricky.

The "confusing" behavior comes in cases like that summarized in 0009008:0018029. In that case a parent project is providing the same option as a child project. The parent gets the first chance to add a user-editable option to the cache. However, it wants to hard-code the value for the child project's option while still allowing the user to edit the value used by the parent project. The parent project achieves this simply by setting a normal variable with the same name as the option in a scope sufficient to hide the option's cache variable from the child completely. The parent has already set *both* the cache and normal variables so the child's set(...CACHE...) should do nothing to change them. This pattern appears in many projects I've seen. The proposal in 0009008 would undermine the parent's ability to do this.
(0029629)
sleske   
2012-06-07 13:57   
(edited on: 2012-06-11 15:34)
Patch updated; new version is set-doc-2012-06-11.diff.

I have incorporated the explanations by Brad King (thanks!). I hope everything is correct (and clear) now.

I realize the docs are rather long now, but I think this is necessary, because there is a fair bit to explain. Of course, I'm open to suggestions for improvement.
(0029712)
sleske   
2012-06-17 16:19   
Hi, any chance of getting this patch accepted? Or is there something else to correct?
(0029716)
Brad King   
2012-06-18 08:52   
(edited on: 2012-06-18 10:03)
Re 0013269:0029712: Yes:

 http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=f2c1f240 [^]

Sorry for the long delay. It seems the notification email from 0013269:0029629 never made it to my eyes.
(0031454)
David Cole   
2012-11-05 14:33   
Closing resolved issues that have not been updated in more than 4 months.