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. -->
12 >Configuration Header File Generation</TITLE
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="The Build Process"
23 HREF="build.html"><LINK
25 TITLE="The Build Process"
26 HREF="build.html"><LINK
29 HREF="build.make.html"></HEAD
40 SUMMARY="Header navigation table"
52 > Component Writer's Guide</TH
68 >Chapter 4. The Build Process</TD
74 HREF="build.make.html"
88 NAME="BUILD.HEADERS">Configuration Header File Generation</H1
90 >Configuration options can affect a build in two main ways. First,
91 enabling a configuration option or other <SPAN
94 > entity can result in
95 various files being built and added to a library, thus providing
96 functionality to the application code. However this mechanism can only
97 operate at a rather coarse grain, at the level of entire source files.
98 Hence the component framework also generates configuration header
99 files containing mainly C preprocessor <TT
103 directives. Package source code can then <TT
107 the appropriate header files and use <TT
118 adapt accordingly. In this way configuration options can be used to
119 enable or disable entire functions within a source file or just a
120 single line, whichever is appropriate.</P
122 >The configuration header files end up in the <TT
125 > subdirectory of the
126 install tree. There will be one header file for the system as a whole,
129 >pkgconf/system.h</TT
131 be additional header files for each package, for example
134 >pkgconf/kernel.h</TT
136 are generated when creating or updating the build and install trees,
137 which needs to happen after every change to the configuration.</P
139 >The component framework processes each package in the configuration
140 one at a time. The exact order in which the packages are processed is
141 not defined, so the order in which <TT
145 end up in the global <TT
147 >pkgconf/system.h</TT
148 > header may vary. However
149 for any given configuration the order should remain consistent until
150 packages are added to or removed from the system. This avoids
151 unnecessary changes to the global header file and hence unnecessary
152 rebuilds of the packages and of application code because of header
153 file dependency handling.</P
155 >Within a given package the various components, options and interfaces
156 will be processed in the order in which they were defined in the
160 > scripts. Typically the data in the configuration
161 headers consists only of a sequence of <TT
165 the order in which these are generated is irrelevant, but some
166 properties such as <SPAN
169 > can be used to add arbitrary data to
170 a configuration header and hence there may be dependencies on the
171 order. It should be noted that re-parenting an option below some other
172 package has no effect on which header file will contain the
176 >: the preprocessor directives
177 will always end up in the header file for the package that defines the
178 option, or in the global configuration header.</P
180 >There are six properties which affect the process of generating header
183 HREF="ref.define-header.html"
190 HREF="ref.no-define.html"
197 HREF="ref.define-format.html"
204 HREF="ref.define.html"
211 HREF="ref.if-define.html"
218 HREF="ref.define-proc.html"
228 > property can only occur in the body of a
232 > command and specifies the name of the header file which
233 should contain the package's configuration data, for example:</P
241 CLASS="PROGRAMLISTING"
242 >cdl_package <some_package> {
244 define_header xyzzy.h
253 > property the component framework will
258 the package's configuration data. If a package does not have
262 > property then a suitable file name is constructed
263 from the package's name. This involves:</P
270 >All characters in the package name up to and including the first
271 underscore are removed. For example <TT
290 >Any upper case letters in the resulting string will be converted to
291 lower case, yielding e.g. <TT
305 > suffix is appended, yielding e.g.
316 >Because of the naming restrictions on configuration options, this
317 should result in a valid filename. There is a small possibility of a
318 file name class, for example <TT
325 > would both end up trying to use the
330 but the use of lower case letters for package names violates the
331 naming conventions. It is not legal to use the <SPAN
335 property to put the configuration data for several packages in a
336 single header file. The resulting behaviour is undefined.</P
338 >Once the name of the package's header file has been determined and the
339 file has been opened, the various components, options and interfaces
340 in the package will be processed starting with the package itself. The
341 following steps are involved:</P
348 >If the current option or other <SPAN
351 > entity is inactive or disabled,
352 the option is ignored for the purposes of header file generation.
356 > are only generated for options that are
357 both active and enabled.</P
361 >The next step is to generate a default <TT
365 the current option. If this option has a <SPAN
372 > is suppressed, and processing
389 >The header file appropriate for the default <TT
393 is determined. For a <TT
398 >pkgconf/system.h</TT
399 >, for any other option this
400 will be the package's own header file. The intention here is that
401 packages and application code can always determine which packages are
402 in the configuration by <TT
407 >pkgconf/system.h</TT
408 >. The C preprocessor lacks
409 any facilities for including a header file only if it exists, and
410 taking appropriate action otherwise.</P
414 >For options with the flavors <TT
425 generated. This takes the form:</P
433 CLASS="PROGRAMLISTING"
434 >#define <option> 1</PRE
447 CLASS="PROGRAMLISTING"
448 >#define CYGFUN_LIBC_TIME_POSIX 1</PRE
453 >Package source code can check whether or not an option is active and
454 enabled by using the <TT
469 >For options with the flavors <TT
480 > will be generated. The first of these may
481 be affected by a <SPAN
484 > property. If this property is not
485 defined then the first <TT
488 > will take the form:</P
496 CLASS="PROGRAMLISTING"
497 >#define <option> <value></PRE
510 CLASS="PROGRAMLISTING"
511 >#define CYGNUM_LIBC_ATEXIT_HANDLERS 32</PRE
516 >Package source code can examine this value using the
520 > directive, or by using the symbol in
529 CLASS="PROGRAMLISTING"
530 > for (i = 0; i < CYGNUM_LIBC_ATEXIT_HANDLERS; i++) {
537 >It must be noted that the <TT
541 only if the corresponding option is both active and enabled. Options
545 > flavor are always enabled but may not
546 be active. Code like the above should be written only if it is known
547 that the symbol will always be defined, for example if the
548 corresponding source file will only get built if the containing
549 component is active and enabled. Otherwise the use of additional
553 > or similar directives will be necessary.</P
560 > property then this controls how the
561 option's value will appear in the header file. Given a format string
565 > and a value 42, the component
566 framework will execute the <SPAN
572 >format %08x 42</TT
573 > and the result will be
578 responsibility of the component writer to make sure that this <SPAN
582 command will be valid given the format string and the legal values for
587 >In addition a second <TT
591 generated. This will take the form:</P
599 CLASS="PROGRAMLISTING"
600 >#define <option>_<value></PRE
613 CLASS="PROGRAMLISTING"
614 >#define CYGNUM_LIBC_ATEXIT_HANDLERS_32</PRE
622 > will be generated only if it would
623 result in a valid C preprocessor symbol. If the value is a string such
631 would be suppressed. This second <TT
635 particularly useful for numerical data, but can be valuable in other
636 circumstances. For example if the legal values for an option
651 the following can be used:</P
659 CLASS="PROGRAMLISTING"
660 >#ifdef XXX_COLOR_red
663 #ifdef XXX_COLOR_green
666 #ifdef XXX_COLOR_blue
673 >The expression syntax provided by the C preprocessor is limited to
674 numerical data and cannot perform string comparisons. By generating
678 > in this way it is possible to work
679 around this limitation of the C preprocessor. However some care has to
680 be taken: if a component writer also defined a configuration option
684 > then there will be confusion. Since
685 such a configuration option violates the naming conventions, the
686 problem is unlikely to arise in practice.</P
692 >For some options it may be useful to generate one or more additional
696 > or, in conjunction with the <SPAN
700 property, to define a symbol with a name different from the option's
701 name. This can be achieved with the <SPAN
704 > property, which takes the
713 CLASS="PROGRAMLISTING"
714 > define [-file=<filename>] [-format=<format>] <symbol></PRE
727 CLASS="PROGRAMLISTING"
728 > define FOPEN_MAX</PRE
733 >This will result in something like:</P
741 CLASS="PROGRAMLISTING"
743 #define FOPEN_MAX_8</PRE
748 >The specified symbol must be a valid C preprocessor symbol. Normally
752 > will end up in the same header file as
753 the default one, in other words <TT
755 >pkgconf/system.h</TT
760 >, or the package's own header file for any other option.
764 > option can be used to change this. At
765 present the only legal value is <TT
777 CLASS="PROGRAMLISTING"
778 > define -file=system.h <symbol></PRE
783 >This will cause the <TT
786 > to end up in the global
787 configuration header rather than in the package's own header. Use of
788 this facility should be avoided since it is very rarely necessary to
789 make options globally visible.</P
794 > property takes another option,
798 >, to provide a format string.</P
806 CLASS="PROGRAMLISTING"
807 > define -format=%08x <symbol></PRE
812 >This should only be used for options with the <TT
819 > flavor, and has the same effect as the
823 > property has on the default
832 > properties are processed in the same way the default
836 >. For options with the
847 > will be generated using the value
851 >. For options with the <TT
858 > flavors either one or two
862 > will be generated.</P
866 >After processing all <SPAN
869 > properties, the component framework will
873 > properties. These take the following form:</P
881 CLASS="PROGRAMLISTING"
882 > if_define [-file=<filename>] <symbol1> <symbol2></PRE
895 CLASS="PROGRAMLISTING"
896 > if_define CYGSRC_KERNEL CYGDBG_USE_ASSERTS</PRE
901 >The following will be generated in the configuration header file:</P
909 CLASS="PROGRAMLISTING"
910 >#ifdef CYGSRC_KERNEL
911 # define CYGDBG_USE_ASSERTS
917 >Typical kernel source code would begin with the following construct:</P
925 CLASS="PROGRAMLISTING"
926 >#define CYGSRC_KERNEL 1
927 #include <pkgconf/kernel.h>
928 #include <cyg/infra/cyg_ass.h></PRE
933 >The infrastructure header file <TT
935 >cyg/infra/cyg_ass.h</TT
936 > only checks for symbols
939 >CYGDBG_USE_ASSERTS</TT
940 >, and has no special
941 knowledge of the kernel or any other package. The <SPAN
945 will only affect code that defines the symbol
949 >, so typically only kernel source
950 code. If the option is enabled then assertion support will be enabled
951 for the kernel source code only. If the option is inactive or disabled
952 then kernel assertions will be disabled. Assertions in other packages
953 are not affected. Thus the <SPAN
956 > property allows control over
957 assertions, tracing, and similar facilities at the level of individual
958 packages, or at finer levels such as components or even single source
970 > packages do not yet make use of this facility. Instead
971 there is a single global configuration option
974 >CYGDBG_USE_ASSERTS</TT
975 > which is used to enable or
976 disable assertions for all packages. This issue should be addressed in
977 a future release of the system.</P
984 > property, the <SPAN
991 > with a single legal value
995 >. This allows the output to be redirected
998 >pkgconf/system.h</TT
1004 >The final property that is relevant to configuration header file
1008 >. This takes a single argument, a <SPAN
1012 fragment that can add arbitrary data to the global header <TT
1014 >pkgconf/system.h</TT
1015 > and to the package's own
1016 header. When the <SPAN
1019 > script is invoked two variables will be
1020 set up to allow access to these headers: <TT
1024 will be a channel to the package's own header file, for example
1027 >pkgconf/kernel.h</TT
1031 >cdl_system_header</TT
1032 > will be a channel to <TT
1034 >pkgconf/system.h</TT
1039 script will use the <SPAN
1046 data to one of these channels, for example:</P
1054 CLASS="PROGRAMLISTING"
1055 >cdl_option <name> {
1058 puts $::cdl_header "#define XXX 1"
1071 >In the current implementation the use of <SPAN
1078 > script cannot access any of the configuration data.
1079 Therefore the script is limited to writing constant data to the
1080 configuration headers. This is a major limitation which will be
1081 addressed in a future release of the component framework.</P
1093 >Generating C header files with <TT
1097 configuration data suffices for existing packages written in some
1098 combination of C, C++ and assembler. It can also be used in
1099 conjunction with some other languages, for example by first passing
1100 the source code through the C preprocessor and feeding the result into
1101 the appropriate compiler. In future versions of the component
1102 framework additional programming languages such as Java may be
1103 supported, and the configuration data may also be written to files in
1104 some format other than C preprocessor directives. </P
1114 >At present there is no way for application or package source code to
1115 get hold of all the configuration details related to the current
1116 hardware. Instead that information is spread over various different
1117 configuration headers for the HAL and device driver packages, with
1118 some of the information going into <TT
1120 >pkgconf/system.h</TT
1121 >. It is possible that in
1122 some future release of the system there will be another global
1123 configuration header file <TT
1125 >pkgconf/hardware.h</TT
1126 > which either contains the
1127 configuration details for the various hardware-specific packages or
1131 > all the hardware-specific
1132 configuration headers. The desirability and feasibility of such a
1133 scheme are still to be determined. To avoid future incompatibility
1134 problems as a result of any such changes, it is recommended that all
1135 hardware packages (in other packages containing the <SPAN
1139 property) use the <SPAN
1141 >define_header</SPAN
1142 > property to specify explicitly which
1143 configuration header should be generated.</P
1151 NAME="BUILD.HEADERS.SYSTEM.H">The <TT
1156 >Typically configuration header files are <TT
1160 only by the package's source code at build time, or by a package's
1161 exported header files if the interface provided by the package may be
1162 affected by a configuration option. There should be no need for
1163 application code to know the details of individual configuration
1164 options, instead the configuration should specifically meet the needs
1165 of the application.</P
1167 >There are always exceptions. Application code may want to adapt to
1168 configuration options, for example to do different things for ROM and
1169 RAM booting systems, or when it is necessary to support several
1170 different target boards. This is especially true if the code in question
1171 is really re-usable library code which has not been converted to an
1172 eCos package, and hence cannot use any CDL facilities.</P
1174 >A major problem here is determining which packages are in the
1175 configuration: attempting to <TT
1183 when it is not known for certain that that particular package is part
1184 of the configuration will result in compilation errors. The global
1187 >pkgconf/system.h</TT
1189 serves to provide such information, so application code can use
1190 techniques like the following:</P
1198 CLASS="PROGRAMLISTING"
1199 >#include <pkgconf/system.h>
1201 # include <pkgconf/net.h>
1207 >This will compile correctly irrespective of the eCos configuration,
1208 and subsequent code can use <TT
1216 configuration options in that package. </P
1218 >In addition to determining whether or not a package is present, the
1219 global configuration header file can also be used to find out the
1220 specific version of a package that is being used. This can be useful
1221 if a more recent version exports additional functionality. It may also
1222 be necessary to adapt to incompatible changes in the exported
1223 interface or to changes in behaviour. For each package the
1224 configuration system will typically <TT
1228 symbols, for example for a V1.3.1 release:</P
1236 CLASS="PROGRAMLISTING"
1237 >#define CYGNUM_NET_VERSION_MAJOR 1
1238 #define CYGNUM_NET_VERSION_MINOR 3
1239 #define CYGNUM_NET_VERSION_RELEASE 1</PRE
1244 >There are a number of problems associated with such version
1248 >. The first restriction is that the
1249 package must follow the standard naming conventions, so the package
1250 name must be of the form <TT
1254 characters immediately preceding the first underscore must be
1258 >, and will be replaced with
1262 > when generating the version
1266 >. If a package does not follow the naming
1267 convention then no version <TT
1273 >Assuming the package does follow the naming conventions, the
1274 configuration tools will always generate three version
1278 > for the major, minor, and release
1279 numbers. The symbol names are obtained from the package name by
1297 >_VERSION_RELEASE</TT
1298 >. It is assumed that the resulting
1299 symbols will not clash with any configuration option names. The values
1303 > are determined by searching the
1304 version string for sequences of digits, optionally preceded by a minus
1305 sign. It is possible that some or all of the numbers are absent in any
1306 given version string, in which case <TT
1313 >. For example, given a version string
1317 >, the major version number is
1321 >, the minor number is <TT
1325 the release number is <TT
1328 >. Given a version string of
1332 > all three numbers would be set to
1338 >There is special case code for the version <TT
1342 which typically corresponds to a development version obtained via
1343 anonymous CVS or similar means. The configuration system has special
1344 built-in knowledge of this version, and will assume it is more recent
1345 than any specific release number. The global configuration header
1346 defines a special symbol <TT
1348 >CYGNUM_VERSION_CURRENT</TT
1350 and this will be used as the major version number when version
1354 > of a package is used:</P
1362 CLASS="PROGRAMLISTING"
1363 >#define CYGNUM_VERSION_CURRENT 0x7fffff00
1365 #define CYGNUM_INFRA_VERSION_MAJOR CYGNUM_VERSION_CURRENT
1366 #define CYGNUM_INFRA_VERSION_MINOR -1
1367 #define CYGNUM_INFRA_VERSION_RELEASE -1</PRE
1372 >The large number used for <TT
1374 >CYGNUM_VERSION_CURRENT</TT
1376 should ensure that major version comparisons work as expected, while
1377 still allowing for a small amount of arithmetic in case that proves
1380 >It should be noted that this implementation of version
1384 > will not cope with all version number
1385 schemes. However for many cases it should suffice.</P
1393 SUMMARY="Footer navigation table"
1413 HREF="cdl-guide.html"
1422 HREF="build.make.html"
1432 >The Build Process</TD