The eCos Component Writer's Guide
Prev |  | Next

# define

## Name

Property define -- Specify additional `#define` symbols that should go into the owning package's configuration header file.

## Synopsis

    cdl_option <name> {
        define [-file=<filename>] [-format=<format>] <symbol>
        …
    }

## Description

Normally the configuration system generates a single `#define` for each option that is active and enabled, with the defined symbol being the name of the option. These `#define's` go to the package's own configuration header file, for example `pkgconf/kernel.h` for kernel configuration options. For the majority of options this is sufficient. Sometimes it is useful to have more control over which `#define's` get generated.

The define property can be used to generate an addition `#define` if the option is both active and enabled, for example:

    cdl_option CYGNUM_LIBC_STDIO_FOPEN_MAX {
        …
        define FOPEN_MAX
    }

If this option is given the value 40 then the following `#define's` will be generated in the configuration header `pkgconf/libc.h`:

    #define CYGNUM_LIBC_STDIO_FOPEN_MAX 40
    #define FOPEN_MAX 40

The default `#define` can be suppressed if desired using the no_define property. This is useful if the symbol should only be defined in `pkgconf/system.h` and not in the package's own configuration header file. The value that will be used for this `#define` is the same as for the default one, and depends on the option's flavor as follows:

`flavor none`

  Options with this flavor are always enabled and have no value, so the constant `1` will be used.

`flavor bool`

  If the option is disabled then no `#define` will be generated. Otherwise the constant `1` will be used.

`flavor booldata`

  If the option is disabled then no `#define` will be generated. Otherwise the option's current value will be used.

`flavor data`

  The option's current value will be used.

For active options with the `data` flavor, and for active and enabled options with the `booldata` flavor, either one or two `#define's` will be generated. These take the following forms:

    #define <symbol> <value>
    #define <symbol>_<value>

For the first `#define` it is possible to control the format used for the value using a `-format=<format>` option. For example, the following can be used to output some configuration data as a C string:

    cdl_option <name> {
        …
        define -format="\\\"%s\\\"" <symbol>
    }

The implementation of this facility involves concatenating the Tcl command `format`, the format string, and the string representation of the option's value, and evaluating this in a Tcl interpreter. Therefore the format string will be processed twice by a Tcl parser, and appropriate care has to be taken with quoting.

The second `#define` will be generated only if is a valid C preprocessor macro symbol. By default the symbols generated by define properties will end up in the package's own configuration header file. The `-file` option can be used to specify an alternative destination. At the time of writing the only valid alternative definition is `-file=system.h`, which will send the output to the global configuration header file `pkgconf/system.h`.

Caution
Care has to be taken with the `-format` option. Because the Tcl interpreter's `format` command is used, this property is subject to any problems with the implementation of this in the Tcl library. Generally there should be no problems with string data or with integers up to 32 bits, but there may well be problems if 64-bit data is involved. This issue may be addressed in a future release.

## Example

    cdl_component CYG_HAL_STARTUP {
        display       "Startup type"
        flavor        data
        legal_values  {"RAM" "ROM" }
        default_value {"RAM"}
        no_define
        define -file=system.h CYG_HAL_STARTUP
        …
    }

## See Also

Properties define_format, define_header, define_proc, if_define and no_define.

Prev | Home | Next
default_value | Up | define_format