><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_component CYGBLD_GLOBAL_OPTIONS {
    flavor  none
    parent  CYGPKG_NONE
    &#8230;

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

    cdl_option CYGBLD_GLOBAL_LDFLAGS {
        flavor  data
        default_value "-g -nostdlib -Wl,--gc-sections &#8230;"
        &#8230;
    }
}</PRE
></TD
></TR
></TABLE
><P
>The <TT
CLASS="VARNAME"
>CYGBLD_GLOBAL_OPTIONS</TT
> component serves to
collect together all global build-related options. It has the flavor
<TT
CLASS="LITERAL"
>none</TT
> 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
<TT
CLASS="FILENAME"
>ecos.ecc</TT
> save file.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>Currently the <SPAN
CLASS="PROPERTY"
>parent</SPAN
> property lists a parent of
<TT
CLASS="VARNAME"
>CYGPKG_NONE</TT
>, 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.</P
></BLOCKQUOTE
></DIV
><P
>The option <TT
CLASS="VARNAME"
>CYGBLD_GLOBAL_COMMAND_PREFIX</TT
> 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 <SPAN
CLASS="PROPERTY"
>default_value</SPAN
> expression could select
a different toolchain depending on some other option that is used to
control which particular processor.
<TT
CLASS="VARNAME"
>CYGBLD_GLOBAL_COMMAND_PREFIX</TT
> is modifiable rather
than calculated, so users can override this when necessary.</P
><P
>Given a command prefix such as <TT
CLASS="LITERAL"
>arm-elf</TT
>, all C
source files will be compiled with <TT
CLASS="LITERAL"
>arm-elf-gcc</TT
>, all
C++ sources will be built using <TT
CLASS="LITERAL"
>arm-elf-g++</TT
>,
and <TT
CLASS="LITERAL"
>arm-elf-ar</TT
> 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 <TT
CLASS="LITERAL"
>$(CC)</TT
> will be set to
<TT
CLASS="LITERAL"
>arm-elf-gcc</TT
>.</P
><P
>The next option, <TT
CLASS="VARNAME"
>CYGBLD_GLOBAL_CFLAGS</TT
>, is used to
provide the initial value of <TT
CLASS="LITERAL"
>$(CFLAGS)</TT
>. Some
compiler flags such as <TT
CLASS="LITERAL"
>-Wall</TT
> and
<TT
CLASS="LITERAL"
>-g</TT
> are likely to be used on all targets. Other
flags such as <TT
CLASS="LITERAL"
>-mcpu=arm7tdmi</TT
> will be
target-specific. Again this is a modifiable option, so the user can
switch from say <TT
CLASS="LITERAL"
>-O2</TT
> to <TT
CLASS="LITERAL"
>-Os</TT
> if
desired. The option <TT
CLASS="VARNAME"
>CYGBLD_GLOBAL_LDFLAGS</TT
> serves
the same purpose for <TT
CLASS="LITERAL"
>$(LDFLAGS)</TT
> 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.</P
><P
>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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_component CYGPKG_KERNEL_OPTIONS {
    display "Kernel build options"
    flavor  none
    &#8230;

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

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

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

    cdl_option CYGPKG_KERNEL_LDFLAGS_REMOVE {
        display "Suppressed linker flags"
        flavor  data
        default_value { "" }
        &#8230;
    }
}</PRE
></TD
></TR
></TABLE
><P
>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 <TT
CLASS="LITERAL"
>$(CFLAGS)</TT
> that is used for
the compilations and custom build steps in a given package is
determined as follows:</P
><P
></P
><OL
TYPE="1"
><LI
><P
>Start with the global settings from
<TT
CLASS="VARNAME"
>CYGBLD_GLOBAL_CFLAGS</TT
>, for example
<TT
CLASS="LITERAL"
>-g&nbsp;-O2</TT
>.</P
></LI
><LI
><P
>Remove any flags specified in the per-package
<TT
CLASS="LITERAL"
>CFLAGS_REMOVE</TT
> option, if any. For example
if <TT
CLASS="LITERAL"
>-O2</TT
> should be removed for this package then
<TT
CLASS="LITERAL"
>$(CFLAGS)</TT
> would now have a value of just
<TT
CLASS="LITERAL"
>-g</TT
>.</P
></LI
><LI
><P
>Then concatenate the flags specified by the per-package
<TT
CLASS="LITERAL"
>CFLAGS_ADD</TT
> option, if any. For example if
<TT
CLASS="LITERAL"
>-Os</TT
> should be added for the current package then
the final value of <TT
CLASS="LITERAL"
>$(CFLAGS)</TT
> will be
<TT
CLASS="LITERAL"
>-g&nbsp;-Os</TT
>.</P
></LI
></OL
><P
><TT
CLASS="LITERAL"
>$(LDFLAGS)</TT
> is determined in much the same way.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>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 <SPAN
CLASS="PROPERTY"
>make_object</SPAN
> property can be used to work
around the limitations.</P
><P
>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
<TT
CLASS="VARNAME"
>CYGPKG_LIBM_CFLAGS_ADD</TT
> and
<TT
CLASS="VARNAME"
>CYGPKG_LIBM_CFLAGS_REMOVE</TT
> <SPAN
CLASS="PROPERTY"
>default_value</SPAN
>
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 <SPAN
CLASS="PROPERTY"
>default_value</SPAN
> 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.</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>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.</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="BUILD.CUSTOM">Custom Build Steps</H2
><DIV
CLASS="CAUTION"
><P
></P
><TABLE
CLASS="CAUTION"
BORDER="1"
WIDTH="100%"
><TR
><TD
ALIGN="CENTER"
><B
>Caution</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
><P
>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
backwards compatibility.</P
></TD
></TR
></TABLE
></DIV
><P
>For most packages simply listing one or more source files in a
<SPAN
CLASS="PROPERTY"
>compile</SPAN
> property is sufficient. These files will get built using the
appropriate compiler and compiler flags and added to a library, which
then gets linked with application code. A package that can be built in
this way is likely to be more portable to different targets and build
environments, since it avoids build-time dependencies. However some
packages have special needs, and the component framework supports
custom build steps to allow for these needs. There are two properties
related to this, <SPAN
CLASS="PROPERTY"
>make</SPAN
> and <SPAN
CLASS="PROPERTY"
>make_object</SPAN
>, and both take the following
form:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    make {
        &lt;target_filepath&gt; : &lt;dependency_filepath&gt; &#8230;
            &lt;command&gt;
            ...
    }</PRE
></TD
></TR
></TABLE
><P
>Although this may look like makefile syntax, and although some build
environments will indeed involve generating makefiles and running
<SPAN
CLASS="APPLICATION"
>make</SPAN
>, this is not
guaranteed. It is possible for the component framework to be
integrated with some other build system, and custom build steps should
be written with that possibility in mind. Each custom build step
involves a target, some number of dependency files, and some number of
commands. If the target is not up to date with respect to one or more
of the dependencies then the commands need to be executed.</P
><P
></P
><OL
TYPE="a"
><LI
><P
>Only one target can be specified. For a <SPAN
CLASS="PROPERTY"
>make_object</SPAN
> property this
target must be an object file. For a <SPAN
CLASS="PROPERTY"
>make</SPAN
> property it can be any
file. In both cases it must refer to a physical file, the use of
phony targets is not supported. The target should not be an absolute
path name. If the generated file needs to end up in the install tree
then this can be achieved using a <TT
CLASS="LITERAL"
>&lt;PREFIX&gt;</TT
>
token, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    make {
        &lt;PREFIX&gt;/lib/mytarget : &#8230;
            ...
    }</PRE
></TD
></TR
></TABLE
><P
>When the build tree is generated and the custom build step is added to
the makefile (or whatever build system is used)
<TT
CLASS="LITERAL"
>&lt;PREFIX&gt;</TT
> will be replaced with the absolute
path to the install tree. </P
></LI
><LI
><P
>All the dependencies must also refer to physical files, not to phony
targets. These files may be in the source tree. The
<TT
CLASS="LITERAL"
>&lt;PACKAGE&gt;</TT
> token can be used to indicate this:
when the build tree is generated this token will be replaced with the
absolute path to the package's root directory in the component
repository, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    make_object {
        xyzzy.o : &lt;PACKAGE&gt;/src/xyzzy.c
            &#8230;</PRE
></TD
></TR
></TABLE
><P
>If the component repository was installed in <TT
CLASS="FILENAME"
>/usr/local/ecos</TT
> and this custom build
step existed in version 1_5 of the kernel,
<TT
CLASS="LITERAL"
>&lt;PACKAGE&gt;</TT
> would be replaced with
<TT
CLASS="FILENAME"
>/usr/local/ecos/packages/kernel/v1_5</TT
>.</P
><P
>Alternatively the dependencies may refer to files that are generated
during the build. These may be object files resulting from <SPAN
CLASS="PROPERTY"
>compile</SPAN
>
properties or other <SPAN
CLASS="PROPERTY"
>make_object</SPAN
> properties, or they may be other
files resulting from a <SPAN
CLASS="PROPERTY"
>make</SPAN
> property, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    compile plugh.c
    make_object {
        xyzzy.o : plugh.o
            &#8230;
    }</PRE
></TD
></TR
></TABLE
></LI
><LI
><P
>No other token or makefile variables may be used in the target or
dependency file names. Also conditionals such as
<TT
CLASS="LITERAL"
>ifneq</TT
> and similar makefile functionality must not
be used.</P
></LI
><LI
><P
> 
Similarly the list of commands must not use any makefile conditionals
or similar functionality. A number of tokens can be used to provide
access to target-specific or environmental data. Note that these
tokens look like makefile variables, unlike the 
<TT
CLASS="LITERAL"
>&lt;PREFIX&gt;</TT
> and
<TT
CLASS="LITERAL"
>&lt;PACKAGE&gt;</TT
> tokens mentioned earlier:</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN2784"><P
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><THEAD
><TR
><TH