EBuild Settings
EBuild Projects are made up of two types of items: Objects and Settings.
Settings represent named string values that control how EBuild behaves to build your project. Settings have a Name and a Value. Only one setting for each name can be active at a time.
Inside the project, settings can be set globally, or for a specific configuration or a specific target.
If a setting is set on multiple levels, the most precise setting "wins" (e.g. if a setting is defined globally and for a configuration, the latter setting overrides the former). If a setting is specified multiple times on the same level, the last value encountered in the project file "wins". If a setting is not specified at all, a well-defined default value may be used.
How Settings are Resolved
At build time, EBuild starts out with a flat list of settings driven by two inputs
- the settings specified in the project itself
- any settings overridden from the command line via the
--setting:Command Line Switch.
During build, tasks can add new or override existing settings with new values.
When a build task asks for a setting by name, the following logic is used to determine the value. The first value encountered will be used:
- Value overridden/set with a new value earlier during the same build cycle.
- Value overridden from the command line via
--setting:. - Value defined in the
.userfile for the project. -
If the current task runs within the context of a specific target:
- Value defined in the .user file, matching the target name and the active configuration.
- Value defined in the .user file, matching the target name and without configuration.
- Value defined in the project, matching the target name and the active configuration.
- Value defined in the project matching the target name and without configuration.
- Value defined in the project without target name and matching active configuration.
- Value defined in the project without target name or configuration.
- Value from the active Defaults Provider (see below).
If neither of the above steps returns a value, the setting is considered undefined.
Note that EBuild does not distinguish between undefined settings and an empty string value. If any of the steps above returns an empty string (e.g. due to an empty element in the project file), the behavior is the same as if the setting was not defined at all.
Undefined required settings are considered a fatal error. In particular, this applies to boolean (True/False) or enum settings.
For boolean settings, the string "True" is considered true, regardless of case, any other values will be considered false.
Defaults Providers
As last resort, a project-specific Defaults Provider is considered for determining a default value for the setting. For Elements projects, this is the ElementsDefaultProvider.
ElementsDefaultProvider is the canonical reference for all defaults for Elements. No other part of the build chain is to have hard-coded assumptions on what the lack of a certain setting means, and all required settings (most importantly including all boolean flags, such as toggles for compiler behavior) must be covered by ElementsDefaultProvider.
ElementsDefaultProvider is used by all parts of the build tool chain, including the compiler, and also by the development environments to represent default values in Project Settings and elsewhere where settings affect IDE behavior.