build.sgml

ecos实时嵌入式操作系统

<para>
The next step is to generate a default <literal>#define</literal> for
the current option. If this option has a &no-define; property then the
default <literal>#define</literal> is suppressed, and processing
continues for &define;, &if-define; and &define-proc; properties.
</para>
<orderedlist>
<listitem>
<para>
The header file appropriate for the default <literal>#define</literal>
is determined. For a &cdl-package; this will be <filename
class="headerfile">pkgconf/system.h</filename>, for any other option this
will be the package's own header file. The intention here is that
packages and application code can always determine which packages are
in the configuration by <literal>#include'ing</literal> <filename
class="headerfile">pkgconf/system.h</filename>. The C preprocessor lacks
any facilities for including a header file only if it exists, and
taking appropriate action otherwise.
</para>
</listitem>
<listitem>
<para>
For options with the flavors <literal>bool</literal> or
<literal>none</literal>, a single <literal>#define</literal> will be
generated. This takes the form:
</para>
<programlisting width=72>
#define &lt;option&gt; 1
</programlisting>
<para>
For example:
</para>
<programlisting width=72>
#define CYGFUN_LIBC_TIME_POSIX 1
</programlisting>
<para>
Package source code can check whether or not an option is active and
enabled by using the <literal>#ifdef</literal>,
<literal>#ifndef</literal> or <literal>#if
defined(&hellip;)</literal>directives.
</para>
</listitem>
<listitem>
<para>
For options with the flavors <literal>data</literal> or
<literal>booldata</literal>, either one or two
<literal>#define's</literal> will be generated. The first of these may
be affected by a &define-format; property. If this property is not
defined then the first <literal>#define</literal> will take the form:
</para>
<programlisting width=72>
#define &lt;option&gt; &lt;value&gt;
</programlisting>
<para>
For example:
</para>
<programlisting width=72>
#define CYGNUM_LIBC_ATEXIT_HANDLERS 32
</programlisting>
<para>
Package source code can examine this value using the
<literal>#if</literal> directive, or by using the symbol in
code such as:
</para>
<programlisting width=72>
    for (i = 0; i < CYGNUM_LIBC_ATEXIT_HANDLERS; i++) {
        &hellip;
    }
</programlisting>
<para>
It must be noted that the <literal>#define</literal> will be generated
only if the corresponding option is both active and enabled. Options
with the <literal>data</literal> 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
<literal>#ifdef</literal> or similar directives will be necessary.
</para>
</listitem>
<listitem>
<para>
If there is a &define-format; property then this controls how the
option's value will appear in the header file. Given a format string
such as <literal>%08x</literal> and a value 42, the component
framework will execute the &Tcl; command
<literal>format&nbsp;%08x&nbsp;42</literal> and the result will be
used for the <literal>#define's</literal> value. It is the
responsibility of the component writer to make sure that this &Tcl;
command will be valid given the format string and the legal values for
the option.
</para>
</listitem>
<listitem>
<para>
In addition a second <literal>#define</literal> may or may not be
generated. This will take the form:
</para>
<programlisting width=72>
#define &lt;option&gt;_&lt;value&gt;
</programlisting>
<para>
For example:
</para>
<programlisting width=72>
#define CYGNUM_LIBC_ATEXIT_HANDLERS_32
</programlisting>
<para>
The <literal>#define</literal> will be generated only if it would
result in a valid C preprocessor symbol. If the value is a string such
as <literal>"/dev/ser0"</literal> then the <literal>#define</literal>
would be suppressed. This second <literal>#define</literal> is not
particularly useful for numerical data, but can be valuable in other
circumstances. For example if the legal values for an option
<literal>XXX_COLOR</literal> are <literal>red</literal>,
<literal>green</literal> and <literal>blue</literal> then code like
the following can be used:
</para>
<programlisting width=72>
#ifdef XXX_COLOR_red
    &hellip;
#endif
#ifdef XXX_COLOR_green
    &hellip;
#endif
#ifdef XXX_COLOR_blue
    &hellip;
#endif
</programlisting>
<para>
The expression syntax provided by the C preprocessor is limited to
numerical data and cannot perform string comparisons. By generating
two <literal>#define's</literal> 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
<literal>XXX_COLOR_green</literal> then there will be confusion. Since
such a configuration option violates the naming conventions, the
problem is unlikely to arise in practice.
</para>
</listitem>
</orderedlist>
</listitem>

<listitem>
<para>
For some options it may be useful to generate one or more additional
<literal>#define's</literal> or, in conjunction with the &no-define;
property, to define a symbol with a name different from the option's
name. This can be achieved with the &define; property, which takes the
following form:
</para>
<programlisting width=72>
    define [-file=&lt;filename&gt;] [-format=&lt;format&gt;] &lt;symbol&gt;
</programlisting>
<para>
For example:
</para>
<programlisting width=72>
    define FOPEN_MAX
</programlisting>
<para>
This will result in something like:
</para>
<programlisting width=72>
#define FOPEN_MAX 8
#define FOPEN_MAX_8
</programlisting>
<para>
The specified symbol must be a valid C preprocessor symbol. Normally
the <literal>#define</literal> will end up in the same header file as
the default one, in other words <filename
class="headerfile">pkgconf/system.h</filename> in the case of a
&cdl-package;, or the package's own header file for any other option.
The <literal>-file</literal> option can be used to change this. At
present the only legal value is <literal>system.h</literal>, for
example:
</para>
<programlisting width=72>
    define -file=system.h &lt;symbol&gt;
</programlisting>
<para>
This will cause the <literal>#define</literal> 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.
</para>
<para>
The &define; property takes another option,
<literal>-format</literal>, to provide a format string.
</para>
<programlisting width=72>
    define -format=%08x &lt;symbol&gt;
</programlisting>
<para>
This should only be used for options with the <literal>data</literal>
or <literal>booldata</literal> flavor, and has the same effect as the
&define-format; property has on the default
<literal>#define</literal>.
</para>
<para>
&define; properties are processed in the same way the default
<literal>#define</literal>. For options with the
<literal>bool</literal> or <literal>none</literal> flavors a single
<literal>#define</literal> will be generated using the value
<literal>1</literal>. For options with the <literal>data</literal> or
<literal>booldata</literal> flavors either one or two
<literal>#define's</literal> will be generated.
</para>
</listitem>

<listitem>
<para>
After processing all &define; properties, the component framework will
look for any &if-define; properties. These take the following form:
</para>
<programlisting width=72>
    if_define [-file=&lt;filename&gt;] &lt;symbol1&gt; &lt;symbol2&gt;
</programlisting>
<para>
For example:
</para>
<programlisting width=72>
    if_define CYGSRC_KERNEL CYGDBG_USE_ASSERTS
</programlisting>
<para>
The following will be generated in the configuration header file:
</para>
<programlisting width=72>
#ifdef CYGSRC_KERNEL
# define CYGDBG_USE_ASSERTS
#endif
</programlisting>
<para>
Typical kernel source code would begin with the following construct:
</para>
<programlisting width=72>
#define CYGSRC_KERNEL 1
#include &lt;pkgconf/kernel.h&gt;
#include &lt;cyg/infra/cyg_ass.h&gt;
</programlisting>
<para>
The infrastructure header file <filename
class="headerfile">cyg/infra/cyg_ass.h</filename> only checks for symbols
such as <literal>CYGDBG_USE_ASSERTS</literal>, and has no special
knowledge of the kernel or any other package. The &if-define; property
will only affect code that defines the symbol
<literal>CYGSRC_KERNEL</literal>, 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 &if-define; 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.
</para>
<note>
<para>
Current &eCos; packages do not yet make use of this facility. Instead
there is a single global configuration option
<varname>CYGDBG_USE_ASSERTS</varname> which is used to enable or
disable assertions for all packages. This issue should be addressed in
a future release of the system.
</para>
</note>
<para>
As with the &define; property, the &if-define; property takes an
option <literal>-file</literal> with a single legal value
<literal>system.h</literal>. This allows the output to be redirected
to <filename class="headerfile">pkgconf/system.h</filename> if and when
necessary. 
</para>
</listitem>

<listitem>
<para>
The final property that is relevant to configuration header file
generation is &define-proc;. This takes a single argument, a &Tcl;
fragment that can add arbitrary data to the global header <filename
class="headerfile">pkgconf/system.h</filename> and to the package's own
header. When the &define-proc; script is invoked two variables will be
set up to allow access to these headers: <literal>cdl_header</literal>
will be a channel to the package's own header file, for example
<filename class="headerfile">pkgconf/kernel.h</filename>;
<literal>cdl_system_header</literal> will be a channel to <filename
class="headerfile">pkgconf/system.h</filename>. A typical &define-proc;
script will use the &Tcl; <literal>puts</literal> command to output
data to one of these channels, for example:
</para>
<programlisting width=72>
cdl_option &lt;name&gt; {
    &hellip;
    define_proc {
        puts $::cdl_header "#define XXX 1"
    }
}
</programlisting>
<note>
<para>
In the current implementation the use of &define-proc; is limited
because the &Tcl; script cannot access any of the configuration data.
Therefore the script is limited to writing constant data to the
configuration headers. This is a major limitation which will be
addressed in a future release of the component framework.
</para>
</note>

</listitem>

</orderedlist>

<note>
<para>
Generating C header files with <literal>#define's</literal> for the
configuration data suffices for existing packages written in some
combination of C, C++ and assembler. It can also be used in
conjunction with some other languages, for example by first passing
the source code through the C preprocessor and feeding the result into
the appropriate compiler. In future versions of the component
framework additional programming languages such as Java may be
supported, and the configuration data may also be written to files in
some format other than C preprocessor directives. 
</para>
</note>

<note>