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 >Option Naming Convention</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 CDL Language"
23 HREF="language.html"><LINK
25 TITLE="CDL Properties"
26 HREF="language.properties.html"><LINK
28 TITLE="An Introduction to Tcl"
29 HREF="language.tcl.html"></HEAD
40 SUMMARY="Header navigation table"
52 > Component Writer's Guide</TH
60 HREF="language.properties.html"
68 >Chapter 3. The CDL Language</TD
74 HREF="language.tcl.html"
88 NAME="LANGUAGE.NAMING">Option Naming Convention</H1
90 >All the options in a given configuration live in the same namespace.
91 Furthermore it is not possible for two separate options to have the
92 same name, because this would make any references to those options in
96 > expressions ambiguous. A naming convention exists to avoid
97 problems. It is recommended that component writers observe some or all
98 of this convention to reduce the probability of name clashes with
101 >There is an important restriction on option names. Typically the
102 component framework will output a <TT
106 active and enabled option, using the name as the symbol being defined.
107 This requires that all names are valid C preprocessor symbols, a
108 limitation that is enforced even for options which have the
112 > property. Preprocessor symbols can be any sequence of
113 lower case letters <TT
127 underscore character <TT
137 >. The first character must be
138 a non-digit. Using an underscore as the first character is
139 discouraged, because that may clash with reserved language
140 identifiers. In addition there is a convention that preprocessor
141 symbols only use upper case letters, and some component writers may
142 wish to follow this convention.</P
144 >A typical option name could be something like
147 >CYGSEM_KERNEL_SCHED_BITMAP</TT
148 >. This name consists of
149 several different parts:</P
156 >The first few characters, in this case the three letters
160 >, are used to identify the organization that
161 produced the package. For historical reasons packages produced by Red
162 Hat tend to use the prefix <TT
169 >. Component writers should use their own
170 prefix: even when cutting and pasting from an existing <SPAN
174 the prefix should be changed to something appropriate to their
177 >It can be argued that a short prefix, often limited to upper case
178 letters, is not sufficiently long to eliminate the possibility of
179 name clashes. A longer prefix could be used, for example one based on
180 internet domain names. However the C preprocessor has no concept of
184 > directives, so it would always
185 be necessary to use the full option name in component source code
186 which gets tedious - option names tend to be long enough as it is.
187 There is a small increased risk of name clashes, but this risk is felt
192 >The next three characters indicate the nature of the option, for
193 example whether it affects the interface or just the implementation. A
194 list of common tags is given below.</P
201 > part indicates the location of the
202 option within the overall hierarchy. In this case the option is part of
203 the scheduling component of the kernel package. Having the hierarchy
204 details as part of the option name can help in understanding
205 configurable code and further reduces the probability of a name clash.</P
212 >, identifies the option
217 >The three-character tag is intended to provide some additional
218 information about the nature of the option. There are a number of
219 pre-defined tags. However for many options there is a choice:
220 options related to the platform should normally use
224 >, but numerical options should normally use
228 >; a platform-related numerical option such as
229 the size of an interrupt stack could therefore use either tag.
230 There are no absolute rules, and it is left to component writers to
231 interpret the following guidelines:</P
247 > tag is intended for options related
248 to the processor architecture. Typically such options will only occur
249 in architectural or variant HAL packages.</P
261 > tag is intended for options related to
262 the specific target board. Typically such options will only occur in
263 platform HAL packages.</P
272 >This tag is intended for packages or components, in other words
273 options which extend the configuration hierarchy. Arguably a
277 > tag would be more appropriate for
278 components, but this could be confusing because of the considerable
279 number of computing terms that begin with com.</P
288 >This is intended for global configuration options, especially
301 > tag indicates that the option is in
302 some way related to debugging, for example it may enable assertions in
303 some part of the system.</P
312 >This tag is for testing-related options. Typically these do not
313 affect actual application code, instead they control the interaction
314 between target-side test cases and a host-side testing infrastructure.</P
323 >This is for configuration options which affect the interface of a
324 package. There are a number of related tag which are also
325 interface-related. <TT
328 > is intended primarily
329 for options that control whether or not one or more functions are
330 provided by the package, but can also be used if none of the other
331 interface-related tags is applicable.</P
340 >This is analogous to <TT
343 > but controls the presence
344 or absence of one or more variables or objects.</P
356 > tag is intended only for packages that
357 provide an object-oriented interface, and controls the presence or
358 absence of an entire class.</P
367 >This is also for object-orientated interfaces, and indicates the
368 presence or absence of a member function rather than an entire class.</P
380 > option does not affect the interface (or if
381 does affect the interface, this is incidental). Instead it is used for
382 options which have a fundamental effect on the semantic behavior of a
383 package. For example the choice of kernel schedulers is semantic in
384 nature: it does not affect the interface, in particular the function
387 >cyg_thread_create</TT
388 > exists irrespective of which
389 scheduler has been selected. However it does have a major impact on
390 the system's behavior.</P
402 > is for implementation options. These do not
403 affect either the interface or the semantic behavior (with the
404 possible exception of timing-related changes). A typical
405 implementation option controls whether or not a particular function or
406 set of functions should get inlined.</P
415 >This tag is for numerical options, for example the number of
416 scheduling priority levels.</P
425 >This is for data items that are not numerical in nature, for example a
438 > tag indicates an option that affects
439 the build process, for example compiler flag settings.</P
448 >This should normally be used for <SPAN
451 > interfaces, which is a language
452 construct that is largely independent from the interface exported by a
453 package via its header files. For more details of <SPAN
458 HREF="language.interface.html"
459 >the Section called <I
471 >This tag is not normally used for configuration options. Instead
475 > scripts to pass additional private information to
476 the source code via the configuration header files, typically inside a
489 >This tag is not normally used for configuration options. Instead
490 it can be used by package source code to interact with such options,
491 especially in the context of the <SPAN
499 >There is one special case of a potential name clash that is worth
500 mentioning here. When the component framework generates a
501 configuration header file for a given package, by default it will use
502 a name derived from the package name (the <SPAN
506 be used to override this). The file name is constructed from the
507 package name by removing everything up to and including the first
508 underscore, converting the remainder of the name to lower case, and
512 > suffix. For example the kernel
516 > will involve a header file
519 >pkgconf/kernel.h</TT
521 configuration contained some other package
525 > then this would attempt to use the
526 same configuration header file, with unfortunate effects. Case
527 sensitivity could introduce problems as well, so a package
531 > would involve the same problem. Even
532 if the header file names preserved the case of the package name, not
533 all file systems are case sensitive. There is no simple solution to
534 this problem. Changing the names of the generated configuration header
535 files would involve a major incompatible change to the interface, to
536 solve a problem which is essentially hypothetical in nature.</P
543 SUMMARY="Footer navigation table"
554 HREF="language.properties.html"
563 HREF="cdl-guide.html"
572 HREF="language.tcl.html"
596 >An Introduction to Tcl</TD
projects / karo-tx-redboot.git / blob