Description

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: #define CYGSRC_KERNEL 1 #define CYGDBG_USE_ASSERTS 1 #include <pkgconf/kernel.h> #include <cyg/infra/cyg_ass.h> The assertion header file does not care whether CYGDBG_USE_ASSERTS is #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.

Example

cdl_option CYGDBG_KERNEL_USE_ASSERTS {
  display "Assertions in the kernel package"
  …
  if_define CYGSRC_KERNEL CYGDBG_USE_ASSERTS
  requires  CYGDBG_INFRA_ASSERTION_SUPPORT
}

See Also

Properties define, define_format, define_header, define_proc and no_define.