language.sgml

ecos实时嵌入式操作系统

suddenly becomes necessary to link with several libraries.
</para>
<para>
The &include-dir; and &include-files; properties relate to a package's
exported header files. By default a package's header files will be
exported to the <filename class="directory">install/include</filename>
directory. This is the desired behavior for some packages like the C
library, since headers like <filename
class="headerfile">stdio.h</filename> should exist at that level.
However if all header files were to end up in that directory then
there would be a significant risk of a name clash. Instead it is
better for packages to specify some sub-directory for their exported
header files, for example:
</para>
<programlisting width=72>
cdl_package CYGPKG_INFRA {
    display       "Infrastructure"
    include_dir   cyg/infra
    &hellip;
}
</programlisting>
<para>
The various header files exported by the infrastructure, for example
<filename class="headerfile">cyg_ass.h</filename> and <filename
class="headerfile">cyg_trac.h</filename> will now end up in the
<filename class="directory">install/include/cyg/infra</filename>
sub-directory, where a name clash is very unlikely.
</para>
<para>
For packages which follow the <link
linkend="package.hierarchy">directory layout conventions</link> the
component framework will assume that the package's
<filename class="directory">include</filename> sub-directory contains
all exported header files. If this is not the case, for example
because the package is sufficiently simple that the layout convention
is inappropriate, then the exported header files can be listed
explicitly in an &include-files; property.
</para>

</sect2>

<!-- }}} -->
<!-- {{{ Miscellaneous          -->

<sect2 id="language.properties.miscellaneous">
<title>Miscellaneous Properties</title>
<para>
The <link linkend="ref.hardware">&hardware;</link> property is
only relevant to packages. Some packages such as device drivers and
HAL packages are hardware-specific, and generally it makes no sense to
add such packages to a configuration unless the corresponding hardware
is present on your target system. Typically hardware package selection
happens automatically when you select your target. The &hardware;
property should be used to identify a hardware-specific package, and
does not take any arguments.
</para>
<programlisting width=72>
cdl_package CYGPKG_HAL_MIPS {
    display "MIPS architecture"
    parent        CYGPKG_HAL
    hardware
    include_dir   cyg/hal
    define_header hal_mips.h
    &hellip;
}
</programlisting>
<para>
At present the &hardware; property is largely ignored by the component
framework. This may change in future releases.
</para>
</sect2>

<!-- }}} -->

</sect1>

<!-- }}} -->
<!-- {{{ Naming conventions     -->

<sect1 id="language.naming">
<title>Option Naming Convention</title>
<para>
All the options in a given configuration live in the same namespace.
Furthermore it is not possible for two separate options to have the
same name, because this would make any references to those options in
&CDL; expressions ambiguous. A naming convention exists to avoid
problems. It is recommended that component writers observe some or all
of this convention to reduce the probability of name clashes with
other packages.
</para>
<para>
There is an important restriction on option names. Typically the
component framework will output a <literal>#define</literal> for every
active and enabled option, using the name as the symbol being defined.
This requires that all names are valid C preprocessor symbols, a
limitation that is enforced even for options which have the
&no-define; property. Preprocessor symbols can be any sequence of
lower case letters <literal>a</literal>-<literal>z</literal>, upper
case letters, <literal>A</literal>-<literal>Z</literal>, the
underscore character <literal>_</literal>, and the digits
<literal>0</literal>-<literal>9</literal>. The first character must be
a non-digit. Using an underscore as the first character is
discouraged, because that may clash with reserved language
identifiers. In addition there is a convention that preprocessor
symbols only use upper case letters, and some component writers may
wish to follow this convention.
</para>
<para>
A typical option name could be something like
<varname>CYGSEM_KERNEL_SCHED_BITMAP</varname>. This name consists of
several different parts:
</para>
<orderedlist>
<listitem>
<para>
The first few characters, in this case the three letters
<literal>CYG</literal>, are used to identify the organization that
produced the package. For historical reasons packages produced by Red
Hat tend to use the prefix <literal>CYG</literal> rather than
<literal>RHAT</literal>. Component writers should use their own
prefix: even when cutting and pasting from an existing &CDL; script
the prefix should be changed to something appropriate to their
organization. 
</para>
<para>
It can be argued that a short prefix, often limited to upper case
letters, is not sufficiently long to eliminate the possibility of
name clashes. A longer prefix could be used, for example one based on
internet domain names. However the C preprocessor has no concept of
namespaces or <literal>import</literal> directives, so it would always
be necessary to use the full option name in component source code
which gets tedious - option names tend to be long enough as it is.
There is a small increased risk of name clashes, but this risk is felt
to be acceptable.
</para>
</listitem>
<listitem>
<para>
The next three characters indicate the nature of the option, for
example whether it affects the interface or just the implementation. A
list of common tags is given below.
</para>
</listitem>
<listitem>
<para>
The <literal>KERNEL_SCHED</literal> part indicates the location of the
option within the overall hierarchy. In this case the option is part of
the scheduling component of the kernel package. Having the hierarchy
details as part of the option name can help in understanding
configurable code and further reduces the probability of a name clash.
</para>
</listitem>
<listitem>
<para>
The final part, <literal>BITMAP</literal>, identifies the option
itself. 
</para>
</listitem>
</orderedlist>
<para>
The three-character tag is intended to provide some additional
information about the nature of the option. There are a number of
pre-defined tags. However for many options there is a choice:
options related to the platform should normally use
<literal>HWR</literal>, but numerical options should normally use
<literal>NUM</literal>; a platform-related numerical option such as
the size of an interrupt stack could therefore use either tag.
There are no absolute rules, and it is left to component writers to
interpret the following guidelines:
</para>
<variablelist>
<varlistentry>
<term><literal>xxxARC_</literal></term>
<listitem><para>
The <literal>ARC</literal> tag is intended for options related
to the processor architecture. Typically such options will only occur
in architectural or variant HAL packages.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxHWR_</literal></term>
<listitem><para>
The <literal>HWR</literal> tag is intended for options related to
the specific target board. Typically such options will only occur in
platform HAL packages.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxPKG_</literal></term>
<listitem><para>
This tag is intended for packages or components, in other words
options which extend the configuration hierarchy. Arguably a
<literal>COM</literal> tag would be more appropriate for
components, but this could be confusing because of the considerable
number of computing terms that begin with com.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxGLO_</literal></term>
<listitem><para>
This is intended for global configuration options, especially
preferences.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxDBG_</literal></term>
<listitem><para>
The <literal>DBG</literal> tag indicates that the option is in
some way related to debugging, for example it may enable assertions in
some part of the system.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxTST_</literal></term>
<listitem><para>
This tag is for testing-related options. Typically these do not
affect actual application code, instead they control the interaction
between target-side test cases and a host-side testing infrastructure.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxFUN_</literal></term>
<listitem><para>
This is for configuration options which affect the interface of a
package. There are a number of related tag which are also
interface-related. <literal>xxxFUN_</literal> is intended primarily
for options that control whether or not one or more functions are
provided by the package, but can also be used if none of the other
interface-related tags is applicable.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxVAR_</literal></term>
<listitem><para>
This is analogous to <literal>FUN</literal> but controls the presence
or absence of one or more variables or objects.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxCLS_</literal></term>
<listitem><para>
The <literal>CLS</literal> tag is intended only for packages that
provide an object-oriented interface, and controls the presence or
absence of an entire class.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxMFN_</literal></term>
<listitem><para>
This is also for object-orientated interfaces, and indicates the
presence or absence of a member function rather than an entire class.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxSEM_</literal></term>
<listitem><para>
A <literal>SEM</literal> option does not affect the interface (or if
does affect the interface, this is incidental). Instead it is used for
options which have a fundamental effect on the semantic behavior of a
package. For example the choice of kernel schedulers is semantic in
nature: it does not affect the interface, in particular the function
<function>cyg_thread_create</function> exists irrespective of which
scheduler has been selected. However it does have a major impact on
the system's behavior.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxIMP_</literal></term>
<listitem><para>
<literal>IMP</literal> is for implementation options. These do not
affect either the interface or the semantic behavior (with the
possible exception of timing-related changes). A typical
implementation option controls whether or not a particular function or
set of functions should get inlined.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxNUM_</literal></term>
<listitem><para>
This tag is for numerical options, for example the number of
scheduling priority levels.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxDAT_</literal></term>
<listitem><para>
This is for data items that are not numerical in nature, for example a
device name.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxBLD_</literal></term>
<listitem><para>
The <literal>BLD</literal> tag indicates an option that affects
the build process, for example compiler flag settings.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxINT_</literal></term>
<listitem><para>
This should normally be used for &CDL; interfaces, which is a language
construct that is largely independent from the interface exported by a
package via its header files. For more details of &CDL; interfaces
see <xref linkend="language.interface">.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxPRI_</literal></term>
<listitem><para>
This tag is not normally used for configuration options. Instead
it is used by &CDL; scripts to pass additional private information to
the source code via the configuration header files, typically inside a
&define-proc; property.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>xxxSRC_</literal></term>
<listitem><para>
This tag is not normally used for configuration options. Instead
it can be used by package source code to interact with such options,
especially in the context of the &if-define; property.
</para></listitem>
</varlistentry>
</variablelist>

<para>
There is one special case of a potential name clash that is worth