1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="The eCos Component Writer's Guide"
20 HREF="cdl-guide.html"><LINK
22 TITLE="CDL Language Specification"
23 HREF="reference.html"><LINK
26 HREF="ref.hardware.html"><LINK
29 HREF="ref.implements.html"></HEAD
40 SUMMARY="Header navigation table"
52 > Component Writer's Guide</TH
60 HREF="ref.hardware.html"
74 HREF="ref.implements.html"
85 NAME="REF.IF-DEFINE"><SPAN
99 > -- Output a common preprocessor construct to a configuration
102 CLASS="REFSYNOPSISDIV"
114 >cdl_option <name> {
115 if_define [-file=<filename>] <symbol1> <symbol2>
130 >The purpose of the <SPAN
133 > property is best explained by an
134 example. Suppose you want finer-grained control over assertions, say
135 on a per-package or even a per-file basis rather than globally. The
136 assertion macros can be defined by an exported header file in an
137 infrastructure package, using code like the following:</P
145 CLASS="PROGRAMLISTING"
146 >#ifdef CYGDBG_USE_ASSERTS
147 # define CYG_ASSERT( _bool_, _msg_ ) \
149 if ( ! ( _bool_ ) ) \
150 CYG_ASSERT_DOCALL( _msg_ ); \
153 # define CYG_ASSERT( _bool_, _msg_ ) CYG_EMPTY_STATEMENT
159 >Assuming this header file is <TT
163 indirectly by any code which may need to be built with assertions
164 enabled, the challenge is now to control whether or not
167 >CYGDBG_USE_ASSERTS</TT
168 > is defined for any given source
169 file. This is the purpose of the <SPAN
180 CLASS="PROGRAMLISTING"
181 >cdl_option CYGDBG_KERNEL_USE_ASSERTS {
183 if_define CYGSRC_KERNEL CYGDBG_USE_ASSERTS
184 requires CYGDBG_INFRA_ASSERTION_SUPPORT
190 >If this option is active and enabled then the kernel's configuration
191 header file would end up containing the following:</P
199 CLASS="PROGRAMLISTING"
200 >#ifdef CYGSRC_KERNEL
201 # define CYGDBG_USE_ASSERTS 1
207 >Kernel source code can now begin with the following construct:</P
215 CLASS="PROGRAMLISTING"
216 >#define CYGSRC_KERNEL 1
217 #include <pkgconf/kernel.h>
218 #include <cyg/infra/cyg_ass.h></PRE
223 >The configuration option only affects kernel source code, assuming
231 >. If the per-package assertion option
234 >CYGDBG_USE_ASSERTS</TT
236 defined. If the option is enabled then
239 >CYGDBG_USE_ASSERTS</TT
240 > will get defined and assertions
241 will be enabled for the kernel sources. It is possible to use the same
242 mechanism for other facilities such as tracing, and to apply it at a
243 finer grain such as individual source files by having multiple options
247 > properties and multiple symbols such as
250 >CYGSRC_KERNEL_SCHED_BITMAP_CXX</TT
256 > property takes two arguments, both of which must be
257 valid C preprocessor symbols. If the current option is active and
258 enabled then three lines will be output to the configuration header
267 CLASS="PROGRAMLISTING"
268 >#ifdef <symbol1>
269 # define <symbol2>
275 >If the option is inactive or disabled then these lines will not be
276 output. By default the current package's configuration header file
277 will be used, but it is possible to specify an alternative destination
281 > option. At present the only
282 legitimate alternative destination is <TT
286 global configuration header. <SPAN
289 > processing happens in
290 addition to, not instead of, the normal <TT
294 processing or the handling of other header-file related properties.</P
302 >The infrastructure in the current <SPAN
305 > release does not yet work
306 this way. In future it may do so, and the intention is that suitable
307 configuration options get generated semi-automatically by the
308 configuration system rather than having to be defined explicitly.</P
318 >As an alternative to changing the configuration, updating the build
319 tree, and so on, it is possible to enable assertions by editing a
320 source file directly, for example:</P
328 CLASS="PROGRAMLISTING"
329 >#define CYGSRC_KERNEL 1
330 #define CYGDBG_USE_ASSERTS 1
331 #include <pkgconf/kernel.h>
332 #include <cyg/infra/cyg_ass.h></PRE
337 >The assertion header file does not care whether
340 >CYGDBG_USE_ASSERTS</TT
345 via a configuration option or by explicit code. This technique can be
346 useful to component writers when debugging their source code, although
347 care has to be taken to remove any such <TT
369 CLASS="PROGRAMLISTING"
370 >cdl_option CYGDBG_KERNEL_USE_ASSERTS {
371 display "Assertions in the kernel package"
373 if_define CYGSRC_KERNEL CYGDBG_USE_ASSERTS
374 requires CYGDBG_INFRA_ASSERTION_SUPPORT
389 HREF="ref.define.html"
396 HREF="ref.define-format.html"
403 HREF="ref.define-header.html"
410 HREF="ref.define-proc.html"
417 HREF="ref.no-define.html"
429 SUMMARY="Footer navigation table"
440 HREF="ref.hardware.html"
449 HREF="cdl-guide.html"
458 HREF="ref.implements.html"
477 HREF="reference.html"