build.sgml

ecos实时嵌入式操作系统

    make_object -library=libSomePackage.a {
        …
    }
</programlisting>
<para>
Again this should be avoided because it makes application development
more difficult. There is one special library which can be used freely,
<filename>libextras.a</filename>, which is used to generate the
<filename>extras.o</filename> file as described below.
</para>
<para>
The order in which object files end up in a library is not defined.
Typically each library will be created directly in the install tree,
since there is little point in generating a file in the build tree and
then immediately copying it to the install tree.
</para>

</sect2>

<!-- }}} -->
<!-- {{{ extras.o               -->

<sect2 id="build.extras">
<title>The <filename>extras.o</filename> file</title>

<para>
Package sources files normally get compiled and then added to a
library, by default <filename>libtarget.a</filename>, which is then
linked with the application code. Because of the usual rules for
linking with libraries, augmented by the use of link-time garbage
collection, this means that code will only end up in the final
executable if there is a direct or indirect reference to it in the
application. Usually this is the desired behaviour: if the application
does not make any use of say kernel message boxes, directly or
indirectly, then that code should not end up in the final executable
taking up valuable memory space.
</para>
<para>
In a few cases it is desirable for package code to end up in the final
executable even if there are no direct or indirect references. For
example, device driver functions are often not called directly.
Instead the application will access the device via the string
<literal>"/dev/xyzzy"</literal> and call the device functions
indirectly. This will be impossible if the functions have been
removed at link-time.
</para>
<para>
Another example involves static C++ objects. It is possible to have a
static C++ object, preferably with a suitable constructor priority,
where all of the interesting work happens as a side effect of running
the constructor. For example a package might include a monitoring
thread or a garbage collection thread created from inside such a
constructor. Without a reference by the application to the static
object the latter will never get linked in, and the package will not
function as expected.
</para>
<para>
A third example would be copyright messages. A package vendor may want
to insist that all products shipped using that package include a
particular message in memory, even though many users of that package
will object to such a restriction.
</para>
<para>
To meet requirements such as these the build system provides support
for a file <filename>extras.o</filename>, which always gets linked
with the application code via the linker script. Because it is an
object file rather than a library everything in the file will be
linked in. The <filename>extras.o</filename> file is generated at the
end of a build from a library <filename>libextras.a</filename>, so
packages can put functions and variables in suitable source files and
add them to that library explicitly:
</para>
<programlisting width=72>
    compile -library=libextras.a xyzzy.c
    compile xyzzy_support.c
</programlisting>
<para>
In this example <filename>xyzzy.o</filename> will end up in
<filename>libextras.a</filename>, and hence in
<filename>extras.o</filename> and in the final executable.
<filename>xyzzy_support.o</filename> will end up in
<filename>libtarget.a</filename> as usual, and is subject to linker
garbage collection.
</para>

</sect2>

<!-- }}} -->
<!-- {{{ Compilers and flags    -->

<sect2 id="build.flags">
<title>Compilers and Flags</title>

<caution>
<para>
Some of the details of compiler selection and compiler flags described
below are subject to change in future revisions of the component
framework, although every reasonable attempt will be made to avoid
breaking backwards compatibility.
</para>
</caution>

<para>
The build system needs to know what compiler to use, what compiler
flags should be used for different stages of the build and so on. Much
of this information will vary from target to target, although users
should be able to override this when appropriate. There may also be a
need for some packages to modify the compiler flags. All platform HAL
packages should define a number of options with well-known names,
along the following lines (any existing platform HAL package can be
consulted for a complete example):
</para>
<programlisting width=72>
cdl_component CYGBLD_GLOBAL_OPTIONS {
    flavor  none
    parent  CYGPKG_NONE
    &hellip;

    cdl_option CYGBLD_GLOBAL_COMMAND_PREFIX {
        flavor  data
        default_value { "arm-elf" }
        &hellip;
    }
    cdl_option CYGBLD_GLOBAL_CFLAGS {
        flavor  data
        default_value "-Wall -g -O2 &hellip;"
        &hellip;
    }

    cdl_option CYGBLD_GLOBAL_LDFLAGS {
        flavor  data
        default_value "-g -nostdlib -Wl,--gc-sections &hellip;"
        &hellip;
    }
}
</programlisting>
<para>
The <varname>CYGBLD_GLOBAL_OPTIONS</varname> component serves to
collect together all global build-related options. It has the flavor
<literal>none</literal> since disabling all of these options would
make it impossible to build anything and hence is not useful. It is
parented immediately below the root of the configuration hierarchy,
thus making sure that it is readily accessible in the graphical
configuration tool and, for command line users, in the
<filename>ecos.ecc</filename> save file.
</para>
<note>
<para>
Currently the &parent; property lists a parent of
<varname>CYGPKG_NONE</varname>, rather than an empty string. This
could be unfortunate if there was ever a package with that name. The
issue will be addressed in a future release of the component
framework.
</para>
</note>
<para>
The option <varname>CYGBLD_GLOBAL_COMMAND_PREFIX</varname> defines
which tools should be used for the current target. Typically this is
determined by the processor on the target hardware. In some cases a
given target board may be able to support several different
processors, in which case the &default-value; expression could select
a different toolchain depending on some other option that is used to
control which particular processor.
<varname>CYGBLD_GLOBAL_COMMAND_PREFIX</varname> is modifiable rather
than calculated, so users can override this when necessary.
</para>
<para>
Given a command prefix such as <literal>arm-elf</literal>, all C
source files will be compiled with <literal>arm-elf-gcc</literal>, all
C++ sources will be built using <literal>arm-elf-g++</literal>,
and <literal>arm-elf-ar</literal> will be used to generate the
library. This is in accordance with the usual naming conventions for
GNU cross-compilers and similar tools. For the purposes of custom
build steps, tokens such as <literal>$(CC)</literal> will be set to
<literal>arm-elf-gcc</literal>.
</para>
<para>
The next option, <varname>CYGBLD_GLOBAL_CFLAGS</varname>, is used to
provide the initial value of <literal>$(CFLAGS)</literal>. Some
compiler flags such as <literal>-Wall</literal> and
<literal>-g</literal> are likely to be used on all targets. Other
flags such as <literal>-mcpu=arm7tdmi</literal> will be
target-specific. Again this is a modifiable option, so the user can
switch from say <literal>-O2</literal> to <literal>-Os</literal> if
desired. The option <varname>CYGBLD_GLOBAL_LDFLAGS</varname> serves
the same purpose for <literal>$(LDFLAGS)</literal> and linking. It is
used primarily when building test cases or possibly for some custom
build steps, since building eCos itself generally involves building
one or more libraries rather than executables.
</para>
<para>
Some packages may wish to add certain flags to the global set, or
possibly remove some flags. This can be achieved by having
appropriately named options in the package, for example:
</para>
<programlisting width=72>
cdl_component CYGPKG_KERNEL_OPTIONS {
    display "Kernel build options"
    flavor  none
    &hellip;

    cdl_option CYGPKG_KERNEL_CFLAGS_ADD {
        display "Additional compiler flags"
        flavor  data
        default_value { "" }
        &hellip;
    }

    cdl_option CYGPKG_KERNEL_CFLAGS_REMOVE {
        display "Suppressed compiler flags"
        flavor  data
        default_value { "" }
        &hellip;
    }

    cdl_option CYGPKG_KERNEL_LDFLAGS_ADD {
        display "Additional linker flags"
        flavor  data
        default_value { "" }
        &hellip;
    }

    cdl_option CYGPKG_KERNEL_LDFLAGS_REMOVE {
        display "Suppressed linker flags"
        flavor  data
        default_value { "" }
        &hellip;
    }
}
</programlisting>
<para>
In this example the kernel does not modify the global compiler flags
by default, but it is possible for the users to modify the options if
desired. The value of <literal>$(CFLAGS)</literal> that is used for
the compilations and custom build steps in a given package is
determined as follows:
</para>
<orderedlist>
<listitem>
<para>
Start with the global settings from
<varname>CYGBLD_GLOBAL_CFLAGS</varname>, for example
<literal>-g&nbsp;-O2</literal>.
</para>
</listitem>
<listitem>
<para>
Remove any flags specified in the per-package
<literal>CFLAGS_REMOVE</literal> option, if any. For example
if <literal>-O2</literal> should be removed for this package then
<literal>$(CFLAGS)</literal> would now have a value of just
<literal>-g</literal>.
</para>
</listitem>
<listitem>
<para>
Then concatenate the flags specified by the per-package
<literal>CFLAGS_ADD</literal> option, if any. For example if
<literal>-Os</literal> should be added for the current package then
the final value of <literal>$(CFLAGS)</literal> will be
<literal>-g&nbsp;-Os</literal>.
</para>
</listitem>
</orderedlist>
<para>
<literal>$(LDFLAGS)</literal> is determined in much the same way.
</para>

<note>
<para>
The way compiler flags are handled at present has numerous limitations
that need to be addressed in a future release, although it should
suffice for nearly all cases. For the time being custom build steps
and in particular the &make-object; property can be used to work
around the limitations.
</para>
<para>
Amongst the issues, there is a specific problem with package
encapsulation. For example the math library imposes some stringent
requirements on the compiler in order to guarantee exact IEEE
behavior, and may need special flags on a per-architecture basis. One
way of handling this is to have
<varname>CYGPKG_LIBM_CFLAGS_ADD</varname> and
<varname>CYGPKG_LIBM_CFLAGS_REMOVE</varname> &default-value;
expressions which depend on the target architecture, but such
expressions may have to updated for each new architecture. An
alternative approach would allow the architectural HAL package to
modify the &default-value; expressions for the math library, but this
breaks encapsulation. A third approach would allow some architectural
HAL packages to define one or more special options with well-known
names, and the math library could check if these options were defined
and adjust the default values appropriately. Other packages with
floating point requirements could do the same. This approach also has
scalability issues, in particular how many such categories of options
would be needed? It is not yet clear how best to resolve such issues.
</para>
</note>

<note>
<para>
When generating a build tree it would be desirable for the component
framework to output details of the tools and compiler flags in a
format that can be re-used for application builds, for example a
makefile fragment. This would make it easier for application
developers to use the same set of flags as were used for building eCos
itself, thus avoiding some potential problems with incompatible
compiler flags.
</para>
</note>

</sect2>

<!-- }}} -->
<!-- {{{ Custom build steps     -->

<sect2 id="build.custom">
<title>Custom Build Steps</title>

<caution>
<para>
Some of the details of custom build steps as described below are
subject to change in future revisions of the component framework,
although every reasonable attempt will be made to avoid breaking