aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--build2/variable23
1 files changed, 18 insertions, 5 deletions
diff --git a/build2/variable b/build2/variable
index 8f0969a..a3c1ea6 100644
--- a/build2/variable
+++ b/build2/variable
@@ -77,11 +77,24 @@ namespace build2
//
// The two variables are considered the same if they have the same name.
//
- // @@ Document override semantics.
- //
- // Note that we don't propagate variable type to override variables and we
- // keep override values as untyped names. So they get "typed" when they are
- // applied.
+ // If the variable is overridden on the command line, then override is the
+ // chain of the special override variables. Their names are derived from the
+ // main variable name as <name>.{__override,__prefix,__suffix} and they are
+ // not entered into the var_pool. The override variables only vary in their
+ // names and visibility.
+ //
+ // Note also that we don't propagate the variable type to override variables
+ // and we keep override values as untyped names. They get "typed" when they
+ // are applied.
+ //
+ // We use the "modify original, override on query" model. Because of that, a
+ // modified value does not necessarily represent the actual value so care
+ // must be taken to re-query after (direct) modification. And because of
+ // that, variables set by the C++ code are by default non-overridable.
+ //
+ // Initial processing including entering of global overrides happens in
+ // reset() before any other variables. Project wide overrides are entered in
+ // main(). Overriding happens in scope::find_override().
//
struct variable
{