?? build.headers.html
字號:
<!-- Copyright (C) 2003 Red Hat, Inc. -->
<!-- This material may be distributed only subject to the terms -->
<!-- and conditions set forth in the Open Publication License, v1.0 -->
<!-- or later (the latest version is presently available at -->
<!-- http://www.opencontent.org/openpub/). -->
<!-- Distribution of the work or derivative of the work in any -->
<!-- standard (paper) book form is prohibited unless prior -->
<!-- permission is obtained from the copyright holder. -->
<HTML
><HEAD
><TITLE
>Configuration Header File Generation</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="The eCos Component Writer's Guide"
HREF="cdl-guide.html"><LINK
REL="UP"
TITLE="The Build Process"
HREF="build.html"><LINK
REL="PREVIOUS"
TITLE="The Build Process"
HREF="build.html"><LINK
REL="NEXT"
TITLE="Building eCos"
HREF="build.make.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>The <SPAN
CLASS="APPLICATION"
>eCos</SPAN
> Component Writer's Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="build.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 4. The Build Process</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="build.make.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="BUILD.HEADERS">Configuration Header File Generation</H1
><P
>Configuration options can affect a build in two main ways. First,
enabling a configuration option or other <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> entity can result in
various files being built and added to a library, thus providing
functionality to the application code. However this mechanism can only
operate at a rather coarse grain, at the level of entire source files.
Hence the component framework also generates configuration header
files containing mainly C preprocessor <TT
CLASS="LITERAL"
>#define</TT
>
directives. Package source code can then <TT
CLASS="LITERAL"
>#include</TT
>
the appropriate header files and use <TT
CLASS="LITERAL"
>#if</TT
>,
<TT
CLASS="LITERAL"
>#ifdef</TT
> and <TT
CLASS="LITERAL"
>#ifndef</TT
> directives to
adapt accordingly. In this way configuration options can be used to
enable or disable entire functions within a source file or just a
single line, whichever is appropriate.</P
><P
>The configuration header files end up in the <TT
CLASS="FILENAME"
>include/pkgconf</TT
> subdirectory of the
install tree. There will be one header file for the system as a whole,
<TT
CLASS="FILENAME"
>pkgconf/system.h</TT
>, and there will
be additional header files for each package, for example
<TT
CLASS="FILENAME"
>pkgconf/kernel.h</TT
>. The header files
are generated when creating or updating the build and install trees,
which needs to happen after every change to the configuration.</P
><P
>The component framework processes each package in the configuration
one at a time. The exact order in which the packages are processed is
not defined, so the order in which <TT
CLASS="LITERAL"
>#define's</TT
> will
end up in the global <TT
CLASS="FILENAME"
>pkgconf/system.h</TT
> header may vary. However
for any given configuration the order should remain consistent until
packages are added to or removed from the system. This avoids
unnecessary changes to the global header file and hence unnecessary
rebuilds of the packages and of application code because of header
file dependency handling.</P
><P
>Within a given package the various components, options and interfaces
will be processed in the order in which they were defined in the
corresponding <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> scripts. Typically the data in the configuration
headers consists only of a sequence of <TT
CLASS="LITERAL"
>#define's</TT
> so
the order in which these are generated is irrelevant, but some
properties such as <SPAN
CLASS="PROPERTY"
>define_proc</SPAN
> can be used to add arbitrary data to
a configuration header and hence there may be dependencies on the
order. It should be noted that re-parenting an option below some other
package has no effect on which header file will contain the
corresponding <TT
CLASS="LITERAL"
>#define</TT
>: the preprocessor directives
will always end up in the header file for the package that defines the
option, or in the global configuration header.</P
><P
>There are six properties which affect the process of generating header
files:
<A
HREF="ref.define-header.html"
><SPAN
CLASS="PROPERTY"
>define_header</SPAN
></A
>,
<A
HREF="ref.no-define.html"
><SPAN
CLASS="PROPERTY"
>no_define</SPAN
></A
>,
<A
HREF="ref.define-format.html"
><SPAN
CLASS="PROPERTY"
>define_format</SPAN
></A
>,
<A
HREF="ref.define.html"
><SPAN
CLASS="PROPERTY"
>define</SPAN
></A
>,
<A
HREF="ref.if-define.html"
><SPAN
CLASS="PROPERTY"
>if_define</SPAN
></A
>, and
<A
HREF="ref.define-proc.html"
><SPAN
CLASS="PROPERTY"
>define_proc</SPAN
></A
>.</P
><P
>The <SPAN
CLASS="PROPERTY"
>define_header</SPAN
> property can only occur in the body of a
<TT
CLASS="LITERAL"
>cdl_package</TT
> command and specifies the name of the header file which
should contain the package's configuration data, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_package <some_package> {
…
define_header xyzzy.h
}</PRE
></TD
></TR
></TABLE
><P
>Given such a <SPAN
CLASS="PROPERTY"
>define_header</SPAN
> property the component framework will
use the file <TT
CLASS="FILENAME"
>pkgconf/xyzzy.h</TT
> for
the package's configuration data. If a package does not have
a <SPAN
CLASS="PROPERTY"
>define_header</SPAN
> property then a suitable file name is constructed
from the package's name. This involves:</P
><P
></P
><OL
TYPE="1"
><LI
><P
>All characters in the package name up to and including the first
underscore are removed. For example <TT
CLASS="VARNAME"
>CYGPKG_KERNEL</TT
>
is converted to <TT
CLASS="LITERAL"
>KERNEL</TT
>, and
<TT
CLASS="VARNAME"
>CYGPKG_HAL_ARM</TT
> is converted to
<TT
CLASS="LITERAL"
>HAL_ARM</TT
>.</P
></LI
><LI
><P
>Any upper case letters in the resulting string will be converted to
lower case, yielding e.g. <TT
CLASS="LITERAL"
>kernel</TT
> and
<TT
CLASS="LITERAL"
>hal_arm</TT
>.</P
></LI
><LI
><P
>A <TT
CLASS="LITERAL"
>.h</TT
> suffix is appended, yielding e.g.
<TT
CLASS="LITERAL"
>kernel.h</TT
> and <TT
CLASS="LITERAL"
>hal_arm.h</TT
>.</P
></LI
></OL
><P
>Because of the naming restrictions on configuration options, this
should result in a valid filename. There is a small possibility of a
file name class, for example <TT
CLASS="VARNAME"
>CYGPKG_PLUGH</TT
> and
<TT
CLASS="VARNAME"
>CYGPKG_plugh</TT
> would both end up trying to use the
same header file <TT
CLASS="FILENAME"
>pkgconf/plugh.h</TT
>,
but the use of lower case letters for package names violates the
naming conventions. It is not legal to use the <SPAN
CLASS="PROPERTY"
>define_header</SPAN
>
property to put the configuration data for several packages in a
single header file. The resulting behaviour is undefined.</P
><P
>Once the name of the package's header file has been determined and the
file has been opened, the various components, options and interfaces
in the package will be processed starting with the package itself. The
following steps are involved:</P
><P
></P
><OL
TYPE="1"
><LI
><P
>If the current option or other <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> entity is inactive or disabled,
the option is ignored for the purposes of header file generation.
<TT
CLASS="LITERAL"
>#define's</TT
> are only generated for options that are
both active and enabled.</P
></LI
><LI
><P
>The next step is to generate a default <TT
CLASS="LITERAL"
>#define</TT
> for
the current option. If this option has a <SPAN
CLASS="PROPERTY"
>no_define</SPAN
> property then the
default <TT
CLASS="LITERAL"
>#define</TT
> is suppressed, and processing
continues for <SPAN
CLASS="PROPERTY"
>define</SPAN
>, <SPAN
CLASS="PROPERTY"
>if_define</SPAN
> and <SPAN
CLASS="PROPERTY"
>define_proc</SPAN
> properties.</P
><P
></P
><OL
TYPE="a"
><LI
><P
>The header file appropriate for the default <TT
CLASS="LITERAL"
>#define</TT
>
is determined. For a <TT
CLASS="LITERAL"
>cdl_package</TT
> this will be <TT
CLASS="FILENAME"
>pkgconf/system.h</TT
>, 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 <TT
CLASS="LITERAL"
>#include'ing</TT
> <TT
CLASS="FILENAME"
>pkgconf/system.h</TT
>. The C preprocessor lacks
any facilities for including a header file only if it exists, and
taking appropriate action otherwise.</P
></LI
><LI
><P
>For options with the flavors <TT
CLASS="LITERAL"
>bool</TT
> or
<TT
CLASS="LITERAL"
>none</TT
>, a single <TT
CLASS="LITERAL"
>#define</TT
> will be
generated. This takes the form:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define <option> 1</PRE
></TD
></TR
></TABLE
><P
>For example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define CYGFUN_LIBC_TIME_POSIX 1</PRE
></TD
></TR
></TABLE
><P
>Package source code can check whether or not an option is active and
enabled by using the <TT
CLASS="LITERAL"
>#ifdef</TT
>,
<TT
CLASS="LITERAL"
>#ifndef</TT
> or <TT
CLASS="LITERAL"
>#if
defined(…)</TT
>directives.</P
></LI
><LI
><P
>For options with the flavors <TT
CLASS="LITERAL"
>data</TT
> or
<TT
CLASS="LITERAL"
>booldata</TT
>, either one or two
<TT
CLASS="LITERAL"
>#define's</TT
> will be generated. The first of these may
be affected by a <SPAN
CLASS="PROPERTY"
>define_format</SPAN
> property. If this property is not
?? 快捷鍵說明
復制代碼
Ctrl + C
搜索代碼
Ctrl + F
全屏模式
F11
切換主題
Ctrl + Shift + D
顯示快捷鍵
?
增大字號
Ctrl + =
減小字號
Ctrl + -