+ :local:
+
+-------------------
+Configuration logic
+-------------------
+
+Moe and the derived modules use many configuration variables indicating i.e. working directories,
+task name, compiler commandline and options, current test name and name of test file to use.
+All values are treated as text and may contain unicode characters (although this is usually not advisable).
+A variable may be either set to a simple fixed string or to a string containing expansions of other variables.
+The configuration library also supports appending text, conditionals and a simple variable hierarchy.
+
+For the complete configuration syntax grammar, see :mod:`moe.config_parser` documentation.
+
+Generally, both whitespace and indentation are optional and do not matter, individual
+operations must be separated by either ``;`` or newline, ``#`` introduces a comment until the end of the line.
+
+In *moe*, the config files are assumed to be in UTF-8, but using non-ASCII characters are discouraged outside
+comments (mainly because not all unix comands handle unicode well).
+
+Variables and substitution
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The names of the variables may consist of letters, numbers, underscore, dash and a dot. Dot acts as
+a separator of the variable name hierarchy and may not occur at the beginning or the end of variable name,
+nor adjacent to another dot. The tree hierarchy is provided only for user's convenience and does not play
+any significant role in variable evaluation.
+
+The value of a variable may be defined by several operations:
+
+**SET**, ``VAR = "value"``
+ Sets the variable to the variable-expansion of the string.
+
+**APPEND**, ``VAR += "value"``
+ Appends the variable-expansion of the string.
+
+Value is a ``"``-delimited string that may contain substitutions in the form ``{VARNAME}`` i.e.
+``"source-{VERSION}.{SUFFIX}"``, where ``VERSION`` and ``SUFFIX`` are the substituted variables.
+The string may contain any characters including unicode (although this is not always advisable).
+Characters ``"``, ``{``, ``{`` and ``\`` have to be escaped with ``\``, i.e. ``\"``, ``\{``, ``\{`` and ``\\``.
+
+When evaluating a variable, all the substitutions are evaluated as well. Every variable is evaluated
+in the same way, independently of the priority of the operations it occurs in. The substitutions must
+therefore be acyclic and a variable may not contain itself as a substitution.
+
+
+Operation priority
+^^^^^^^^^^^^^^^^^^
+
+Each operation has a priority usually depending on its origin, i.e. builtins, global config file, task config file
+or commandline overrides.
+Only the **SET** operation with the highest priority and higher priority **APPENDs** are used (as if all operations were
+applied from the least priority operation to the highest).
+Operations of the same priority are processed by their definition order (first to last).
+
+For example, in builtins (priority 0) we may have::
+
+ COMPILE = "{CC} {OPTS} {INFILE} -o {OUTFILE}"
+ OPTS = "-O{OPTIMIZE}"
+ CC = "gcc"
+
+In config file (priority 30)::
+
+ OPTS += " -W{WARNOPT}" # OPTS is now "-O{OPTIMIZE} -W{WARNOPT}"
+ WARNOPT = "all"
+ OPTIMIZE = "0"
+
+And in command-line overrides (priority 100)::
+
+ COMPILE = "cp {INFILE} {OUTFILE}"
+
+Moe would then later set ``INFILE`` and ``OUTFILE`` at some point before evaluating and executing
+the compilation command.
+
+With these *lazy* semantics, it is possible to set a variable to a value depending
+on both higher- and lower-priority operations.
+
+.. note::
+ The implementation is actually very efficient and recalculates only the necessary values,
+ caching the results. Adding/removing operations to variables only recursively invalidates the
+ (potentially) influenced cached values, these are recalculated lazily on-demand.
+
projects / moe.git / blobdiff