<!-- Copyright (C) 2003 Red Hat, Inc. -->
|
<!-- Copyright (C) 2003 Red Hat, Inc. -->
|
<!-- This material may be distributed only subject to the terms -->
|
<!-- This material may be distributed only subject to the terms -->
|
<!-- and conditions set forth in the Open Publication License, v1.0 -->
|
<!-- and conditions set forth in the Open Publication License, v1.0 -->
|
<!-- or later (the latest version is presently available at -->
|
<!-- or later (the latest version is presently available at -->
|
<!-- http://www.opencontent.org/openpub/). -->
|
<!-- http://www.opencontent.org/openpub/). -->
|
<!-- Distribution of the work or derivative of the work in any -->
|
<!-- Distribution of the work or derivative of the work in any -->
|
<!-- standard (paper) book form is prohibited unless prior -->
|
<!-- standard (paper) book form is prohibited unless prior -->
|
<!-- permission is obtained from the copyright holder. -->
|
<!-- permission is obtained from the copyright holder. -->
|
<HTML
|
<HTML
|
><HEAD
|
><HEAD
|
><TITLE
|
><TITLE
|
>Package Contents and Layout</TITLE
|
>Package Contents and Layout</TITLE
|
><meta name="MSSmartTagsPreventParsing" content="TRUE">
|
><meta name="MSSmartTagsPreventParsing" content="TRUE">
|
<META
|
<META
|
NAME="GENERATOR"
|
NAME="GENERATOR"
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
|
"><LINK
|
"><LINK
|
REL="HOME"
|
REL="HOME"
|
TITLE="The eCos Component Writer's Guide"
|
TITLE="The eCos Component Writer's Guide"
|
HREF="cdl-guide.html"><LINK
|
HREF="cdl-guide.html"><LINK
|
REL="UP"
|
REL="UP"
|
TITLE="Package Organization"
|
TITLE="Package Organization"
|
HREF="package.html"><LINK
|
HREF="package.html"><LINK
|
REL="PREVIOUS"
|
REL="PREVIOUS"
|
TITLE="Package Versioning"
|
TITLE="Package Versioning"
|
HREF="package.versions.html"><LINK
|
HREF="package.versions.html"><LINK
|
REL="NEXT"
|
REL="NEXT"
|
TITLE="Making a Package Distribution"
|
TITLE="Making a Package Distribution"
|
HREF="package.distrib.html"></HEAD
|
HREF="package.distrib.html"></HEAD
|
><BODY
|
><BODY
|
CLASS="SECT1"
|
CLASS="SECT1"
|
BGCOLOR="#FFFFFF"
|
BGCOLOR="#FFFFFF"
|
TEXT="#000000"
|
TEXT="#000000"
|
LINK="#0000FF"
|
LINK="#0000FF"
|
VLINK="#840084"
|
VLINK="#840084"
|
ALINK="#0000FF"
|
ALINK="#0000FF"
|
><DIV
|
><DIV
|
CLASS="NAVHEADER"
|
CLASS="NAVHEADER"
|
><TABLE
|
><TABLE
|
SUMMARY="Header navigation table"
|
SUMMARY="Header navigation table"
|
WIDTH="100%"
|
WIDTH="100%"
|
BORDER="0"
|
BORDER="0"
|
CELLPADDING="0"
|
CELLPADDING="0"
|
CELLSPACING="0"
|
CELLSPACING="0"
|
><TR
|
><TR
|
><TH
|
><TH
|
COLSPAN="3"
|
COLSPAN="3"
|
ALIGN="center"
|
ALIGN="center"
|
>The <SPAN
|
>The <SPAN
|
CLASS="APPLICATION"
|
CLASS="APPLICATION"
|
>eCos</SPAN
|
>eCos</SPAN
|
> Component Writer's Guide</TH
|
> Component Writer's Guide</TH
|
></TR
|
></TR
|
><TR
|
><TR
|
><TD
|
><TD
|
WIDTH="10%"
|
WIDTH="10%"
|
ALIGN="left"
|
ALIGN="left"
|
VALIGN="bottom"
|
VALIGN="bottom"
|
><A
|
><A
|
HREF="package.versions.html"
|
HREF="package.versions.html"
|
ACCESSKEY="P"
|
ACCESSKEY="P"
|
>Prev</A
|
>Prev</A
|
></TD
|
></TD
|
><TD
|
><TD
|
WIDTH="80%"
|
WIDTH="80%"
|
ALIGN="center"
|
ALIGN="center"
|
VALIGN="bottom"
|
VALIGN="bottom"
|
>Chapter 2. Package Organization</TD
|
>Chapter 2. Package Organization</TD
|
><TD
|
><TD
|
WIDTH="10%"
|
WIDTH="10%"
|
ALIGN="right"
|
ALIGN="right"
|
VALIGN="bottom"
|
VALIGN="bottom"
|
><A
|
><A
|
HREF="package.distrib.html"
|
HREF="package.distrib.html"
|
ACCESSKEY="N"
|
ACCESSKEY="N"
|
>Next</A
|
>Next</A
|
></TD
|
></TD
|
></TR
|
></TR
|
></TABLE
|
></TABLE
|
><HR
|
><HR
|
ALIGN="LEFT"
|
ALIGN="LEFT"
|
WIDTH="100%"></DIV
|
WIDTH="100%"></DIV
|
><DIV
|
><DIV
|
CLASS="SECT1"
|
CLASS="SECT1"
|
><H1
|
><H1
|
CLASS="SECT1"
|
CLASS="SECT1"
|
><A
|
><A
|
NAME="PACKAGE.CONTENTS">Package Contents and Layout</H1
|
NAME="PACKAGE.CONTENTS">Package Contents and Layout</H1
|
><P
|
><P
|
>A typical package contains the following:</P
|
>A typical package contains the following:</P
|
><P
|
><P
|
></P
|
></P
|
><OL
|
><OL
|
TYPE="1"
|
TYPE="1"
|
><LI
|
><LI
|
><P
|
><P
|
>Some number of source files which will end up in a library. The
|
>Some number of source files which will end up in a library. The
|
application code will be linked with this library to produce an
|
application code will be linked with this library to produce an
|
executable. Some source files may serve other purposes, for example to
|
executable. Some source files may serve other purposes, for example to
|
provide a linker script.</P
|
provide a linker script.</P
|
></LI
|
></LI
|
><LI
|
><LI
|
><P
|
><P
|
>Exported header files which define the interface provided by the
|
>Exported header files which define the interface provided by the
|
package. </P
|
package. </P
|
></LI
|
></LI
|
><LI
|
><LI
|
><P
|
><P
|
>On-line documentation, for example reference pages for each exported
|
>On-line documentation, for example reference pages for each exported
|
function. </P
|
function. </P
|
></LI
|
></LI
|
><LI
|
><LI
|
><P
|
><P
|
>Some number of test cases, shipped in source format, allowing users to
|
>Some number of test cases, shipped in source format, allowing users to
|
check that the package is working as expected on their particular
|
check that the package is working as expected on their particular
|
hardware and in their specific configuration.</P
|
hardware and in their specific configuration.</P
|
></LI
|
></LI
|
><LI
|
><LI
|
><P
|
><P
|
>One or more <SPAN
|
>One or more <SPAN
|
CLASS="APPLICATION"
|
CLASS="APPLICATION"
|
>CDL</SPAN
|
>CDL</SPAN
|
> scripts describing the package to the configuration
|
> scripts describing the package to the configuration
|
system.</P
|
system.</P
|
></LI
|
></LI
|
></OL
|
></OL
|
><P
|
><P
|
>It is also conventional to have a per-package
|
>It is also conventional to have a per-package
|
<TT
|
<TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>ChangeLog</TT
|
>ChangeLog</TT
|
> file used to keep track of changes to
|
> file used to keep track of changes to
|
that package. This is especially valuable to end users of the package
|
that package. This is especially valuable to end users of the package
|
who may not have convenient access to the source code control system
|
who may not have convenient access to the source code control system
|
used to manage the master copy of the package, and hence cannot find
|
used to manage the master copy of the package, and hence cannot find
|
out easily what has changed. Often it can be very useful to the main
|
out easily what has changed. Often it can be very useful to the main
|
developers as well.</P
|
developers as well.</P
|
><P
|
><P
|
>Any given packages need not contain all of these. It is compulsory to
|
>Any given packages need not contain all of these. It is compulsory to
|
have at least one <SPAN
|
have at least one <SPAN
|
CLASS="APPLICATION"
|
CLASS="APPLICATION"
|
>CDL</SPAN
|
>CDL</SPAN
|
> script describing the package, otherwise the
|
> script describing the package, otherwise the
|
component framework would be unable to process it. Some packages may
|
component framework would be unable to process it. Some packages may
|
not have any source code: it is possible to have a package that merely
|
not have any source code: it is possible to have a package that merely
|
defines a common interface which can then be implemented by several
|
defines a common interface which can then be implemented by several
|
other packages, especially in the context of device drivers; however
|
other packages, especially in the context of device drivers; however
|
it is still common to have some code in such packages to avoid
|
it is still common to have some code in such packages to avoid
|
replicating shareable code in all of the implementation packages.
|
replicating shareable code in all of the implementation packages.
|
Similarly it is possible to have a package with no exported header
|
Similarly it is possible to have a package with no exported header
|
files, just source code that implements an existing interface: for
|
files, just source code that implements an existing interface: for
|
example an ethernet device driver might just implement a standard
|
example an ethernet device driver might just implement a standard
|
interface and not provide any additional functionality. Packages do
|
interface and not provide any additional functionality. Packages do
|
not need to come with any on-line documentation, although this may
|
not need to come with any on-line documentation, although this may
|
affect how many people will want to use the package. Much the same
|
affect how many people will want to use the package. Much the same
|
applies to per-package test cases.</P
|
applies to per-package test cases.</P
|
><P
|
><P
|
>The component framework has a recommended per-package directory layout
|
>The component framework has a recommended per-package directory layout
|
which splits the package contents on a functional basis:</P
|
which splits the package contents on a functional basis:</P
|
><DIV
|
><DIV
|
CLASS="INFORMALFIGURE"
|
CLASS="INFORMALFIGURE"
|
><A
|
><A
|
NAME="AEN302"><P
|
NAME="AEN302"><P
|
></P
|
></P
|
><DIV
|
><DIV
|
CLASS="MEDIAOBJECT"
|
CLASS="MEDIAOBJECT"
|
><P
|
><P
|
><IMG
|
><IMG
|
SRC="package.png"
|
SRC="package.png"
|
ALIGN="CENTER"></P
|
ALIGN="CENTER"></P
|
></DIV
|
></DIV
|
><P
|
><P
|
></P
|
></P
|
></DIV
|
></DIV
|
><P
|
><P
|
>For example, if a package has an <TT
|
>For example, if a package has an <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>include</TT
|
>include</TT
|
> sub-directory then the component
|
> sub-directory then the component
|
framework will assume that all header files in and below that
|
framework will assume that all header files in and below that
|
directory are exported header files and will do the right thing at
|
directory are exported header files and will do the right thing at
|
build time. Similarly if there is <SPAN
|
build time. Similarly if there is <SPAN
|
CLASS="PROPERTY"
|
CLASS="PROPERTY"
|
>doc</SPAN
|
>doc</SPAN
|
> property indicating the
|
> property indicating the
|
location of on-line documentation then the component framework will
|
location of on-line documentation then the component framework will
|
first look in the <TT
|
first look in the <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>doc</TT
|
>doc</TT
|
>
|
>
|
sub-directory.</P
|
sub-directory.</P
|
><P
|
><P
|
>This directory layout is just a guideline, it is not enforced by the
|
>This directory layout is just a guideline, it is not enforced by the
|
component framework. For simple packages it often makes more sense to
|
component framework. For simple packages it often makes more sense to
|
have all of the files in just one directory. For example a package
|
have all of the files in just one directory. For example a package
|
could just contain the files <TT
|
could just contain the files <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>hello.cxx</TT
|
>hello.cxx</TT
|
>,
|
>,
|
<TT
|
<TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>hello.h</TT
|
>hello.h</TT
|
>, <TT
|
>, <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>hello.html</TT
|
>hello.html</TT
|
> and
|
> and
|
<TT
|
<TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>hello.cdl</TT
|
>hello.cdl</TT
|
>. By default
|
>. By default
|
<TT
|
<TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>hello.h</TT
|
>hello.h</TT
|
> will be treated as an exported header
|
> will be treated as an exported header
|
file, although this can be overridden with the <A
|
file, although this can be overridden with the <A
|
HREF="ref.include-files.html"
|
HREF="ref.include-files.html"
|
><SPAN
|
><SPAN
|
CLASS="PROPERTY"
|
CLASS="PROPERTY"
|
>include_files</SPAN
|
>include_files</SPAN
|
></A
|
></A
|
> property. Assuming
|
> property. Assuming
|
there is a <SPAN
|
there is a <SPAN
|
CLASS="PROPERTY"
|
CLASS="PROPERTY"
|
>doc</SPAN
|
>doc</SPAN
|
> property referring to <TT
|
> property referring to <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>hello.html</TT
|
>hello.html</TT
|
>
|
>
|
and there is no <TT
|
and there is no <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>doc</TT
|
>doc</TT
|
>
|
>
|
sub-directory then the tools will search for this file relative to the
|
sub-directory then the tools will search for this file relative to the
|
package's top-level and everything will just work. Much the same
|
package's top-level and everything will just work. Much the same
|
applies to <TT
|
applies to <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>hello.cxx</TT
|
>hello.cxx</TT
|
> and
|
> and
|
<TT
|
<TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>hello.cdl</TT
|
>hello.cdl</TT
|
>. </P
|
>. </P
|
><DIV
|
><DIV
|
CLASS="TIP"
|
CLASS="TIP"
|
><BLOCKQUOTE
|
><BLOCKQUOTE
|
CLASS="TIP"
|
CLASS="TIP"
|
><P
|
><P
|
><B
|
><B
|
>Tip: </B
|
>Tip: </B
|
>Older versions of the <SPAN
|
>Older versions of the <SPAN
|
CLASS="APPLICATION"
|
CLASS="APPLICATION"
|
>eCos</SPAN
|
>eCos</SPAN
|
> build system only supported packages that
|
> build system only supported packages that
|
followed the directory structure exactly. Hence certain core packages
|
followed the directory structure exactly. Hence certain core packages
|
such as <TT
|
such as <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>error</TT
|
>error</TT
|
> implement the full directory
|
> implement the full directory
|
structure, even though that is a particularly simple package and the
|
structure, even though that is a particularly simple package and the
|
full directory structure is inappropriate. Component writers can
|
full directory structure is inappropriate. Component writers can
|
decide for themselves whether or not the directory structure
|
decide for themselves whether or not the directory structure
|
guidelines are appropriate for their package.</P
|
guidelines are appropriate for their package.</P
|
></BLOCKQUOTE
|
></BLOCKQUOTE
|
></DIV
|
></DIV
|
><DIV
|
><DIV
|
CLASS="SECT2"
|
CLASS="SECT2"
|
><H2
|
><H2
|
CLASS="SECT2"
|
CLASS="SECT2"
|
><A
|
><A
|
NAME="PACKAGE.BUILD">Outline of the Build Process</H2
|
NAME="PACKAGE.BUILD">Outline of the Build Process</H2
|
><P
|
><P
|
>The full build process is described in <A
|
>The full build process is described in <A
|
HREF="build.html"
|
HREF="build.html"
|
>Chapter 4</A
|
>Chapter 4</A
|
>, but
|
>, but
|
a summary is appropriate here. A build involves three directory
|
a summary is appropriate here. A build involves three directory
|
structures: </P
|
structures: </P
|
><P
|
><P
|
></P
|
></P
|
><OL
|
><OL
|
TYPE="1"
|
TYPE="1"
|
><LI
|
><LI
|
><P
|
><P
|
>The component repository. This is where all the package source code is
|
>The component repository. This is where all the package source code is
|
held, along with <SPAN
|
held, along with <SPAN
|
CLASS="APPLICATION"
|
CLASS="APPLICATION"
|
>CDL</SPAN
|
>CDL</SPAN
|
> scripts, documentation, and so on. For build
|
> scripts, documentation, and so on. For build
|
purposes a component repository is read-only. Application developers
|
purposes a component repository is read-only. Application developers
|
will only modify the component repository when installing or removing
|
will only modify the component repository when installing or removing
|
packages, via the administration tool. Component writers will
|
packages, via the administration tool. Component writers will
|
typically work on just one package in the component repository.</P
|
typically work on just one package in the component repository.</P
|
></LI
|
></LI
|
><LI
|
><LI
|
><P
|
><P
|
>The build tree. Each configuration has its own build tree, which can
|
>The build tree. Each configuration has its own build tree, which can
|
be regenerated at any time using the configuration's
|
be regenerated at any time using the configuration's
|
<TT
|
<TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>ecos.ecc</TT
|
>ecos.ecc</TT
|
> savefile. The build tree contains only
|
> savefile. The build tree contains only
|
intermediate files, primarily object files. Once a build is complete
|
intermediate files, primarily object files. Once a build is complete
|
the build tree contains no information that is useful for application
|
the build tree contains no information that is useful for application
|
development and can be wiped, although this would slow down any
|
development and can be wiped, although this would slow down any
|
rebuilds following changes to the configuration.</P
|
rebuilds following changes to the configuration.</P
|
></LI
|
></LI
|
><LI
|
><LI
|
><P
|
><P
|
>The install tree. This is populated during a build, and contains all
|
>The install tree. This is populated during a build, and contains all
|
the files relevant to application development. There will be a
|
the files relevant to application development. There will be a
|
<TT
|
<TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>lib</TT
|
>lib</TT
|
> sub-directory which
|
> sub-directory which
|
typically contains <TT
|
typically contains <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>libtarget.a</TT
|
>libtarget.a</TT
|
>, a linker script,
|
>, a linker script,
|
start-up code, and so on. There will also be an <TT
|
start-up code, and so on. There will also be an <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>include</TT
|
>include</TT
|
> sub-directory containing all the
|
> sub-directory containing all the
|
header files exported by the various packages. There will also be a
|
header files exported by the various packages. There will also be a
|
<TT
|
<TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>include/pkgconf</TT
|
>include/pkgconf</TT
|
> sub-directory
|
> sub-directory
|
containing various configuration header files with
|
containing various configuration header files with
|
<TT
|
<TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#define's</TT
|
>#define's</TT
|
> for the options. Typically the install
|
> for the options. Typically the install
|
tree is created within the build tree, but this is not a requirement.</P
|
tree is created within the build tree, but this is not a requirement.</P
|
></LI
|
></LI
|
></OL
|
></OL
|
><P
|
><P
|
>The build process involves the following steps:</P
|
>The build process involves the following steps:</P
|
><P
|
><P
|
></P
|
></P
|
><OL
|
><OL
|
TYPE="1"
|
TYPE="1"
|
><LI
|
><LI
|
><P
|
><P
|
>Given a configuration, the component framework is responsible for
|
>Given a configuration, the component framework is responsible for
|
creating all the directories in the build and install trees. If these
|
creating all the directories in the build and install trees. If these
|
trees already exist then the component framework is responsible for
|
trees already exist then the component framework is responsible for
|
any clean-ups that may be necessary, for example if a package has been
|
any clean-ups that may be necessary, for example if a package has been
|
removed then all related files should be expunged from the build and
|
removed then all related files should be expunged from the build and
|
install trees. The configuration header files will be generated at
|
install trees. The configuration header files will be generated at
|
this time. Depending on the host environment, the component framework
|
this time. Depending on the host environment, the component framework
|
will also generate makefiles or some other way of building the various
|
will also generate makefiles or some other way of building the various
|
packages. Every time the configuration is modified this step needs to
|
packages. Every time the configuration is modified this step needs to
|
be repeated, to ensure that all option consequences take effect. Care
|
be repeated, to ensure that all option consequences take effect. Care
|
is taken that this will not result in unnecessary rebuilds.</P
|
is taken that this will not result in unnecessary rebuilds.</P
|
><DIV
|
><DIV
|
CLASS="NOTE"
|
CLASS="NOTE"
|
><BLOCKQUOTE
|
><BLOCKQUOTE
|
CLASS="NOTE"
|
CLASS="NOTE"
|
><P
|
><P
|
><B
|
><B
|
>Note: </B
|
>Note: </B
|
>At present this step needs to be invoked manually. In a future version
|
>At present this step needs to be invoked manually. In a future version
|
the generated makefile may if desired perform this step automatically,
|
the generated makefile may if desired perform this step automatically,
|
using a dependency on the <TT
|
using a dependency on the <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>ecos.ecc</TT
|
>ecos.ecc</TT
|
> savefile.</P
|
> savefile.</P
|
></BLOCKQUOTE
|
></BLOCKQUOTE
|
></DIV
|
></DIV
|
></LI
|
></LI
|
><LI
|
><LI
|
><P
|
><P
|
>The first step in an actual build is to make sure that the install
|
>The first step in an actual build is to make sure that the install
|
tree contains all exported header files. All compilations will use
|
tree contains all exported header files. All compilations will use
|
the install tree's <TT
|
the install tree's <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>include</TT
|
>include</TT
|
>
|
>
|
directory as one of the places to search for header files.</P
|
directory as one of the places to search for header files.</P
|
></LI
|
></LI
|
><LI
|
><LI
|
><P
|
><P
|
>All source files relevant to the current configuration get compiled.
|
>All source files relevant to the current configuration get compiled.
|
This involves a set of compiler flags initialized on a per-target
|
This involves a set of compiler flags initialized on a per-target
|
basis, with each package being able to modify these flags, and with
|
basis, with each package being able to modify these flags, and with
|
the ability for the user to override the flags as well. Care has to be
|
the ability for the user to override the flags as well. Care has to be
|
taken here to avoid inappropriate target-dependencies in packages that
|
taken here to avoid inappropriate target-dependencies in packages that
|
are intended to be portable. The component framework has built-in
|
are intended to be portable. The component framework has built-in
|
knowledge of how to handle C, C++ and assembler source files —
|
knowledge of how to handle C, C++ and assembler source files —
|
other languages may be added in future, as and when necessary. The
|
other languages may be added in future, as and when necessary. The
|
<A
|
<A
|
HREF="ref.compile.html"
|
HREF="ref.compile.html"
|
><SPAN
|
><SPAN
|
CLASS="PROPERTY"
|
CLASS="PROPERTY"
|
>compile</SPAN
|
>compile</SPAN
|
></A
|
></A
|
> property is used to
|
> property is used to
|
list the files that should get compiled. All object files end up in
|
list the files that should get compiled. All object files end up in
|
the build tree.</P
|
the build tree.</P
|
></LI
|
></LI
|
><LI
|
><LI
|
><P
|
><P
|
>Once all the object files have been built they are collected into a
|
>Once all the object files have been built they are collected into a
|
library, typically <TT
|
library, typically <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>libtarget.a</TT
|
>libtarget.a</TT
|
>, which can then be
|
>, which can then be
|
linked with application code. The library is generated in the install
|
linked with application code. The library is generated in the install
|
tree. </P
|
tree. </P
|
></LI
|
></LI
|
><LI
|
><LI
|
><P
|
><P
|
>The component framework provides support for custom build steps, using
|
>The component framework provides support for custom build steps, using
|
the <A
|
the <A
|
HREF="ref.make-object.html"
|
HREF="ref.make-object.html"
|
><SPAN
|
><SPAN
|
CLASS="PROPERTY"
|
CLASS="PROPERTY"
|
>make_object</SPAN
|
>make_object</SPAN
|
></A
|
></A
|
> and
|
> and
|
<A
|
<A
|
HREF="ref.make.html"
|
HREF="ref.make.html"
|
><SPAN
|
><SPAN
|
CLASS="PROPERTY"
|
CLASS="PROPERTY"
|
>make</SPAN
|
>make</SPAN
|
></A
|
></A
|
> properties. The results of
|
> properties. The results of
|
these custom build steps can either be object files that should end up
|
these custom build steps can either be object files that should end up
|
in a library, or other files such as a linker script. It is possible
|
in a library, or other files such as a linker script. It is possible
|
to control the order in which these custom build steps take place, for
|
to control the order in which these custom build steps take place, for
|
example it is possible to run a particular build step before any of
|
example it is possible to run a particular build step before any of
|
the compilations happen.</P
|
the compilations happen.</P
|
></LI
|
></LI
|
></OL
|
></OL
|
></DIV
|
></DIV
|
><DIV
|
><DIV
|
CLASS="SECT2"
|
CLASS="SECT2"
|
><H2
|
><H2
|
CLASS="SECT2"
|
CLASS="SECT2"
|
><A
|
><A
|
NAME="PACKAGE.SOURCE">Configurable Source Code</H2
|
NAME="PACKAGE.SOURCE">Configurable Source Code</H2
|
><P
|
><P
|
>All packages should be totally portable to all target hardware (with
|
>All packages should be totally portable to all target hardware (with
|
the obvious exceptions of HAL and device driver packages). They should
|
the obvious exceptions of HAL and device driver packages). They should
|
also be totally bug-free, require the absolute minimum amount of code
|
also be totally bug-free, require the absolute minimum amount of code
|
and data space, be so efficient that cpu time usage is negligible, and
|
and data space, be so efficient that cpu time usage is negligible, and
|
provide lots of configuration options so that application developers
|
provide lots of configuration options so that application developers
|
have full control over the behavior. The configuration options are
|
have full control over the behavior. The configuration options are
|
optional only if a package can meet the requirements of every
|
optional only if a package can meet the requirements of every
|
potential application without any overheads. It is not the purpose of
|
potential application without any overheads. It is not the purpose of
|
this guide to explain how to achieve all of these requirements.</P
|
this guide to explain how to achieve all of these requirements.</P
|
><P
|
><P
|
>The <SPAN
|
>The <SPAN
|
CLASS="APPLICATION"
|
CLASS="APPLICATION"
|
>eCos</SPAN
|
>eCos</SPAN
|
> component framework does have some important implications
|
> component framework does have some important implications
|
for the source code: compiler flag dependencies; package interfaces
|
for the source code: compiler flag dependencies; package interfaces
|
vs. implementations; and how configuration options affect source code.</P
|
vs. implementations; and how configuration options affect source code.</P
|
><DIV
|
><DIV
|
CLASS="SECT3"
|
CLASS="SECT3"
|
><H3
|
><H3
|
CLASS="SECT3"
|
CLASS="SECT3"
|
><A
|
><A
|
NAME="PACKAGE.SOURCE.FLAGS">Compiler Flag Dependencies</H3
|
NAME="PACKAGE.SOURCE.FLAGS">Compiler Flag Dependencies</H3
|
><P
|
><P
|
>Wherever possible component writers should avoid dependencies on
|
>Wherever possible component writers should avoid dependencies on
|
particular compiler flags. Any such dependencies are likely to impact
|
particular compiler flags. Any such dependencies are likely to impact
|
portability. For example, if one package needs to be built in
|
portability. For example, if one package needs to be built in
|
big-endian mode and another package needs to be built in little-endian
|
big-endian mode and another package needs to be built in little-endian
|
mode then usually it will not be possible for application developers
|
mode then usually it will not be possible for application developers
|
to use both packages at the same time; in addition the application
|
to use both packages at the same time; in addition the application
|
developer is no longer given a choice in the matter. It is far better
|
developer is no longer given a choice in the matter. It is far better
|
for the package source code to adapt the endianness at compile-time,
|
for the package source code to adapt the endianness at compile-time,
|
or possibly at run-time although that will involve code-size
|
or possibly at run-time although that will involve code-size
|
overheads.</P
|
overheads.</P
|
><DIV
|
><DIV
|
CLASS="NOTE"
|
CLASS="NOTE"
|
><BLOCKQUOTE
|
><BLOCKQUOTE
|
CLASS="NOTE"
|
CLASS="NOTE"
|
><P
|
><P
|
><B
|
><B
|
>Note: </B
|
>Note: </B
|
>A related issue is that the current support for handling compiler
|
>A related issue is that the current support for handling compiler
|
flags in the component framework is still limited and incapable of
|
flags in the component framework is still limited and incapable of
|
handling flags at a very fine-grain. The support is likely to be
|
handling flags at a very fine-grain. The support is likely to be
|
enhanced in future versions of the framework, but there are
|
enhanced in future versions of the framework, but there are
|
non-trivial problems to be resolved.</P
|
non-trivial problems to be resolved.</P
|
></BLOCKQUOTE
|
></BLOCKQUOTE
|
></DIV
|
></DIV
|
></DIV
|
></DIV
|
><DIV
|
><DIV
|
CLASS="SECT3"
|
CLASS="SECT3"
|
><H3
|
><H3
|
CLASS="SECT3"
|
CLASS="SECT3"
|
><A
|
><A
|
NAME="PACKAGE.SOURCE.INTERFACES">Package Interfaces and Implementations</H3
|
NAME="PACKAGE.SOURCE.INTERFACES">Package Interfaces and Implementations</H3
|
><P
|
><P
|
>The component framework provides encapsulation at the package level. A
|
>The component framework provides encapsulation at the package level. A
|
package <TT
|
package <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>A</TT
|
>A</TT
|
> has no way of accessing the
|
> has no way of accessing the
|
implementation details of another package <TT
|
implementation details of another package <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>B</TT
|
>B</TT
|
> at
|
> at
|
compile-time. In particular, if there is a private header file
|
compile-time. In particular, if there is a private header file
|
somewhere in a package's <TT
|
somewhere in a package's <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>src</TT
|
>src</TT
|
>
|
>
|
sub-directory then this header file is completely invisible to other
|
sub-directory then this header file is completely invisible to other
|
packages. Any attempts to cheat by using relative pathnames beginning
|
packages. Any attempts to cheat by using relative pathnames beginning
|
with <TT
|
with <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>../..</TT
|
>../..</TT
|
> are generally doomed
|
> are generally doomed
|
to failure because of the presence of package version directories.
|
to failure because of the presence of package version directories.
|
There are two ways in which one package can affect another: by means
|
There are two ways in which one package can affect another: by means
|
of the exported header files, which define a public interface; or via
|
of the exported header files, which define a public interface; or via
|
the <SPAN
|
the <SPAN
|
CLASS="APPLICATION"
|
CLASS="APPLICATION"
|
>CDL</SPAN
|
>CDL</SPAN
|
> scripts.</P
|
> scripts.</P
|
><P
|
><P
|
>This encapsulation is a deliberate aspect of the overall <SPAN
|
>This encapsulation is a deliberate aspect of the overall <SPAN
|
CLASS="APPLICATION"
|
CLASS="APPLICATION"
|
>eCos</SPAN
|
>eCos</SPAN
|
>
|
>
|
component framework design. In most cases it does not cause any
|
component framework design. In most cases it does not cause any
|
problems for component writers. In some cases enforcing a clean
|
problems for component writers. In some cases enforcing a clean
|
separation between interface and implementation details can improve
|
separation between interface and implementation details can improve
|
the code. Also it reduces problems when a package gets upgraded:
|
the code. Also it reduces problems when a package gets upgraded:
|
component writers are free to do pretty much anything on the
|
component writers are free to do pretty much anything on the
|
implementation side, including renaming every single source file; care
|
implementation side, including renaming every single source file; care
|
has to be taken only with the exported header files and with the <SPAN
|
has to be taken only with the exported header files and with the <SPAN
|
CLASS="APPLICATION"
|
CLASS="APPLICATION"
|
>CDL</SPAN
|
>CDL</SPAN
|
>
|
>
|
data, because those have the potential of impacting other packages.
|
data, because those have the potential of impacting other packages.
|
Application code is similarly unable to access package implementation
|
Application code is similarly unable to access package implementation
|
details, only the exported interface.</P
|
details, only the exported interface.</P
|
><P
|
><P
|
>Very occasionally the inability of one package to see implementation
|
>Very occasionally the inability of one package to see implementation
|
details of another does cause problems. One example occurs in HAL
|
details of another does cause problems. One example occurs in HAL
|
packages, where it may be desirable for the architectural, variant and
|
packages, where it may be desirable for the architectural, variant and
|
platform HAL's to share some information that should not be visible to
|
platform HAL's to share some information that should not be visible to
|
other packages or to application code. This may be addressed in the
|
other packages or to application code. This may be addressed in the
|
future by introducing the concept of <TT
|
future by introducing the concept of <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>friend</TT
|
>friend</TT
|
>
|
>
|
packages, just as a C++ class can have <TT
|
packages, just as a C++ class can have <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>friend</TT
|
>friend</TT
|
>
|
>
|
functions and classes which are allowed special access to a class
|
functions and classes which are allowed special access to a class
|
internals. It is not yet clear whether such cases are sufficiently
|
internals. It is not yet clear whether such cases are sufficiently
|
frequent to warrant introducing such a facility.</P
|
frequent to warrant introducing such a facility.</P
|
></DIV
|
></DIV
|
><DIV
|
><DIV
|
CLASS="SECT3"
|
CLASS="SECT3"
|
><H3
|
><H3
|
CLASS="SECT3"
|
CLASS="SECT3"
|
><A
|
><A
|
NAME="PACKAGE.SOURCE.CONFIG">Source Code and Configuration Options</H3
|
NAME="PACKAGE.SOURCE.CONFIG">Source Code and Configuration Options</H3
|
><P
|
><P
|
>Configurability usually involves source code that needs to implement
|
>Configurability usually involves source code that needs to implement
|
different behavior depending on the settings of configuration
|
different behavior depending on the settings of configuration
|
options. It is possible to write packages where the only consequence
|
options. It is possible to write packages where the only consequence
|
associated with various configuration options is to control what gets
|
associated with various configuration options is to control what gets
|
built, but this approach is limited and does not allow for
|
built, but this approach is limited and does not allow for
|
fine-grained configurability. There are three main ways in which
|
fine-grained configurability. There are three main ways in which
|
options could affect source code at build time:</P
|
options could affect source code at build time:</P
|
><P
|
><P
|
></P
|
></P
|
><OL
|
><OL
|
TYPE="1"
|
TYPE="1"
|
><LI
|
><LI
|
><P
|
><P
|
>The component code can be passed through a suitable preprocessor,
|
>The component code can be passed through a suitable preprocessor,
|
either an existing one such as <SPAN
|
either an existing one such as <SPAN
|
CLASS="APPLICATION"
|
CLASS="APPLICATION"
|
>m4</SPAN
|
>m4</SPAN
|
> or a new one specially designed with
|
> or a new one specially designed with
|
configurability in mind. The original sources would reside in the
|
configurability in mind. The original sources would reside in the
|
component repository and the processed sources would reside in the
|
component repository and the processed sources would reside in the
|
build tree. These processed sources can then be compiled in the usual
|
build tree. These processed sources can then be compiled in the usual
|
way.</P
|
way.</P
|
><P
|
><P
|
>This approach has two main advantages. First, it is independent from
|
>This approach has two main advantages. First, it is independent from
|
the programming language used to code the components, provided
|
the programming language used to code the components, provided
|
reasonable precautions are taken to avoid syntax clashes between
|
reasonable precautions are taken to avoid syntax clashes between
|
preprocessor statements and actual code. This would make it easier in
|
preprocessor statements and actual code. This would make it easier in
|
future to support languages other than C and C++. Second, configurable
|
future to support languages other than C and C++. Second, configurable
|
code can make use of advanced preprocessing facilities such as loops
|
code can make use of advanced preprocessing facilities such as loops
|
and recursion. The disadvantage is that component writers would have
|
and recursion. The disadvantage is that component writers would have
|
to learn about a new preprocessor and embed appropriate directives in
|
to learn about a new preprocessor and embed appropriate directives in
|
the code. This makes it much more difficult to turn existing code into
|
the code. This makes it much more difficult to turn existing code into
|
components, and it involves extra training costs for the component
|
components, and it involves extra training costs for the component
|
writers.</P
|
writers.</P
|
></LI
|
></LI
|
><LI
|
><LI
|
><P
|
><P
|
>Compiler optimizations can be used to elide code that should not be
|
>Compiler optimizations can be used to elide code that should not be
|
present, for example:</P
|
present, for example:</P
|
><TABLE
|
><TABLE
|
BORDER="5"
|
BORDER="5"
|
BGCOLOR="#E0E0F0"
|
BGCOLOR="#E0E0F0"
|
WIDTH="70%"
|
WIDTH="70%"
|
><TR
|
><TR
|
><TD
|
><TD
|
><PRE
|
><PRE
|
CLASS="PROGRAMLISTING"
|
CLASS="PROGRAMLISTING"
|
> …
|
> …
|
if (CYGHWR_NUMBER_UARTS > 0) {
|
if (CYGHWR_NUMBER_UARTS > 0) {
|
…
|
…
|
}
|
}
|
…</PRE
|
…</PRE
|
></TD
|
></TD
|
></TR
|
></TR
|
></TABLE
|
></TABLE
|
><P
|
><P
|
>If the compiler knows that <TT
|
>If the compiler knows that <TT
|
CLASS="VARNAME"
|
CLASS="VARNAME"
|
>CYGHWR_NUMBER_UARTS</TT
|
>CYGHWR_NUMBER_UARTS</TT
|
> is
|
> is
|
the constant number 0 then it is a trivial operation to get rid of the
|
the constant number 0 then it is a trivial operation to get rid of the
|
unnecessary code. The component framework still has to define this
|
unnecessary code. The component framework still has to define this
|
symbol in a way that is acceptable to the compiler, typically by using
|
symbol in a way that is acceptable to the compiler, typically by using
|
a <TT
|
a <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>const</TT
|
>const</TT
|
> variable or a preprocessor symbol. In some
|
> variable or a preprocessor symbol. In some
|
respects this is a clean approach to configurability, but it has
|
respects this is a clean approach to configurability, but it has
|
limitations. It cannot be used in the declarations of data structures
|
limitations. It cannot be used in the declarations of data structures
|
or classes, nor does it provide control over entire functions. In
|
or classes, nor does it provide control over entire functions. In
|
addition it may not be immediately obvious that this code is affected
|
addition it may not be immediately obvious that this code is affected
|
by configuration options, which may make it more difficult to
|
by configuration options, which may make it more difficult to
|
understand.</P
|
understand.</P
|
></LI
|
></LI
|
><LI
|
><LI
|
><P
|
><P
|
>Existing language preprocessors can be used. In the case of C or C++
|
>Existing language preprocessors can be used. In the case of C or C++
|
this would be the standard C preprocessor, and configurable code would
|
this would be the standard C preprocessor, and configurable code would
|
contain a number of <TT
|
contain a number of <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#ifdef</TT
|
>#ifdef</TT
|
> and
|
> and
|
<TT
|
<TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#if</TT
|
>#if</TT
|
> statements.</P
|
> statements.</P
|
><TABLE
|
><TABLE
|
BORDER="5"
|
BORDER="5"
|
BGCOLOR="#E0E0F0"
|
BGCOLOR="#E0E0F0"
|
WIDTH="70%"
|
WIDTH="70%"
|
><TR
|
><TR
|
><TD
|
><TD
|
><PRE
|
><PRE
|
CLASS="PROGRAMLISTING"
|
CLASS="PROGRAMLISTING"
|
>#if (CYGHWR_NUMBER_UARTS > 0)
|
>#if (CYGHWR_NUMBER_UARTS > 0)
|
…
|
…
|
#endif</PRE
|
#endif</PRE
|
></TD
|
></TD
|
></TR
|
></TR
|
></TABLE
|
></TABLE
|
><P
|
><P
|
>This approach has the big advantage that the C preprocessor is a
|
>This approach has the big advantage that the C preprocessor is a
|
technology that is both well-understood and widely used. There are
|
technology that is both well-understood and widely used. There are
|
also disadvantages: it is not directly applicable to components
|
also disadvantages: it is not directly applicable to components
|
written in other languages such as Java (although it is possible to
|
written in other languages such as Java (although it is possible to
|
use the C preprocessor as a stand-alone program); the preprocessing
|
use the C preprocessor as a stand-alone program); the preprocessing
|
facilities are rather limited, for example there is no looping
|
facilities are rather limited, for example there is no looping
|
facility; and some people consider the technology to be ugly. Of
|
facility; and some people consider the technology to be ugly. Of
|
course it may be possible to get around the second objection by
|
course it may be possible to get around the second objection by
|
extending the preprocessor that is used by gcc and g++.</P
|
extending the preprocessor that is used by gcc and g++.</P
|
></LI
|
></LI
|
></OL
|
></OL
|
><P
|
><P
|
>The current component framework generates configuration header files
|
>The current component framework generates configuration header files
|
with C preprocessor <TT
|
with C preprocessor <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#define's</TT
|
>#define's</TT
|
> for each option
|
> for each option
|
(typically, there various properties which can be used to control
|
(typically, there various properties which can be used to control
|
this). It is up to component writers to decide whether to use
|
this). It is up to component writers to decide whether to use
|
preprocessor <TT
|
preprocessor <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#ifdef</TT
|
>#ifdef</TT
|
> statements or language
|
> statements or language
|
constructs such as <TT
|
constructs such as <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>if</TT
|
>if</TT
|
>. At present there is no
|
>. At present there is no
|
support for languages which do not involve the C preprocessor,
|
support for languages which do not involve the C preprocessor,
|
although such support can be added in future when the need arises.</P
|
although such support can be added in future when the need arises.</P
|
></DIV
|
></DIV
|
></DIV
|
></DIV
|
><DIV
|
><DIV
|
CLASS="SECT2"
|
CLASS="SECT2"
|
><H2
|
><H2
|
CLASS="SECT2"
|
CLASS="SECT2"
|
><A
|
><A
|
NAME="PACKAGE.HEADERS">Exported Header Files</H2
|
NAME="PACKAGE.HEADERS">Exported Header Files</H2
|
><P
|
><P
|
>A package's exported header files should specify the interface
|
>A package's exported header files should specify the interface
|
provided by that package, and avoid any implementation details.
|
provided by that package, and avoid any implementation details.
|
However there may be performance or other reasons why implementation
|
However there may be performance or other reasons why implementation
|
details occasionally need to be present in the exported headers.</P
|
details occasionally need to be present in the exported headers.</P
|
><DIV
|
><DIV
|
CLASS="NOTE"
|
CLASS="NOTE"
|
><BLOCKQUOTE
|
><BLOCKQUOTE
|
CLASS="NOTE"
|
CLASS="NOTE"
|
><P
|
><P
|
><B
|
><B
|
>Note: </B
|
>Note: </B
|
>Not all programming languages have the concept of a header file. In
|
>Not all programming languages have the concept of a header file. In
|
some cases the component framework would need extensions to support
|
some cases the component framework would need extensions to support
|
packages written in such languages. </P
|
packages written in such languages. </P
|
></BLOCKQUOTE
|
></BLOCKQUOTE
|
></DIV
|
></DIV
|
><P
|
><P
|
>Configurability has a number of effects on the way exported header
|
>Configurability has a number of effects on the way exported header
|
files should be written. There may be configuration options which
|
files should be written. There may be configuration options which
|
affect the interface of a package, not just the implementation. It is
|
affect the interface of a package, not just the implementation. It is
|
necessary to worry about nested <TT
|
necessary to worry about nested <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#include's</TT
|
>#include's</TT
|
> and how
|
> and how
|
this affects package and application builds. A special case of this
|
this affects package and application builds. A special case of this
|
relates to whether or not exported header files should
|
relates to whether or not exported header files should
|
<TT
|
<TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#include</TT
|
>#include</TT
|
> configuration headers. These configuration
|
> configuration headers. These configuration
|
headers are exported, but should only be <TT
|
headers are exported, but should only be <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#include'd</TT
|
>#include'd</TT
|
>
|
>
|
when necessary.</P
|
when necessary.</P
|
><DIV
|
><DIV
|
CLASS="SECT3"
|
CLASS="SECT3"
|
><H3
|
><H3
|
CLASS="SECT3"
|
CLASS="SECT3"
|
><A
|
><A
|
NAME="PACKAGE.HEADERS.FUNCTIONS">Configurable Functionality</H3
|
NAME="PACKAGE.HEADERS.FUNCTIONS">Configurable Functionality</H3
|
><P
|
><P
|
>Many configuration options affect only the implementation of a
|
>Many configuration options affect only the implementation of a
|
package, not the interface. However some options will affect the
|
package, not the interface. However some options will affect the
|
interface as well, which means that the options have to be tested in
|
interface as well, which means that the options have to be tested in
|
the exported header files. Some implementation choices, for example
|
the exported header files. Some implementation choices, for example
|
whether or not a particular function should be inlined, also need to
|
whether or not a particular function should be inlined, also need to
|
be tested in the header file because of language limitations.</P
|
be tested in the header file because of language limitations.</P
|
><P
|
><P
|
>Consider a configuration option
|
>Consider a configuration option
|
<TT
|
<TT
|
CLASS="VARNAME"
|
CLASS="VARNAME"
|
>CYGFUN_KERNEL_MUTEX_TIMEDLOCK</TT
|
>CYGFUN_KERNEL_MUTEX_TIMEDLOCK</TT
|
> which controls
|
> which controls
|
whether or not a function <TT
|
whether or not a function <TT
|
CLASS="FUNCTION"
|
CLASS="FUNCTION"
|
>cyg_mutex_timedlock</TT
|
>cyg_mutex_timedlock</TT
|
> is
|
> is
|
provided. The exported kernel header file <TT
|
provided. The exported kernel header file <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>cyg/kernel/kapi.h</TT
|
>cyg/kernel/kapi.h</TT
|
> could contain the
|
> could contain the
|
following:</P
|
following:</P
|
><TABLE
|
><TABLE
|
BORDER="5"
|
BORDER="5"
|
BGCOLOR="#E0E0F0"
|
BGCOLOR="#E0E0F0"
|
WIDTH="70%"
|
WIDTH="70%"
|
><TR
|
><TR
|
><TD
|
><TD
|
><PRE
|
><PRE
|
CLASS="PROGRAMLISTING"
|
CLASS="PROGRAMLISTING"
|
>#include <pkgconf/kernel.h>
|
>#include <pkgconf/kernel.h>
|
…
|
…
|
#ifdef CYGFUN_KERNEL_MUTEX_TIMEDLOCK
|
#ifdef CYGFUN_KERNEL_MUTEX_TIMEDLOCK
|
extern bool cyg_mutex_timedlock(cyg_mutex_t*);
|
extern bool cyg_mutex_timedlock(cyg_mutex_t*);
|
#endif</PRE
|
#endif</PRE
|
></TD
|
></TD
|
></TR
|
></TR
|
></TABLE
|
></TABLE
|
><P
|
><P
|
>This is a correct header file, in that it defines the exact interface
|
>This is a correct header file, in that it defines the exact interface
|
provided by the package at all times. However is has a number of
|
provided by the package at all times. However is has a number of
|
implications. First, the header file is now dependent on <TT
|
implications. First, the header file is now dependent on <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>pkgconf/kernel.h</TT
|
>pkgconf/kernel.h</TT
|
>, so any changes to
|
>, so any changes to
|
kernel configuration options will cause <TT
|
kernel configuration options will cause <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>cyg/kernel/kapi.h</TT
|
>cyg/kernel/kapi.h</TT
|
> to be out of date, and
|
> to be out of date, and
|
any source files that use the kernel interface will need rebuilding.
|
any source files that use the kernel interface will need rebuilding.
|
This may affect sources in the kernel package, in other packages, and
|
This may affect sources in the kernel package, in other packages, and
|
in application source code. Second, if the application makes use of
|
in application source code. Second, if the application makes use of
|
this function somewhere but the application developer has
|
this function somewhere but the application developer has
|
misconfigured the system and disabled this functionality anyway then
|
misconfigured the system and disabled this functionality anyway then
|
there will now be a compile-time error when building the application.
|
there will now be a compile-time error when building the application.
|
Note that other packages should not be affected, since they should
|
Note that other packages should not be affected, since they should
|
impose appropriate constraints on
|
impose appropriate constraints on
|
<TT
|
<TT
|
CLASS="VARNAME"
|
CLASS="VARNAME"
|
>CYGFUN_KERNEL_MUTEX_TIMEDLOCK</TT
|
>CYGFUN_KERNEL_MUTEX_TIMEDLOCK</TT
|
> if they use that
|
> if they use that
|
functionality (although of course some dependencies like this may get
|
functionality (although of course some dependencies like this may get
|
missed by component developers).</P
|
missed by component developers).</P
|
><P
|
><P
|
>An alternative approach would be:</P
|
>An alternative approach would be:</P
|
><TABLE
|
><TABLE
|
BORDER="5"
|
BORDER="5"
|
BGCOLOR="#E0E0F0"
|
BGCOLOR="#E0E0F0"
|
WIDTH="70%"
|
WIDTH="70%"
|
><TR
|
><TR
|
><TD
|
><TD
|
><PRE
|
><PRE
|
CLASS="PROGRAMLISTING"
|
CLASS="PROGRAMLISTING"
|
>extern bool cyg_mutex_timedlock(cyg_mutex_t*);</PRE
|
>extern bool cyg_mutex_timedlock(cyg_mutex_t*);</PRE
|
></TD
|
></TD
|
></TR
|
></TR
|
></TABLE
|
></TABLE
|
><P
|
><P
|
>Effectively the header file is now lying about the functionality
|
>Effectively the header file is now lying about the functionality
|
provided by the package. The first result is that there is no longer a
|
provided by the package. The first result is that there is no longer a
|
dependency on the kernel configuration header. The second result is
|
dependency on the kernel configuration header. The second result is
|
that an application file using the timed-lock function will now
|
that an application file using the timed-lock function will now
|
compile, but the application will fail to link. At this stage the
|
compile, but the application will fail to link. At this stage the
|
application developer still has to intervene, change the
|
application developer still has to intervene, change the
|
configuration, and rebuild the system. However no application
|
configuration, and rebuild the system. However no application
|
recompilations are necessary, just a relink.</P
|
recompilations are necessary, just a relink.</P
|
><P
|
><P
|
>Theoretically it would be possible for a tool to analyze linker errors
|
>Theoretically it would be possible for a tool to analyze linker errors
|
and suggest possible configuration changes that would resolve the
|
and suggest possible configuration changes that would resolve the
|
problem, reducing the burden on the application developer. No such
|
problem, reducing the burden on the application developer. No such
|
tool is planned in the short term.</P
|
tool is planned in the short term.</P
|
><P
|
><P
|
>It is up to component writers to decide which of these two approaches
|
>It is up to component writers to decide which of these two approaches
|
should be preferred. Note that it is not always possible to avoid
|
should be preferred. Note that it is not always possible to avoid
|
<TT
|
<TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#include'ing</TT
|
>#include'ing</TT
|
> a configuration header file in an
|
> a configuration header file in an
|
exported one, for example an option may affect a data structure rather
|
exported one, for example an option may affect a data structure rather
|
than just the presence or absence of a function. Issues like this will
|
than just the presence or absence of a function. Issues like this will
|
vary from package to package.</P
|
vary from package to package.</P
|
></DIV
|
></DIV
|
><DIV
|
><DIV
|
CLASS="SECT3"
|
CLASS="SECT3"
|
><H3
|
><H3
|
CLASS="SECT3"
|
CLASS="SECT3"
|
><A
|
><A
|
NAME="PACKAGE.HEADERS.INCLUDES">Nested <TT
|
NAME="PACKAGE.HEADERS.INCLUDES">Nested <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#include's</TT
|
>#include's</TT
|
></H3
|
></H3
|
><P
|
><P
|
>As a general rule, unnecessary <TT
|
>As a general rule, unnecessary <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#include's</TT
|
>#include's</TT
|
> should be
|
> should be
|
avoided. A header file should <TT
|
avoided. A header file should <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#include</TT
|
>#include</TT
|
> only those
|
> only those
|
header files which are absolutely needed for it to define its
|
header files which are absolutely needed for it to define its
|
interface. Any additional <TT
|
interface. Any additional <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#include's</TT
|
>#include's</TT
|
> make it more
|
> make it more
|
likely that package or application source files become dependent on
|
likely that package or application source files become dependent on
|
configuration header files and will get rebuilt unnecessarily when
|
configuration header files and will get rebuilt unnecessarily when
|
there are minor configuration changes.</P
|
there are minor configuration changes.</P
|
></DIV
|
></DIV
|
><DIV
|
><DIV
|
CLASS="SECT3"
|
CLASS="SECT3"
|
><H3
|
><H3
|
CLASS="SECT3"
|
CLASS="SECT3"
|
><A
|
><A
|
NAME="PACKAGE.HEADERS.CONFIGINCLUDES">Including Configuration Headers</H3
|
NAME="PACKAGE.HEADERS.CONFIGINCLUDES">Including Configuration Headers</H3
|
><P
|
><P
|
>Exported header files should avoid <TT
|
>Exported header files should avoid <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#include'ing</TT
|
>#include'ing</TT
|
>
|
>
|
configuration header files unless absolutely necessary, to avoid
|
configuration header files unless absolutely necessary, to avoid
|
unnecessary rebuilding of both application code and other packages
|
unnecessary rebuilding of both application code and other packages
|
when there are minor configuration changes. A
|
when there are minor configuration changes. A
|
<TT
|
<TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#include</TT
|
>#include</TT
|
> is needed only when a configuration option
|
> is needed only when a configuration option
|
affects the exported interface, or when it affects some implementation
|
affects the exported interface, or when it affects some implementation
|
details which is controlled by the header file such as whether or not
|
details which is controlled by the header file such as whether or not
|
a particular function gets inlined.</P
|
a particular function gets inlined.</P
|
><P
|
><P
|
>There are a couple of ways in which the problem of unnecessary
|
>There are a couple of ways in which the problem of unnecessary
|
rebuilding could be addressed. The first would require more
|
rebuilding could be addressed. The first would require more
|
intelligent handling of header file dependency handling by the tools
|
intelligent handling of header file dependency handling by the tools
|
(especially the compiler) and the build system. This would require
|
(especially the compiler) and the build system. This would require
|
changes to various non-eCos tools. An alternative approach would be to
|
changes to various non-eCos tools. An alternative approach would be to
|
support finer-grained configuration header files, for example there
|
support finer-grained configuration header files, for example there
|
could be a file <TT
|
could be a file <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>pkgconf/libc/inline.h</TT
|
>pkgconf/libc/inline.h</TT
|
> controlling which
|
> controlling which
|
functions should be inlined. This could be achieved by some fairly
|
functions should be inlined. This could be achieved by some fairly
|
simple extensions to the component framework, but it makes it more
|
simple extensions to the component framework, but it makes it more
|
difficult to get the package header files and source code correct:
|
difficult to get the package header files and source code correct:
|
a C preprocessor <TT
|
a C preprocessor <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#ifdef</TT
|
>#ifdef</TT
|
> directive does not
|
> directive does not
|
distinguish between a symbol not being defined because the option is
|
distinguish between a symbol not being defined because the option is
|
disabled, or the symbol not being defined because the appropriate
|
disabled, or the symbol not being defined because the appropriate
|
configuration header file has not been <TT
|
configuration header file has not been <TT
|
CLASS="LITERAL"
|
CLASS="LITERAL"
|
>#include'd</TT
|
>#include'd</TT
|
>.
|
>.
|
It is likely that a cross-referencing tool would have to be developed
|
It is likely that a cross-referencing tool would have to be developed
|
first to catch problems like this, before the component framework
|
first to catch problems like this, before the component framework
|
could support finer-grained configuration headers.</P
|
could support finer-grained configuration headers.</P
|
></DIV
|
></DIV
|
></DIV
|
></DIV
|
><DIV
|
><DIV
|
CLASS="SECT2"
|
CLASS="SECT2"
|
><H2
|
><H2
|
CLASS="SECT2"
|
CLASS="SECT2"
|
><A
|
><A
|
NAME="PACKAGE.DOCUMENTATION">Package Documentation</H2
|
NAME="PACKAGE.DOCUMENTATION">Package Documentation</H2
|
><P
|
><P
|
>On-line package documentation should be in HTML format. The component
|
>On-line package documentation should be in HTML format. The component
|
framework imposes no special limitations: component writers can decide
|
framework imposes no special limitations: component writers can decide
|
which version of the HTML specification should be followed; they can
|
which version of the HTML specification should be followed; they can
|
also decide on how best to cope with the limitations of different
|
also decide on how best to cope with the limitations of different
|
browsers. In general it is a good idea to keep things simple.</P
|
browsers. In general it is a good idea to keep things simple.</P
|
></DIV
|
></DIV
|
><DIV
|
><DIV
|
CLASS="SECT2"
|
CLASS="SECT2"
|
><H2
|
><H2
|
CLASS="SECT2"
|
CLASS="SECT2"
|
><A
|
><A
|
NAME="PACKAGE.TESTS">Test Cases</H2
|
NAME="PACKAGE.TESTS">Test Cases</H2
|
><P
|
><P
|
>Packages should normally come with one or more test cases. This allows
|
>Packages should normally come with one or more test cases. This allows
|
application developers to verify that a given package works correctly
|
application developers to verify that a given package works correctly
|
on their particular hardware and in their particular configuration,
|
on their particular hardware and in their particular configuration,
|
making it slightly more likely that they will attempt to find bugs in
|
making it slightly more likely that they will attempt to find bugs in
|
their own code rather than automatically blaming the component
|
their own code rather than automatically blaming the component
|
writers.</P
|
writers.</P
|
><P
|
><P
|
>At the time of writing the application developer support for building
|
>At the time of writing the application developer support for building
|
and running test cases via the component framework is under review and
|
and running test cases via the component framework is under review and
|
likely to change. Currently each test case should consist of a single
|
likely to change. Currently each test case should consist of a single
|
C or C++ source file that can be compiled with the package's set of
|
C or C++ source file that can be compiled with the package's set of
|
compiler flags and linked like any application program. Each test case
|
compiler flags and linked like any application program. Each test case
|
should use the testing API defined by the infrastructure. A
|
should use the testing API defined by the infrastructure. A
|
magically-named calculated configuration option of the form
|
magically-named calculated configuration option of the form
|
<TT
|
<TT
|
CLASS="VARNAME"
|
CLASS="VARNAME"
|
>CYGPKG_<PACKAGE-NAME>_TESTS</TT
|
>CYGPKG_<PACKAGE-NAME>_TESTS</TT
|
> lists the test
|
> lists the test
|
cases.</P
|
cases.</P
|
></DIV
|
></DIV
|
><DIV
|
><DIV
|
CLASS="SECT2"
|
CLASS="SECT2"
|
><H2
|
><H2
|
CLASS="SECT2"
|
CLASS="SECT2"
|
><A
|
><A
|
NAME="PACKAGE.HOST">Host-side Support</H2
|
NAME="PACKAGE.HOST">Host-side Support</H2
|
><P
|
><P
|
>On occasion it would be useful for an <SPAN
|
>On occasion it would be useful for an <SPAN
|
CLASS="APPLICATION"
|
CLASS="APPLICATION"
|
>eCos</SPAN
|
>eCos</SPAN
|
> package to be shipped
|
> package to be shipped
|
with host-side support. This could take the form of an additional tool
|
with host-side support. This could take the form of an additional tool
|
needed to build that package. It could be an application intended to
|
needed to build that package. It could be an application intended to
|
communicate with the target-side package code and display monitoring
|
communicate with the target-side package code and display monitoring
|
information. It could be a utility needed for running the package test
|
information. It could be a utility needed for running the package test
|
cases, especially in the case of device drivers. The component
|
cases, especially in the case of device drivers. The component
|
framework does not yet provide any such support for host-side
|
framework does not yet provide any such support for host-side
|
software, and there are obvious issues related to portability to the
|
software, and there are obvious issues related to portability to the
|
different machines that can be used for hosts. This issue may get
|
different machines that can be used for hosts. This issue may get
|
addressed in some future release. In some cases custom build steps can
|
addressed in some future release. In some cases custom build steps can
|
be subverted to do things on the host side rather than the target
|
be subverted to do things on the host side rather than the target
|
side, but this is not recommended.</P
|
side, but this is not recommended.</P
|
></DIV
|
></DIV
|
></DIV
|
></DIV
|
><DIV
|
><DIV
|
CLASS="NAVFOOTER"
|
CLASS="NAVFOOTER"
|
><HR
|
><HR
|
ALIGN="LEFT"
|
ALIGN="LEFT"
|
WIDTH="100%"><TABLE
|
WIDTH="100%"><TABLE
|
SUMMARY="Footer navigation table"
|
SUMMARY="Footer navigation table"
|
WIDTH="100%"
|
WIDTH="100%"
|
BORDER="0"
|
BORDER="0"
|
CELLPADDING="0"
|
CELLPADDING="0"
|
CELLSPACING="0"
|
CELLSPACING="0"
|
><TR
|
><TR
|
><TD
|
><TD
|
WIDTH="33%"
|
WIDTH="33%"
|
ALIGN="left"
|
ALIGN="left"
|
VALIGN="top"
|
VALIGN="top"
|
><A
|
><A
|
HREF="package.versions.html"
|
HREF="package.versions.html"
|
ACCESSKEY="P"
|
ACCESSKEY="P"
|
>Prev</A
|
>Prev</A
|
></TD
|
></TD
|
><TD
|
><TD
|
WIDTH="34%"
|
WIDTH="34%"
|
ALIGN="center"
|
ALIGN="center"
|
VALIGN="top"
|
VALIGN="top"
|
><A
|
><A
|
HREF="cdl-guide.html"
|
HREF="cdl-guide.html"
|
ACCESSKEY="H"
|
ACCESSKEY="H"
|
>Home</A
|
>Home</A
|
></TD
|
></TD
|
><TD
|
><TD
|
WIDTH="33%"
|
WIDTH="33%"
|
ALIGN="right"
|
ALIGN="right"
|
VALIGN="top"
|
VALIGN="top"
|
><A
|
><A
|
HREF="package.distrib.html"
|
HREF="package.distrib.html"
|
ACCESSKEY="N"
|
ACCESSKEY="N"
|
>Next</A
|
>Next</A
|
></TD
|
></TD
|
></TR
|
></TR
|
><TR
|
><TR
|
><TD
|
><TD
|
WIDTH="33%"
|
WIDTH="33%"
|
ALIGN="left"
|
ALIGN="left"
|
VALIGN="top"
|
VALIGN="top"
|
>Package Versioning</TD
|
>Package Versioning</TD
|
><TD
|
><TD
|
WIDTH="34%"
|
WIDTH="34%"
|
ALIGN="center"
|
ALIGN="center"
|
VALIGN="top"
|
VALIGN="top"
|
><A
|
><A
|
HREF="package.html"
|
HREF="package.html"
|
ACCESSKEY="U"
|
ACCESSKEY="U"
|
>Up</A
|
>Up</A
|
></TD
|
></TD
|
><TD
|
><TD
|
WIDTH="33%"
|
WIDTH="33%"
|
ALIGN="right"
|
ALIGN="right"
|
VALIGN="top"
|
VALIGN="top"
|
>Making a Package Distribution</TD
|
>Making a Package Distribution</TD
|
></TR
|
></TR
|
></TABLE
|
></TABLE
|
></DIV
|
></DIV
|
></BODY
|
></BODY
|
></HTML
|
></HTML
|
|
|