Defines an inheritable text parameter, where users can enter a string value,
which you can use during a build, either as an environment variable, or
through variable substitution in some other parts of the configuration.
The difference to a normal String-Parameter is, that this parameter will
alter its behaviour when inherited to child projects.
You can either:
-
Keep the old behaviour of the parameter being overwritten by
the project with the highest priority,
-
allow the parameter to be extended by higher-prioritised projects,
or
-
completely prevent any overwriting. In that case, the first project
to set a variable (the one with the lowest priority) will set the
variable.
Furthermore, you can toggle the mandatory flag between two states:
-
If set to mandatory, the parameter has to be set,
before a build can be started. This might happen automatically
through a default value. The creator of a child project will be
warned during configuration, if a particular parameter is not
yet set.
-
If set to optional, the parameter can be assigned freely.
Do note that children can alter these flags on inheriting them, with the
following exceptions:
-
They may not change a mandatory field to be optional. They are
allowed to set a default though, which makes this field effectively
non-mandatory.
-
They are incapable (by design) of altering the overwritable
flag. Of course, they can always set an overwritable parameter to
non-overwritable.
-
While allowed, changing the flag from overwritable to extensible
and/or back can lead to surprising results, as the output depends
on the serialisation of the parameters according to their order.
Assume a parameter is overwritable in A and extensible in B and both
are inherited by C.
If A is ordered before B, then:
-
C will only get the value of B, and
-
if C overwrites the value, it will extend the value.
If B is ordered before A, then:
-
C will get the value of B extended by A, and
-
if C overwrites the value, it will replace it completely.
Violating these restrictions results in a non-buildable project and a
warning during configuration. This may happen insidiously, if a parameter
is defined separately in two parents with differing flags.