language.sgml

ecos实时嵌入式操作系统

</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>flavor booldata</literal></term>
<listitem>
<para>
Both the boolean and the data part of the option are user-modifiable.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
For more details of &CDL; flavors and how a flavor affects expression
evaluation, and other consequences, see <xref
linkend="language.values">. The &flavor; property cannot be used for a
package because packages always have the <literal>booldata</literal>
flavor. Options and components have the <literal>bool</literal> flavor
by default, since most configuration choices are simple yes-or-no
choices. Interfaces have the <literal>data</literal> flavor by default.
</para>
<para>
The &calculated; property can be used for options which should not be
user-modifiable, but which instead are fixed by the target hardware or
determined from the current values of other options. In general
&calculated; options should be avoided, since they can be confusing to
users who need to figure out whether or not a particular option can
actually be changed. There are a number of valid uses for &calculated;
options, and quite a few invalid ones as well. The <link
linkend="ref.calculated">reference packages</link> should be consulted
for further details. The property takes an <link
linkend="language.expression">ordinary &CDL; expression</link> as
argument, for example:
</para>
<programlisting width=72>
# A constant on some target hardware, perhaps user-modifiable on other
# targets.
cdl_option CYGNUM_HAL_RTC_PERIOD {
    display       "Real-time clock period"
    flavor        data
    calculated    12500
}
</programlisting>
<para>
The &calculated; property cannot be used for packages or interfaces.
The value of a package always corresponds to the version of that
package which is loaded, and this is under user control. Interfaces
are implicitly calculated, based on the number of active and enabled
implementors.
</para>
<para>
The &default-value; property is similar to &calculated;, but only
specifies a default value which users can modify. Again this property
is not relevant to packages or interfaces. A typical example would be:
</para>
<programlisting width=72>
cdl_option CYGDBG_HAL_DEBUG_GDB_THREAD_SUPPORT {
    display       "Include GDB multi-threading debug support"
    requires      CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
    default_value CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
    &hellip;
}
</programlisting>
<para>
The &legal-values; property imposes a constraint on the possible
values of the data part of an option. Hence it is only applicable to
options with the <literal>data</literal> or
<literal>booldata</literal> flavors. It cannot be used for a package
since the only valid value for a package is its version number. The
arguments to the &legal-values; property should constitute a <link
linkend="language.list-expression">&CDL; list expression</link>.
</para>
<programlisting width=72>
cdl_option CYGNUM_LIBC_TIME_STD_DEFAULT_OFFSET {
    display       "Default Standard Time offset"
    flavor        data
    legal_values  -- -90000 to 90000
    default_value -- 0
    &hellip;
}
</programlisting>
<para>
The &active-if; property does not relate directly to an option's
value, but rather to its active state. Usually this is controlled via
the configuration hierarchy: if the
<varname>CYGPKG_LIBC_STDIO</varname> component is disabled then all
options below it are inactive and do not have any consequences.
In some cases the hierarchy does not provide sufficient control, for
example an option should only be active if two disjoint sets of
conditions are satisfied: the hierarchy could be used for one of these
conditions, and an additional &active-if; property could be used for
the other one. The arguments to &active-if; should constitute a
<link linkend="language.goal-expression">&CDL; goal expression</link>.
</para>
<programlisting width=72>
# Do not provide extra semaphore debugging if there are no semaphores
cdl_option CYGDBG_KERNEL_INSTRUMENT_BINSEM {
    active_if CYGPKG_KERNEL_SYNCH
    &hellip;
}
</programlisting>
<para>
The &implements; property is related to the concept of <link
linkend="language.interface">&CDL; interfaces</link>. If an option is
active and enabled and it implements a particular interface then it
contributes <literal>1</literal> to that interface's value.
</para>
<programlisting width=72>
cdl_package CYGPKG_NET_EDB7XXX_ETH_DRIVERS {
    display       "Cirrus Logic ethernet driver"
    implements    CYGHWR_NET_DRIVERS
    implements    CYGHWR_NET_DRIVER_ETH0
    &hellip;
}
</programlisting>
<para>
The &requires; property is used to impose constraints on the user's
choices. For example it is unreasonable to expect the C library to
provide thread-safe implementations of certain functions if the
underlying kernel support has been disabled, or even if the kernel is
not being used at all.
</para>
<programlisting width=72>
cdl_option CYGSEM_LIBC_PER_THREAD_ERRNO {
    display       "Per-thread errno"
    doc           ref/ecos-ref.15.html
    requires      CYGVAR_KERNEL_THREADS_DATA
    default_value 1
    &hellip;
}
</programlisting>
<para>
The arguments to the &requires; property should be a <link
linkend="language.goal-expression">&CDL; goal expression</link>.
</para>

</sect2>

<!-- }}} -->
<!-- {{{ Header file generation -->

<sect2 id="language.properties.define">
<title>Generating the Configuration Header Files</title>
<para>
When creating or updating a build tree the component framework will
also generate configuration header files, one per package. By default
it will generate a <literal>#define</literal> for each option,
component or interface that is active and enabled. For options with
the <literal>data</literal> or <literal>booldata</literal> flavors the
<literal>#define</literal> will use the option's data part, otherwise
it will use the constant <literal>1</literal>. Typical output would
include:
</para>
<programlisting width=72>
#define CYGFUN_LIBC_TIME_POSIX 1
#define CYGNUM_LIBC_TIME_DST_DEFAULT_STATE -1
</programlisting>
<para>
There are six properties which can be used to control the header file
generation process:
<link linkend="ref.define-header">&define-header;</link>,
<link linkend="ref.no-define">&no-define;</link>,
<link linkend="ref.define-format">&define-format;</link>,
<link linkend="ref.define">&define;</link>,
<link linkend="ref.if-define">&if-define;</link>, and
<link linkend="ref.define-proc">&define-proc;</link>.
</para>
<para>
By default the component framework will generate a configuration
header file for each package based on the package's name: everything
up to and including the first underscore is discarded, the rest of the
name is lower-cased, and a <literal>.h</literal> suffix is appended.
For example the configuration header file for the kernel package
<varname>CYGPKG_KERNEL</varname> is <filename
class="headerfile">pkgconf/kernel.h</filename>. The &define-header;
property can be used to specify an alternative filename. This applies
to all the components and options within a package, so it can only be
used in the body of a &cdl-package; command. For example the following
specifies that the configuration header file for the SPARClite HAL
package is <filename
class="headerfile">pkgconf/hal_sparclite.h</filename>.
</para>
<programlisting width=72>
cdl_package CYGPKG_HAL_SPARCLITE {
    display "SPARClite architecture"
    parent        CYGPKG_HAL
    hardware
    define_header hal_sparclite.h
    &hellip;
}
</programlisting>
<note>
<para>
At present the main use for the &define-header; property is related 
to hardware packages, see the <link linkend="ref.hardware">reference
pages</link> for more details.
</para>
</note>
<para>
The &no-define; property is used to suppress the generation of the
default <literal>#define</literal>. This can be useful if an option's
consequences are all related to the build process or to constraints,
and the option is never actually checked in any source code. It can
also be useful in conjunction with the &define;, &if-define; or
&define-proc; properties. The &no-define; property does not take any
arguments. 
</para>
<programlisting width=72>
cdl_component CYG_HAL_STARTUP {
    display       "Startup type"
    flavor        data
    legal_values  { "RAM" "ROM" }
    default_value {"RAM"}
    no_define
    define -file system.h CYG_HAL_STARTUP
    &hellip;
}
</programlisting>
<para>
This example also illustrates the &define; property, which can be used
to generate a <literal>#define</literal> in addition to the default
one. It takes a single argument, the name of the symbol to be defined.
It also takes options to control the configuration header file in
which the symbol should be defined and the format to be used.
</para>
<para>
The &define-format; property can be used to control how the value part
of the default <literal>#define</literal> gets formatted. For example
a format string of  <literal>"0x%04x"</literal> could be used to
generate a four-digit hexadecimal number. 
</para>
<para>
The &if-define; property is intended for use primarily to control
assertions, tracing, and similar functionality. It supports a specific
implementation model for these, allowing control at the grain of
packages or even individual source files. The <link
linkend="ref.if-define">reference pages</link> provide additional
information.
</para>
<para>
The &define-proc; property provides an escape mechanism for those
cases where something special has to happen at configuration header
file generation time. It takes a single argument, a fragment of &Tcl;
code, which gets executed when the header file is generated. This code
can output arbitrary data to the header file, or perform any other
actions that might be appropriate.
</para>

</sect2>

<!-- }}} -->
<!-- {{{ Builds                 -->

<sect2 id="language.properties.build">
<title>Controlling what gets Built</title>
<para>
There are six properties which affect the build process:
<link linkend="ref.compile">&compile;</link>,
<link linkend="ref.make">&make;</link>,
<link linkend="ref.make-object">&make-object;</link>,
<link linkend="ref.library">&library;</link>,
<link linkend="ref.include-dir">&include-dir;</link>, and
<link linkend="ref.include-files">&include-files;</link>.
The last three apply to a package as a whole, and can only occur in
the body of a &cdl-package; command.
</para>
<para>
Most of the source files that go into a package should simply be
compiled with the appropriate compiler, selected by the target
architecture, and with the appropriate flags, with an additional set
defined by the target hardware and possible modifications on a
per-package basis. The resulting object files will go into the library
<filename>libtarget.a</filename>, which can then be linked against
application code. The &compile; property is used to list these source
files: 
</para>
<programlisting width=72>
cdl_package CYGPKG_ERROR {
    display       "Common error code support"
    compile       strerror.cxx
    include_dir   cyg/error
    &hellip;
}
</programlisting>
<para>
The arguments to the &compile; property should be one or more source
files. Typically most of the sources will be needed for the package as
a whole, and hence they will be listed in one or more &compile;
properties in the body of the &cdl-package;. Some sources may be
specific to particular configuration options, in other words there is
no point in compiling them unless that option is enabled, in which
case the sources should be listed in a &compile; property in the
corresponding &cdl-option;, &cdl-component; or &cdl-interface; body.
</para>
<para>
Some packages may have more complicated build requirements, for
example they may involve a special target such as a linker script
which should not end up in the usual library, or they may involve
special build steps for generating an object file. The &make; and
&make-object; properties provide support for such requirements, for
example:
</para>
<programlisting>
cdl_package CYGPKG_HAL_MN10300_AM33 {
    display       "MN10300 AM33 variant"
    &hellip;
    make {
        &lt;PREFIX&gt;/lib/target.ld: &lt;PACKAGE&gt;/src/mn10300_am33.ld
        $(CC) -E -P -Wp,-MD,target.tmp -DEXTRAS=1 -xc $(INCLUDE_PATH) \
            $(CFLAGS) -o $@ $&lt;
        @echo $@ ": \\" &gt; $(notdir $@).deps
        @tail +2 target.tmp &gt;&gt; $(notdir $@).deps
        @echo &gt;&gt; $(notdir $@).deps
        @rm target.tmp
    }
}
</programlisting>
<para>
For full details of custom build steps and the build process
generally, see <xref linkend="build">.
</para>
<para>
By default all object files go into the library
<filename>libtarget.a</filename>. It is possible to override this at
the package level using the &library; property, but this should be
avoided since it complicates application development: instead of just
linking with a single library for all &eCos;-related packages, it