default_value

Name

Property default_value -- Provide a default value for this option using a CDL expression.

Synopsis

cdl_option <name> {
    default_value <expression>
    …
}

Description

The default_value property allows the initial value of a configuration option to depend on other configuration options. The arguments to the property should be a CDL expression, see the Section called Ordinary Expressions in Chapter 3 for the syntactic details. In many cases a simple constant value will suffice, for example:

cdl_component CYGPKG_KERNEL_EXCEPTIONS {
    …
    default_value 1

    cdl_option CYGSEM_KERNEL_EXCEPTIONS_DECODE {
        …
        default_value 0
    }
}

However it is also possible for an option's default value to depend on other options. For example the common HAL package provides some support functions that are needed by the eCos kernel, but are unlikely to be useful if the kernel is not being used. This relationship can be expressed using:

cdl_option CYGFUN_HAL_COMMON_KERNEL_SUPPORT {
    ...
    default_value CYGPKG_KERNEL
}

If the kernel is loaded then this HAL option is automatically enabled, although the user can still disable it explicitly should this prove necessary. If the kernel is not loaded then the option is disabled, although it can still be enabled by the user if desired. default_value expressions can be more complicated than this if appropriate, and provide a very powerful facility for component writers who want their code to “just do the right thing” in a wide variety of configurations.

The CDL configuration system evaluates the default_value expression when the current package is loaded and whenever there is a change to any other option referenced in the expression. The result depends on the option's flavor:

flavor none

Options with this flavor have no value, so the default_value property is not applicable.

flavor bool

If the expression evaluates to a non-zero result the option is enabled by default, otherwise it is disabled.

flavor booldata

If the result of evaluating the expression is zero then the option is disabled, otherwise the option is enabled and its value is the result.

flavor data

The default value of the option is the result of evaluating the expression.

A cdl_option or other entity can have at most one default_value property, and it is illegal to have both a calculated and a default_value property in one body. If an option does not have either a default_value or a calculated property and it does not have the flavor none then the configuration tools will assume a default value expression of 0.

On occasion it is useful to have a configuration option A which has both a requires constraint on some other option B and a default_value expression of B. If option B is not enabled then A will also be disabled by default and no conflict arises. If B is enabled then A also becomes enabled and again no conflict arises. If a user attempts to enable B but not A then there will be a conflict. Users should be able to deduce that the two options are closely interlinked and should not be manipulated independently except in very unusual circumstances.

Tip: If the first entry in a default_value expression is a negative number, for example default_value -1 then this can be misinterpreted as an option instead of as part of the expression. Currently the default_value property does not take any options, but this may change in future. Option processing halts at the sequence --, so the desired value can be expressed safely using default_value -- -1

Note: In many cases it would be useful to calculate default values using some global preferences, for example:

cdl_option CYGIMP_LIBC_STRING_PREFER_SMALL_TO_FAST {
    …
    default_value CYGGLO_CODESIZE > CYGGLO_SPEED
}

Such global preference options do not yet exist, but are likely to be added in a future version.

Note: For options with the booldata flavor the current syntax does not allow the default values of the enabled flag and the value to be controlled separately. Functionality to permit this may be added in a future release.

Example

cdl_option CYGDBG_HAL_DEBUG_GDB_THREAD_SUPPORT {
    display       "Include GDB multi-threading debug support"
    requires      CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
    default_value CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
    description   "
        This option enables some extra HAL code which is needed
        to support multi-threaded source level debugging."
}

See Also

Properties calculated, flavor and legal_values.

2017-02-09
Documentation license for this page: Open Publication License