build.headers.html

ecos源代码包

defined then the first <TT
CLASS="LITERAL"
>#define</TT
> will take the form:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define &lt;option&gt; &lt;value&gt;</PRE
></TD
></TR
></TABLE
><P
>For example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define CYGNUM_LIBC_ATEXIT_HANDLERS 32</PRE
></TD
></TR
></TABLE
><P
>Package source code can examine this value using the
<TT
CLASS="LITERAL"
>#if</TT
> directive, or by using the symbol in
code such as:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    for (i = 0; i &#60; CYGNUM_LIBC_ATEXIT_HANDLERS; i++) {
        &#8230;
    }</PRE
></TD
></TR
></TABLE
><P
>It must be noted that the <TT
CLASS="LITERAL"
>#define</TT
> will be generated
only if the corresponding option is both active and enabled. Options
with the <TT
CLASS="LITERAL"
>data</TT
> flavor are always enabled but may not
be active. Code like the above should be written only if it is known
that the symbol will always be defined, for example if the
corresponding source file will only get built if the containing
component is active and enabled. Otherwise the use of additional
<TT
CLASS="LITERAL"
>#ifdef</TT
> or similar directives will be necessary.</P
></LI
><LI
><P
>If there is a <SPAN
CLASS="PROPERTY"
>define_format</SPAN
> property then this controls how the
option's value will appear in the header file. Given a format string
such as <TT
CLASS="LITERAL"
>%08x</TT
> and a value 42, the component
framework will execute the <SPAN
CLASS="APPLICATION"
>Tcl</SPAN
> command
<TT
CLASS="LITERAL"
>format&nbsp;%08x&nbsp;42</TT
> and the result will be
used for the <TT
CLASS="LITERAL"
>#define's</TT
> value. It is the
responsibility of the component writer to make sure that this <SPAN
CLASS="APPLICATION"
>Tcl</SPAN
>
command will be valid given the format string and the legal values for
the option.</P
></LI
><LI
><P
>In addition a second <TT
CLASS="LITERAL"
>#define</TT
> may or may not be
generated. This will take the form:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define &lt;option&gt;_&lt;value&gt;</PRE
></TD
></TR
></TABLE
><P
>For example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define CYGNUM_LIBC_ATEXIT_HANDLERS_32</PRE
></TD
></TR
></TABLE
><P
>The <TT
CLASS="LITERAL"
>#define</TT
> will be generated only if it would
result in a valid C preprocessor symbol. If the value is a string such
as <TT
CLASS="LITERAL"
>"/dev/ser0"</TT
> then the <TT
CLASS="LITERAL"
>#define</TT
>
would be suppressed. This second <TT
CLASS="LITERAL"
>#define</TT
> is not
particularly useful for numerical data, but can be valuable in other
circumstances. For example if the legal values for an option
<TT
CLASS="LITERAL"
>XXX_COLOR</TT
> are <TT
CLASS="LITERAL"
>red</TT
>,
<TT
CLASS="LITERAL"
>green</TT
> and <TT
CLASS="LITERAL"
>blue</TT
> then code like
the following can be used:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#ifdef XXX_COLOR_red
    &#8230;
#endif
#ifdef XXX_COLOR_green
    &#8230;
#endif
#ifdef XXX_COLOR_blue
    &#8230;
#endif</PRE
></TD
></TR
></TABLE
><P
>The expression syntax provided by the C preprocessor is limited to
numerical data and cannot perform string comparisons. By generating
two <TT
CLASS="LITERAL"
>#define's</TT
> in this way it is possible to work
around this limitation of the C preprocessor. However some care has to
be taken: if a component writer also defined a configuration option
<TT
CLASS="LITERAL"
>XXX_COLOR_green</TT
> then there will be confusion. Since
such a configuration option violates the naming conventions, the
problem is unlikely to arise in practice.</P
></LI
></OL
></LI
><LI
><P
>For some options it may be useful to generate one or more additional
<TT
CLASS="LITERAL"
>#define's</TT
> or, in conjunction with the <SPAN
CLASS="PROPERTY"
>no_define</SPAN
>
property, to define a symbol with a name different from the option's
name. This can be achieved with the <SPAN
CLASS="PROPERTY"
>define</SPAN
> property, which takes the
following form:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    define [-file=&lt;filename&gt;] [-format=&lt;format&gt;] &lt;symbol&gt;</PRE
></TD
></TR
></TABLE
><P
>For example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    define FOPEN_MAX</PRE
></TD
></TR
></TABLE
><P
>This will result in something like:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define FOPEN_MAX 8
#define FOPEN_MAX_8</PRE
></TD
></TR
></TABLE
><P
>The specified symbol must be a valid C preprocessor symbol. Normally
the <TT
CLASS="LITERAL"
>#define</TT
> will end up in the same header file as
the default one, in other words <TT
CLASS="FILENAME"
>pkgconf/system.h</TT
> in the case of a
<TT
CLASS="LITERAL"
>cdl_package</TT
>, or the package's own header file for any other option.
The <TT
CLASS="LITERAL"
>-file</TT
> option can be used to change this. At
present the only legal value is <TT
CLASS="LITERAL"
>system.h</TT
>, for
example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    define -file=system.h &lt;symbol&gt;</PRE
></TD
></TR
></TABLE
><P
>This will cause the <TT
CLASS="LITERAL"
>#define</TT
> to end up in the global
configuration header rather than in the package's own header. Use of
this facility should be avoided since it is very rarely necessary to
make options globally visible.</P
><P
>The <SPAN
CLASS="PROPERTY"
>define</SPAN
> property takes another option,
<TT
CLASS="LITERAL"
>-format</TT
>, to provide a format string.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    define -format=%08x &lt;symbol&gt;</PRE
></TD
></TR
></TABLE
><P
>This should only be used for options with the <TT
CLASS="LITERAL"
>data</TT
>
or <TT
CLASS="LITERAL"
>booldata</TT
> flavor, and has the same effect as the
<SPAN
CLASS="PROPERTY"
>define_format</SPAN
> property has on the default
<TT
CLASS="LITERAL"
>#define</TT
>.</P
><P
><SPAN
CLASS="PROPERTY"
>define</SPAN
> properties are processed in the same way the default
<TT
CLASS="LITERAL"
>#define</TT
>. For options with the
<TT
CLASS="LITERAL"
>bool</TT
> or <TT
CLASS="LITERAL"
>none</TT
> flavors a single
<TT
CLASS="LITERAL"
>#define</TT
> will be generated using the value
<TT
CLASS="LITERAL"
>1</TT
>. For options with the <TT
CLASS="LITERAL"
>data</TT
> or
<TT
CLASS="LITERAL"
>booldata</TT
> flavors either one or two
<TT
CLASS="LITERAL"
>#define's</TT
> will be generated.</P
></LI
><LI
><P
>After processing all <SPAN
CLASS="PROPERTY"
>define</SPAN
> properties, the component framework will
look for any <SPAN
CLASS="PROPERTY"
>if_define</SPAN
> properties. These take the following form:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    if_define [-file=&lt;filename&gt;] &lt;symbol1&gt; &lt;symbol2&gt;</PRE
></TD
></TR
></TABLE
><P
>For example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    if_define CYGSRC_KERNEL CYGDBG_USE_ASSERTS</PRE
></TD
></TR
></TABLE
><P
>The following will be generated in the configuration header file:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#ifdef CYGSRC_KERNEL
# define CYGDBG_USE_ASSERTS
#endif</PRE
></TD
></TR
></TABLE
><P
>Typical kernel source code would begin with the following construct:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define CYGSRC_KERNEL 1
#include &lt;pkgconf/kernel.h&gt;
#include &lt;cyg/infra/cyg_ass.h&gt;</PRE
></TD
></TR
></TABLE
><P
>The infrastructure header file <TT
CLASS="FILENAME"
>cyg/infra/cyg_ass.h</TT
> only checks for symbols
such as <TT
CLASS="LITERAL"
>CYGDBG_USE_ASSERTS</TT
>, and has no special
knowledge of the kernel or any other package. The <SPAN
CLASS="PROPERTY"
>if_define</SPAN
> property
will only affect code that defines the symbol
<TT
CLASS="LITERAL"
>CYGSRC_KERNEL</TT
>, so typically only kernel source
code. If the option is enabled then assertion support will be enabled
for the kernel source code only. If the option is inactive or disabled
then kernel assertions will be disabled. Assertions in other packages
are not affected. Thus the <SPAN
CLASS="PROPERTY"
>if_define</SPAN
> property allows control over
assertions, tracing, and similar facilities at the level of individual
packages, or at finer levels such as components or even single source
files if desired.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>Current <SPAN
CLASS="APPLICATION"