📄 package.contents.html
字号:
<!-- Copyright (C) 2003 Red Hat, Inc. -->
<!-- This material may be distributed only subject to the terms -->
<!-- and conditions set forth in the Open Publication License, v1.0 -->
<!-- or later (the latest version is presently available at -->
<!-- http://www.opencontent.org/openpub/). -->
<!-- Distribution of the work or derivative of the work in any -->
<!-- standard (paper) book form is prohibited unless prior -->
<!-- permission is obtained from the copyright holder. -->
<HTML
><HEAD
><TITLE
>Package Contents and Layout</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="The eCos Component Writer's Guide"
HREF="cdl-guide.html"><LINK
REL="UP"
TITLE="Package Organization"
HREF="package.html"><LINK
REL="PREVIOUS"
TITLE="Package Versioning"
HREF="package.versions.html"><LINK
REL="NEXT"
TITLE="Making a Package Distribution"
HREF="package.distrib.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>The <SPAN
CLASS="APPLICATION"
>eCos</SPAN
> Component Writer's Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="package.versions.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 2. Package Organization</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="package.distrib.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="PACKAGE.CONTENTS">Package Contents and Layout</H1
><P
>A typical package contains the following:</P
><P
></P
><OL
TYPE="1"
><LI
><P
>Some number of source files which will end up in a library. The
application code will be linked with this library to produce an
executable. Some source files may serve other purposes, for example to
provide a linker script.</P
></LI
><LI
><P
>Exported header files which define the interface provided by the
package. </P
></LI
><LI
><P
>On-line documentation, for example reference pages for each exported
function. </P
></LI
><LI
><P
>Some number of test cases, shipped in source format, allowing users to
check that the package is working as expected on their particular
hardware and in their specific configuration.</P
></LI
><LI
><P
>One or more <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> scripts describing the package to the configuration
system.</P
></LI
></OL
><P
>It is also conventional to have a per-package
<TT
CLASS="FILENAME"
>ChangeLog</TT
> file used to keep track of changes to
that package. This is especially valuable to end users of the package
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
out easily what has changed. Often it can be very useful to the main
developers as well.</P
><P
>Any given packages need not contain all of these. It is compulsory to
have at least one <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> script describing the package, otherwise the
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
defines a common interface which can then be implemented by several
other packages, especially in the context of device drivers; however
it is still common to have some code in such packages to avoid
replicating shareable code in all of the implementation packages.
Similarly it is possible to have a package with no exported header
files, just source code that implements an existing interface: for
example an ethernet device driver might just implement a standard
interface and not provide any additional functionality. Packages do
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
applies to per-package test cases.</P
><P
>The component framework has a recommended per-package directory layout
which splits the package contents on a functional basis:</P
><DIV
CLASS="INFORMALFIGURE"
><A
NAME="AEN302"><P
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="package.png"
ALIGN="CENTER"></P
></DIV
><P
></P
></DIV
><P
>For example, if a package has an <TT
CLASS="FILENAME"
>include</TT
> sub-directory then the component
framework will assume that all header files in and below that
directory are exported header files and will do the right thing at
build time. Similarly if there is <SPAN
CLASS="PROPERTY"
>doc</SPAN
> property indicating the
location of on-line documentation then the component framework will
first look in the <TT
CLASS="FILENAME"
>doc</TT
>
sub-directory.</P
><P
>This directory layout is just a guideline, it is not enforced by the
component framework. For simple packages it often makes more sense to
have all of the files in just one directory. For example a package
could just contain the files <TT
CLASS="FILENAME"
>hello.cxx</TT
>,
<TT
CLASS="FILENAME"
>hello.h</TT
>, <TT
CLASS="FILENAME"
>hello.html</TT
> and
<TT
CLASS="FILENAME"
>hello.cdl</TT
>. By default
<TT
CLASS="FILENAME"
>hello.h</TT
> will be treated as an exported header
file, although this can be overridden with the <A
HREF="ref.include-files.html"
><SPAN
CLASS="PROPERTY"
>include_files</SPAN
></A
> property. Assuming
there is a <SPAN
CLASS="PROPERTY"
>doc</SPAN
> property referring to <TT
CLASS="FILENAME"
>hello.html</TT
>
and there is no <TT
CLASS="FILENAME"
>doc</TT
>
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
applies to <TT
CLASS="FILENAME"
>hello.cxx</TT
> and
<TT
CLASS="FILENAME"
>hello.cdl</TT
>. </P
><DIV
CLASS="TIP"
><BLOCKQUOTE
CLASS="TIP"
><P
><B
>Tip: </B
>Older versions of the <SPAN
CLASS="APPLICATION"
>eCos</SPAN
> build system only supported packages that
followed the directory structure exactly. Hence certain core packages
such as <TT
CLASS="FILENAME"
>error</TT
> implement the full directory
structure, even though that is a particularly simple package and the
full directory structure is inappropriate. Component writers can
decide for themselves whether or not the directory structure
guidelines are appropriate for their package.</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="PACKAGE.BUILD">Outline of the Build Process</H2
><P
>The full build process is described in <A
HREF="build.html"
>Chapter 4</A
>, but
a summary is appropriate here. A build involves three directory
structures: </P
><P
></P
><OL
TYPE="1"
><LI
><P
>The component repository. This is where all the package source code is
held, along with <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> scripts, documentation, and so on. For build
purposes a component repository is read-only. Application developers
will only modify the component repository when installing or removing
packages, via the administration tool. Component writers will
typically work on just one package in the component repository.</P
></LI
><LI
><P
>The build tree. Each configuration has its own build tree, which can
be regenerated at any time using the configuration's
<TT
CLASS="FILENAME"
>ecos.ecc</TT
> savefile. The build tree contains only
intermediate files, primarily object files. Once a build is complete
the build tree contains no information that is useful for application
development and can be wiped, although this would slow down any
rebuilds following changes to the configuration.</P
></LI
><LI
><P
>The install tree. This is populated during a build, and contains all
the files relevant to application development. There will be a
<TT
CLASS="FILENAME"
>lib</TT
> sub-directory which
typically contains <TT
CLASS="FILENAME"
>libtarget.a</TT
>, a linker script,
start-up code, and so on. There will also be an <TT
CLASS="FILENAME"
>include</TT
> sub-directory containing all the
header files exported by the various packages. There will also be a
<TT
CLASS="FILENAME"
>include/pkgconf</TT
> sub-directory
containing various configuration header files with
<TT
CLASS="LITERAL"
>#define's</TT
> for the options. Typically the install
tree is created within the build tree, but this is not a requirement.</P
></LI
></OL
><P
>The build process involves the following steps:</P
><P
></P
><OL
TYPE="1"
><LI
><P
>Given a configuration, the component framework is responsible for
creating all the directories in the build and install trees. If these
trees already exist then the component framework is responsible for
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
install trees. The configuration header files will be generated at
this time. Depending on the host environment, the component framework
will also generate makefiles or some other way of building the various
packages. Every time the configuration is modified this step needs to
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -