The purpose of the if_define property is best explained by an example. Suppose you want finer-grained control over assertions, say on a per-package or even a per-file basis rather than globally. The assertion macros can be defined by an exported header file in an infrastructure package, using code like the following:
#ifdef CYGDBG_USE_ASSERTS
# define CYG_ASSERT( _bool_, _msg_ ) \
CYG_MACRO_START \
if ( ! ( _bool_ ) ) \
CYG_ASSERT_DOCALL( _msg_ ); \
CYG_MACRO_END
#else
# define CYG_ASSERT( _bool_, _msg_ ) CYG_EMPTY_STATEMENT
#endif |
Assuming this header file is #include'd directly or
indirectly by any code which may need to be built with assertions
enabled, the challenge is now to control whether or not
CYGDBG_USE_ASSERTS is defined for any given source
file. This is the purpose of the if_define property:
cdl_option CYGDBG_KERNEL_USE_ASSERTS {
…
if_define CYGSRC_KERNEL CYGDBG_USE_ASSERTS
requires CYGDBG_INFRA_ASSERTION_SUPPORT
} |
If this option is active and enabled then the kernel's configuration header file would end up containing the following:
#ifdef CYGSRC_KERNEL # define CYGDBG_USE_ASSERTS 1 #endif |
Kernel source code can now begin with the following construct:
#define CYGSRC_KERNEL 1 #include <pkgconf/kernel.h> #include <cyg/infra/cyg_ass.h> |
The configuration option only affects kernel source code, assuming
nothing else #define's the symbol
CYGSRC_KERNEL. If the per-package assertion option
is disabled then CYGDBG_USE_ASSERTS will not get
defined. If the option is enabled then
CYGDBG_USE_ASSERTS will get defined and assertions
will be enabled for the kernel sources. It is possible to use the same
mechanism for other facilities such as tracing, and to apply it at a
finer grain such as individual source files by having multiple options
with if_define properties and multiple symbols such as
CYGSRC_KERNEL_SCHED_BITMAP_CXX.
The if_define property takes two arguments, both of which must be valid C preprocessor symbols. If the current option is active and enabled then three lines will be output to the configuration header file:
#ifdef <symbol1> # define <symbol2> #endif |
If the option is inactive or disabled then these lines will not be output. By default the current package's configuration header file will be used, but it is possible to specify an alternative destination using a -file option. At present the only legitimate alternative destination is system.h, the global configuration header. if_define processing happens in addition to, not instead of, the normal #define processing or the handling of other header-file related properties.
Note: The infrastructure in the current eCos release does not yet work this way. In future it may do so, and the intention is that suitable configuration options get generated semi-automatically by the configuration system rather than having to be defined explicitly.
Tip: As an alternative to changing the configuration, updating the build tree, and so on, it is possible to enable assertions by editing a source file directly, for example:
The assertion header file does not care whether
CYGDBG_USE_ASSERTSis #define'd via a configuration option or by explicit code. This technique can be useful to component writers when debugging their source code, although care has to be taken to remove any such #define's later on.