| 1 |
28 |
unneback |
<!-- Copyright (C) 2003 Red Hat, Inc. -->
|
| 2 |
|
|
<!-- This material may be distributed only subject to the terms -->
|
| 3 |
|
|
<!-- and conditions set forth in the Open Publication License, v1.0 -->
|
| 4 |
|
|
<!-- or later (the latest version is presently available at -->
|
| 5 |
|
|
<!-- http://www.opencontent.org/openpub/). -->
|
| 6 |
|
|
<!-- Distribution of the work or derivative of the work in any -->
|
| 7 |
|
|
<!-- standard (paper) book form is prohibited unless prior -->
|
| 8 |
|
|
<!-- permission is obtained from the copyright holder. -->
|
| 9 |
|
|
<HTML
|
| 10 |
|
|
><HEAD
|
| 11 |
|
|
><TITLE
|
| 12 |
|
|
>Package Contents and Layout</TITLE
|
| 13 |
|
|
><meta name="MSSmartTagsPreventParsing" content="TRUE">
|
| 14 |
|
|
<META
|
| 15 |
|
|
NAME="GENERATOR"
|
| 16 |
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
|
| 17 |
|
|
"><LINK
|
| 18 |
|
|
REL="HOME"
|
| 19 |
|
|
TITLE="The eCos Component Writer's Guide"
|
| 20 |
|
|
HREF="cdl-guide.html"><LINK
|
| 21 |
|
|
REL="UP"
|
| 22 |
|
|
TITLE="Package Organization"
|
| 23 |
|
|
HREF="package.html"><LINK
|
| 24 |
|
|
REL="PREVIOUS"
|
| 25 |
|
|
TITLE="Package Versioning"
|
| 26 |
|
|
HREF="package.versions.html"><LINK
|
| 27 |
|
|
REL="NEXT"
|
| 28 |
|
|
TITLE="Making a Package Distribution"
|
| 29 |
|
|
HREF="package.distrib.html"></HEAD
|
| 30 |
|
|
><BODY
|
| 31 |
|
|
CLASS="SECT1"
|
| 32 |
|
|
BGCOLOR="#FFFFFF"
|
| 33 |
|
|
TEXT="#000000"
|
| 34 |
|
|
LINK="#0000FF"
|
| 35 |
|
|
VLINK="#840084"
|
| 36 |
|
|
ALINK="#0000FF"
|
| 37 |
|
|
><DIV
|
| 38 |
|
|
CLASS="NAVHEADER"
|
| 39 |
|
|
><TABLE
|
| 40 |
|
|
SUMMARY="Header navigation table"
|
| 41 |
|
|
WIDTH="100%"
|
| 42 |
|
|
BORDER="0"
|
| 43 |
|
|
CELLPADDING="0"
|
| 44 |
|
|
CELLSPACING="0"
|
| 45 |
|
|
><TR
|
| 46 |
|
|
><TH
|
| 47 |
|
|
COLSPAN="3"
|
| 48 |
|
|
ALIGN="center"
|
| 49 |
|
|
>The <SPAN
|
| 50 |
|
|
CLASS="APPLICATION"
|
| 51 |
|
|
>eCos</SPAN
|
| 52 |
|
|
> Component Writer's Guide</TH
|
| 53 |
|
|
></TR
|
| 54 |
|
|
><TR
|
| 55 |
|
|
><TD
|
| 56 |
|
|
WIDTH="10%"
|
| 57 |
|
|
ALIGN="left"
|
| 58 |
|
|
VALIGN="bottom"
|
| 59 |
|
|
><A
|
| 60 |
|
|
HREF="package.versions.html"
|
| 61 |
|
|
ACCESSKEY="P"
|
| 62 |
|
|
>Prev</A
|
| 63 |
|
|
></TD
|
| 64 |
|
|
><TD
|
| 65 |
|
|
WIDTH="80%"
|
| 66 |
|
|
ALIGN="center"
|
| 67 |
|
|
VALIGN="bottom"
|
| 68 |
|
|
>Chapter 2. Package Organization</TD
|
| 69 |
|
|
><TD
|
| 70 |
|
|
WIDTH="10%"
|
| 71 |
|
|
ALIGN="right"
|
| 72 |
|
|
VALIGN="bottom"
|
| 73 |
|
|
><A
|
| 74 |
|
|
HREF="package.distrib.html"
|
| 75 |
|
|
ACCESSKEY="N"
|
| 76 |
|
|
>Next</A
|
| 77 |
|
|
></TD
|
| 78 |
|
|
></TR
|
| 79 |
|
|
></TABLE
|
| 80 |
|
|
><HR
|
| 81 |
|
|
ALIGN="LEFT"
|
| 82 |
|
|
WIDTH="100%"></DIV
|
| 83 |
|
|
><DIV
|
| 84 |
|
|
CLASS="SECT1"
|
| 85 |
|
|
><H1
|
| 86 |
|
|
CLASS="SECT1"
|
| 87 |
|
|
><A
|
| 88 |
|
|
NAME="PACKAGE.CONTENTS">Package Contents and Layout</H1
|
| 89 |
|
|
><P
|
| 90 |
|
|
>A typical package contains the following:</P
|
| 91 |
|
|
><P
|
| 92 |
|
|
></P
|
| 93 |
|
|
><OL
|
| 94 |
|
|
TYPE="1"
|
| 95 |
|
|
><LI
|
| 96 |
|
|
><P
|
| 97 |
|
|
>Some number of source files which will end up in a library. The
|
| 98 |
|
|
application code will be linked with this library to produce an
|
| 99 |
|
|
executable. Some source files may serve other purposes, for example to
|
| 100 |
|
|
provide a linker script.</P
|
| 101 |
|
|
></LI
|
| 102 |
|
|
><LI
|
| 103 |
|
|
><P
|
| 104 |
|
|
>Exported header files which define the interface provided by the
|
| 105 |
|
|
package. </P
|
| 106 |
|
|
></LI
|
| 107 |
|
|
><LI
|
| 108 |
|
|
><P
|
| 109 |
|
|
>On-line documentation, for example reference pages for each exported
|
| 110 |
|
|
function. </P
|
| 111 |
|
|
></LI
|
| 112 |
|
|
><LI
|
| 113 |
|
|
><P
|
| 114 |
|
|
>Some number of test cases, shipped in source format, allowing users to
|
| 115 |
|
|
check that the package is working as expected on their particular
|
| 116 |
|
|
hardware and in their specific configuration.</P
|
| 117 |
|
|
></LI
|
| 118 |
|
|
><LI
|
| 119 |
|
|
><P
|
| 120 |
|
|
>One or more <SPAN
|
| 121 |
|
|
CLASS="APPLICATION"
|
| 122 |
|
|
>CDL</SPAN
|
| 123 |
|
|
> scripts describing the package to the configuration
|
| 124 |
|
|
system.</P
|
| 125 |
|
|
></LI
|
| 126 |
|
|
></OL
|
| 127 |
|
|
><P
|
| 128 |
|
|
>It is also conventional to have a per-package
|
| 129 |
|
|
<TT
|
| 130 |
|
|
CLASS="FILENAME"
|
| 131 |
|
|
>ChangeLog</TT
|
| 132 |
|
|
> file used to keep track of changes to
|
| 133 |
|
|
that package. This is especially valuable to end users of the package
|
| 134 |
|
|
who may not have convenient access to the source code control system
|
| 135 |
|
|
used to manage the master copy of the package, and hence cannot find
|
| 136 |
|
|
out easily what has changed. Often it can be very useful to the main
|
| 137 |
|
|
developers as well.</P
|
| 138 |
|
|
><P
|
| 139 |
|
|
>Any given packages need not contain all of these. It is compulsory to
|
| 140 |
|
|
have at least one <SPAN
|
| 141 |
|
|
CLASS="APPLICATION"
|
| 142 |
|
|
>CDL</SPAN
|
| 143 |
|
|
> script describing the package, otherwise the
|
| 144 |
|
|
component framework would be unable to process it. Some packages may
|
| 145 |
|
|
not have any source code: it is possible to have a package that merely
|
| 146 |
|
|
defines a common interface which can then be implemented by several
|
| 147 |
|
|
other packages, especially in the context of device drivers; however
|
| 148 |
|
|
it is still common to have some code in such packages to avoid
|
| 149 |
|
|
replicating shareable code in all of the implementation packages.
|
| 150 |
|
|
Similarly it is possible to have a package with no exported header
|
| 151 |
|
|
files, just source code that implements an existing interface: for
|
| 152 |
|
|
example an ethernet device driver might just implement a standard
|
| 153 |
|
|
interface and not provide any additional functionality. Packages do
|
| 154 |
|
|
not need to come with any on-line documentation, although this may
|
| 155 |
|
|
affect how many people will want to use the package. Much the same
|
| 156 |
|
|
applies to per-package test cases.</P
|
| 157 |
|
|
><P
|
| 158 |
|
|
>The component framework has a recommended per-package directory layout
|
| 159 |
|
|
which splits the package contents on a functional basis:</P
|
| 160 |
|
|
><DIV
|
| 161 |
|
|
CLASS="INFORMALFIGURE"
|
| 162 |
|
|
><A
|
| 163 |
|
|
NAME="AEN302"><P
|
| 164 |
|
|
></P
|
| 165 |
|
|
><DIV
|
| 166 |
|
|
CLASS="MEDIAOBJECT"
|
| 167 |
|
|
><P
|
| 168 |
|
|
><IMG
|
| 169 |
|
|
SRC="package.png"
|
| 170 |
|
|
ALIGN="CENTER"></P
|
| 171 |
|
|
></DIV
|
| 172 |
|
|
><P
|
| 173 |
|
|
></P
|
| 174 |
|
|
></DIV
|
| 175 |
|
|
><P
|
| 176 |
|
|
>For example, if a package has an <TT
|
| 177 |
|
|
CLASS="FILENAME"
|
| 178 |
|
|
>include</TT
|
| 179 |
|
|
> sub-directory then the component
|
| 180 |
|
|
framework will assume that all header files in and below that
|
| 181 |
|
|
directory are exported header files and will do the right thing at
|
| 182 |
|
|
build time. Similarly if there is <SPAN
|
| 183 |
|
|
CLASS="PROPERTY"
|
| 184 |
|
|
>doc</SPAN
|
| 185 |
|
|
> property indicating the
|
| 186 |
|
|
location of on-line documentation then the component framework will
|
| 187 |
|
|
first look in the <TT
|
| 188 |
|
|
CLASS="FILENAME"
|
| 189 |
|
|
>doc</TT
|
| 190 |
|
|
>
|
| 191 |
|
|
sub-directory.</P
|
| 192 |
|
|
><P
|
| 193 |
|
|
>This directory layout is just a guideline, it is not enforced by the
|
| 194 |
|
|
component framework. For simple packages it often makes more sense to
|
| 195 |
|
|
have all of the files in just one directory. For example a package
|
| 196 |
|
|
could just contain the files <TT
|
| 197 |
|
|
CLASS="FILENAME"
|
| 198 |
|
|
>hello.cxx</TT
|
| 199 |
|
|
>,
|
| 200 |
|
|
<TT
|
| 201 |
|
|
CLASS="FILENAME"
|
| 202 |
|
|
>hello.h</TT
|
| 203 |
|
|
>, <TT
|
| 204 |
|
|
CLASS="FILENAME"
|
| 205 |
|
|
>hello.html</TT
|
| 206 |
|
|
> and
|
| 207 |
|
|
<TT
|
| 208 |
|
|
CLASS="FILENAME"
|
| 209 |
|
|
>hello.cdl</TT
|
| 210 |
|
|
>. By default
|
| 211 |
|
|
<TT
|
| 212 |
|
|
CLASS="FILENAME"
|
| 213 |
|
|
>hello.h</TT
|
| 214 |
|
|
> will be treated as an exported header
|
| 215 |
|
|
file, although this can be overridden with the <A
|
| 216 |
|
|
HREF="ref.include-files.html"
|
| 217 |
|
|
><SPAN
|
| 218 |
|
|
CLASS="PROPERTY"
|
| 219 |
|
|
>include_files</SPAN
|
| 220 |
|
|
></A
|
| 221 |
|
|
> property. Assuming
|
| 222 |
|
|
there is a <SPAN
|
| 223 |
|
|
CLASS="PROPERTY"
|
| 224 |
|
|
>doc</SPAN
|
| 225 |
|
|
> property referring to <TT
|
| 226 |
|
|
CLASS="FILENAME"
|
| 227 |
|
|
>hello.html</TT
|
| 228 |
|
|
>
|
| 229 |
|
|
and there is no <TT
|
| 230 |
|
|
CLASS="FILENAME"
|
| 231 |
|
|
>doc</TT
|
| 232 |
|
|
>
|
| 233 |
|
|
sub-directory then the tools will search for this file relative to the
|
| 234 |
|
|
package's top-level and everything will just work. Much the same
|
| 235 |
|
|
applies to <TT
|
| 236 |
|
|
CLASS="FILENAME"
|
| 237 |
|
|
>hello.cxx</TT
|
| 238 |
|
|
> and
|
| 239 |
|
|
<TT
|
| 240 |
|
|
CLASS="FILENAME"
|
| 241 |
|
|
>hello.cdl</TT
|
| 242 |
|
|
>. </P
|
| 243 |
|
|
><DIV
|
| 244 |
|
|
CLASS="TIP"
|
| 245 |
|
|
><BLOCKQUOTE
|
| 246 |
|
|
CLASS="TIP"
|
| 247 |
|
|
><P
|
| 248 |
|
|
><B
|
| 249 |
|
|
>Tip: </B
|
| 250 |
|
|
>Older versions of the <SPAN
|
| 251 |
|
|
CLASS="APPLICATION"
|
| 252 |
|
|
>eCos</SPAN
|
| 253 |
|
|
> build system only supported packages that
|
| 254 |
|
|
followed the directory structure exactly. Hence certain core packages
|
| 255 |
|
|
such as <TT
|
| 256 |
|
|
CLASS="FILENAME"
|
| 257 |
|
|
>error</TT
|
| 258 |
|
|
> implement the full directory
|
| 259 |
|
|
structure, even though that is a particularly simple package and the
|
| 260 |
|
|
full directory structure is inappropriate. Component writers can
|
| 261 |
|
|
decide for themselves whether or not the directory structure
|
| 262 |
|
|
guidelines are appropriate for their package.</P
|
| 263 |
|
|
></BLOCKQUOTE
|
| 264 |
|
|
></DIV
|
| 265 |
|
|
><DIV
|
| 266 |
|
|
CLASS="SECT2"
|
| 267 |
|
|
><H2
|
| 268 |
|
|
CLASS="SECT2"
|
| 269 |
|
|
><A
|
| 270 |
|
|
NAME="PACKAGE.BUILD">Outline of the Build Process</H2
|
| 271 |
|
|
><P
|
| 272 |
|
|
>The full build process is described in <A
|
| 273 |
|
|
HREF="build.html"
|
| 274 |
|
|
>Chapter 4</A
|
| 275 |
|
|
>, but
|
| 276 |
|
|
a summary is appropriate here. A build involves three directory
|
| 277 |
|
|
structures: </P
|
| 278 |
|
|
><P
|
| 279 |
|
|
></P
|
| 280 |
|
|
><OL
|
| 281 |
|
|
TYPE="1"
|
| 282 |
|
|
><LI
|
| 283 |
|
|
><P
|
| 284 |
|
|
>The component repository. This is where all the package source code is
|
| 285 |
|
|
held, along with <SPAN
|
| 286 |
|
|
CLASS="APPLICATION"
|
| 287 |
|
|
>CDL</SPAN
|
| 288 |
|
|
> scripts, documentation, and so on. For build
|
| 289 |
|
|
purposes a component repository is read-only. Application developers
|
| 290 |
|
|
will only modify the component repository when installing or removing
|
| 291 |
|
|
packages, via the administration tool. Component writers will
|
| 292 |
|
|
typically work on just one package in the component repository.</P
|
| 293 |
|
|
></LI
|
| 294 |
|
|
><LI
|
| 295 |
|
|
><P
|
| 296 |
|
|
>The build tree. Each configuration has its own build tree, which can
|
| 297 |
|
|
be regenerated at any time using the configuration's
|
| 298 |
|
|
<TT
|
| 299 |
|
|
CLASS="FILENAME"
|
| 300 |
|
|
>ecos.ecc</TT
|
| 301 |
|
|
> savefile. The build tree contains only
|
| 302 |
|
|
intermediate files, primarily object files. Once a build is complete
|
| 303 |
|
|
the build tree contains no information that is useful for application
|
| 304 |
|
|
development and can be wiped, although this would slow down any
|
| 305 |
|
|
rebuilds following changes to the configuration.</P
|
| 306 |
|
|
></LI
|
| 307 |
|
|
><LI
|
| 308 |
|
|
><P
|
| 309 |
|
|
>The install tree. This is populated during a build, and contains all
|
| 310 |
|
|
the files relevant to application development. There will be a
|
| 311 |
|
|
<TT
|
| 312 |
|
|
CLASS="FILENAME"
|
| 313 |
|
|
>lib</TT
|
| 314 |
|
|
> sub-directory which
|
| 315 |
|
|
typically contains <TT
|
| 316 |
|
|
CLASS="FILENAME"
|
| 317 |
|
|
>libtarget.a</TT
|
| 318 |
|
|
>, a linker script,
|
| 319 |
|
|
start-up code, and so on. There will also be an <TT
|
| 320 |
|
|
CLASS="FILENAME"
|
| 321 |
|
|
>include</TT
|
| 322 |
|
|
> sub-directory containing all the
|
| 323 |
|
|
header files exported by the various packages. There will also be a
|
| 324 |
|
|
<TT
|
| 325 |
|
|
CLASS="FILENAME"
|
| 326 |
|
|
>include/pkgconf</TT
|
| 327 |
|
|
> sub-directory
|
| 328 |
|
|
containing various configuration header files with
|
| 329 |
|
|
<TT
|
| 330 |
|
|
CLASS="LITERAL"
|
| 331 |
|
|
>#define's</TT
|
| 332 |
|
|
> for the options. Typically the install
|
| 333 |
|
|
tree is created within the build tree, but this is not a requirement.</P
|
| 334 |
|
|
></LI
|
| 335 |
|
|
></OL
|
| 336 |
|
|
><P
|
| 337 |
|
|
>The build process involves the following steps:</P
|
| 338 |
|
|
><P
|
| 339 |
|
|
></P
|
| 340 |
|
|
><OL
|
| 341 |
|
|
TYPE="1"
|
| 342 |
|
|
><LI
|
| 343 |
|
|
><P
|
| 344 |
|
|
>Given a configuration, the component framework is responsible for
|
| 345 |
|
|
creating all the directories in the build and install trees. If these
|
| 346 |
|
|
trees already exist then the component framework is responsible for
|
| 347 |
|
|
any clean-ups that may be necessary, for example if a package has been
|
| 348 |
|
|
removed then all related files should be expunged from the build and
|
| 349 |
|
|
install trees. The configuration header files will be generated at
|
| 350 |
|
|
this time. Depending on the host environment, the component framework
|
| 351 |
|
|
will also generate makefiles or some other way of building the various
|
| 352 |
|
|
packages. Every time the configuration is modified this step needs to
|
| 353 |
|
|
be repeated, to ensure that all option consequences take effect. Care
|
| 354 |
|
|
is taken that this will not result in unnecessary rebuilds.</P
|
| 355 |
|
|
><DIV
|
| 356 |
|
|
CLASS="NOTE"
|
| 357 |
|
|
><BLOCKQUOTE
|
| 358 |
|
|
CLASS="NOTE"
|
| 359 |
|
|
><P
|
| 360 |
|
|
><B
|
| 361 |
|
|
>Note: </B
|
| 362 |
|
|
>At present this step needs to be invoked manually. In a future version
|
| 363 |
|
|
the generated makefile may if desired perform this step automatically,
|
| 364 |
|
|
using a dependency on the <TT
|
| 365 |
|
|
CLASS="FILENAME"
|
| 366 |
|
|
>ecos.ecc</TT
|
| 367 |
|
|
> savefile.</P
|
| 368 |
|
|
></BLOCKQUOTE
|
| 369 |
|
|
></DIV
|
| 370 |
|
|
></LI
|
| 371 |
|
|
><LI
|
| 372 |
|
|
><P
|
| 373 |
|
|
>The first step in an actual build is to make sure that the install
|
| 374 |
|
|
tree contains all exported header files. All compilations will use
|
| 375 |
|
|
the install tree's <TT
|
| 376 |
|
|
CLASS="FILENAME"
|
| 377 |
|
|
>include</TT
|
| 378 |
|
|
>
|
| 379 |
|
|
directory as one of the places to search for header files.</P
|
| 380 |
|
|
></LI
|
| 381 |
|
|
><LI
|
| 382 |
|
|
><P
|
| 383 |
|
|
>All source files relevant to the current configuration get compiled.
|
| 384 |
|
|
This involves a set of compiler flags initialized on a per-target
|
| 385 |
|
|
basis, with each package being able to modify these flags, and with
|
| 386 |
|
|
the ability for the user to override the flags as well. Care has to be
|
| 387 |
|
|
taken here to avoid inappropriate target-dependencies in packages that
|
| 388 |
|
|
are intended to be portable. The component framework has built-in
|
| 389 |
|
|
knowledge of how to handle C, C++ and assembler source files —
|
| 390 |
|
|
other languages may be added in future, as and when necessary. The
|
| 391 |
|
|
<A
|
| 392 |
|
|
HREF="ref.compile.html"
|
| 393 |
|
|
><SPAN
|
| 394 |
|
|
CLASS="PROPERTY"
|
| 395 |
|
|
>compile</SPAN
|
| 396 |
|
|
></A
|
| 397 |
|
|
> property is used to
|
| 398 |
|
|
list the files that should get compiled. All object files end up in
|
| 399 |
|
|
the build tree.</P
|
| 400 |
|
|
></LI
|
| 401 |
|
|
><LI
|
| 402 |
|
|
><P
|
| 403 |
|
|
>Once all the object files have been built they are collected into a
|
| 404 |
|
|
library, typically <TT
|
| 405 |
|
|
CLASS="FILENAME"
|
| 406 |
|
|
>libtarget.a</TT
|
| 407 |
|
|
>, which can then be
|
| 408 |
|
|
linked with application code. The library is generated in the install
|
| 409 |
|
|
tree. </P
|
| 410 |
|
|
></LI
|
| 411 |
|
|
><LI
|
| 412 |
|
|
><P
|
| 413 |
|
|
>The component framework provides support for custom build steps, using
|
| 414 |
|
|
the <A
|
| 415 |
|
|
HREF="ref.make-object.html"
|
| 416 |
|
|
><SPAN
|
| 417 |
|
|
CLASS="PROPERTY"
|
| 418 |
|
|
>make_object</SPAN
|
| 419 |
|
|
></A
|
| 420 |
|
|
> and
|
| 421 |
|
|
<A
|
| 422 |
|
|
HREF="ref.make.html"
|
| 423 |
|
|
><SPAN
|
| 424 |
|
|
CLASS="PROPERTY"
|
| 425 |
|
|
>make</SPAN
|
| 426 |
|
|
></A
|
| 427 |
|
|
> properties. The results of
|
| 428 |
|
|
these custom build steps can either be object files that should end up
|
| 429 |
|
|
in a library, or other files such as a linker script. It is possible
|
| 430 |
|
|
to control the order in which these custom build steps take place, for
|
| 431 |
|
|
example it is possible to run a particular build step before any of
|
| 432 |
|
|
the compilations happen.</P
|
| 433 |
|
|
></LI
|
| 434 |
|
|
></OL
|
| 435 |
|
|
></DIV
|
| 436 |
|
|
><DIV
|
| 437 |
|
|
CLASS="SECT2"
|
| 438 |
|
|
><H2
|
| 439 |
|
|
CLASS="SECT2"
|
| 440 |
|
|
><A
|
| 441 |
|
|
NAME="PACKAGE.SOURCE">Configurable Source Code</H2
|
| 442 |
|
|
><P
|
| 443 |
|
|
>All packages should be totally portable to all target hardware (with
|
| 444 |
|
|
the obvious exceptions of HAL and device driver packages). They should
|
| 445 |
|
|
also be totally bug-free, require the absolute minimum amount of code
|
| 446 |
|
|
and data space, be so efficient that cpu time usage is negligible, and
|
| 447 |
|
|
provide lots of configuration options so that application developers
|
| 448 |
|
|
have full control over the behavior. The configuration options are
|
| 449 |
|
|
optional only if a package can meet the requirements of every
|
| 450 |
|
|
potential application without any overheads. It is not the purpose of
|
| 451 |
|
|
this guide to explain how to achieve all of these requirements.</P
|
| 452 |
|
|
><P
|
| 453 |
|
|
>The <SPAN
|
| 454 |
|
|
CLASS="APPLICATION"
|
| 455 |
|
|
>eCos</SPAN
|
| 456 |
|
|
> component framework does have some important implications
|
| 457 |
|
|
for the source code: compiler flag dependencies; package interfaces
|
| 458 |
|
|
vs. implementations; and how configuration options affect source code.</P
|
| 459 |
|
|
><DIV
|
| 460 |
|
|
CLASS="SECT3"
|
| 461 |
|
|
><H3
|
| 462 |
|
|
CLASS="SECT3"
|
| 463 |
|
|
><A
|
| 464 |
|
|
NAME="PACKAGE.SOURCE.FLAGS">Compiler Flag Dependencies</H3
|
| 465 |
|
|
><P
|
| 466 |
|
|
>Wherever possible component writers should avoid dependencies on
|
| 467 |
|
|
particular compiler flags. Any such dependencies are likely to impact
|
| 468 |
|
|
portability. For example, if one package needs to be built in
|
| 469 |
|
|
big-endian mode and another package needs to be built in little-endian
|
| 470 |
|
|
mode then usually it will not be possible for application developers
|
| 471 |
|
|
to use both packages at the same time; in addition the application
|
| 472 |
|
|
developer is no longer given a choice in the matter. It is far better
|
| 473 |
|
|
for the package source code to adapt the endianness at compile-time,
|
| 474 |
|
|
or possibly at run-time although that will involve code-size
|
| 475 |
|
|
overheads.</P
|
| 476 |
|
|
><DIV
|
| 477 |
|
|
CLASS="NOTE"
|
| 478 |
|
|
><BLOCKQUOTE
|
| 479 |
|
|
CLASS="NOTE"
|
| 480 |
|
|
><P
|
| 481 |
|
|
><B
|
| 482 |
|
|
>Note: </B
|
| 483 |
|
|
>A related issue is that the current support for handling compiler
|
| 484 |
|
|
flags in the component framework is still limited and incapable of
|
| 485 |
|
|
handling flags at a very fine-grain. The support is likely to be
|
| 486 |
|
|
enhanced in future versions of the framework, but there are
|
| 487 |
|
|
non-trivial problems to be resolved.</P
|
| 488 |
|
|
></BLOCKQUOTE
|
| 489 |
|
|
></DIV
|
| 490 |
|
|
></DIV
|
| 491 |
|
|
><DIV
|
| 492 |
|
|
CLASS="SECT3"
|
| 493 |
|
|
><H3
|
| 494 |
|
|
CLASS="SECT3"
|
| 495 |
|
|
><A
|
| 496 |
|
|
NAME="PACKAGE.SOURCE.INTERFACES">Package Interfaces and Implementations</H3
|
| 497 |
|
|
><P
|
| 498 |
|
|
>The component framework provides encapsulation at the package level. A
|
| 499 |
|
|
package <TT
|
| 500 |
|
|
CLASS="LITERAL"
|
| 501 |
|
|
>A</TT
|
| 502 |
|
|
> has no way of accessing the
|
| 503 |
|
|
implementation details of another package <TT
|
| 504 |
|
|
CLASS="LITERAL"
|
| 505 |
|
|
>B</TT
|
| 506 |
|
|
> at
|
| 507 |
|
|
compile-time. In particular, if there is a private header file
|
| 508 |
|
|
somewhere in a package's <TT
|
| 509 |
|
|
CLASS="FILENAME"
|
| 510 |
|
|
>src</TT
|
| 511 |
|
|
>
|
| 512 |
|
|
sub-directory then this header file is completely invisible to other
|
| 513 |
|
|
packages. Any attempts to cheat by using relative pathnames beginning
|
| 514 |
|
|
with <TT
|
| 515 |
|
|
CLASS="FILENAME"
|
| 516 |
|
|
>../..</TT
|
| 517 |
|
|
> are generally doomed
|
| 518 |
|
|
to failure because of the presence of package version directories.
|
| 519 |
|
|
There are two ways in which one package can affect another: by means
|
| 520 |
|
|
of the exported header files, which define a public interface; or via
|
| 521 |
|
|
the <SPAN
|
| 522 |
|
|
CLASS="APPLICATION"
|
| 523 |
|
|
>CDL</SPAN
|
| 524 |
|
|
> scripts.</P
|
| 525 |
|
|
><P
|
| 526 |
|
|
>This encapsulation is a deliberate aspect of the overall <SPAN
|
| 527 |
|
|
CLASS="APPLICATION"
|
| 528 |
|
|
>eCos</SPAN
|
| 529 |
|
|
>
|
| 530 |
|
|
component framework design. In most cases it does not cause any
|
| 531 |
|
|
problems for component writers. In some cases enforcing a clean
|
| 532 |
|
|
separation between interface and implementation details can improve
|
| 533 |
|
|
the code. Also it reduces problems when a package gets upgraded:
|
| 534 |
|
|
component writers are free to do pretty much anything on the
|
| 535 |
|
|
implementation side, including renaming every single source file; care
|
| 536 |
|
|
has to be taken only with the exported header files and with the <SPAN
|
| 537 |
|
|
CLASS="APPLICATION"
|
| 538 |
|
|
>CDL</SPAN
|
| 539 |
|
|
>
|
| 540 |
|
|
data, because those have the potential of impacting other packages.
|
| 541 |
|
|
Application code is similarly unable to access package implementation
|
| 542 |
|
|
details, only the exported interface.</P
|
| 543 |
|
|
><P
|
| 544 |
|
|
>Very occasionally the inability of one package to see implementation
|
| 545 |
|
|
details of another does cause problems. One example occurs in HAL
|
| 546 |
|
|
packages, where it may be desirable for the architectural, variant and
|
| 547 |
|
|
platform HAL's to share some information that should not be visible to
|
| 548 |
|
|
other packages or to application code. This may be addressed in the
|
| 549 |
|
|
future by introducing the concept of <TT
|
| 550 |
|
|
CLASS="LITERAL"
|
| 551 |
|
|
>friend</TT
|
| 552 |
|
|
>
|
| 553 |
|
|
packages, just as a C++ class can have <TT
|
| 554 |
|
|
CLASS="LITERAL"
|
| 555 |
|
|
>friend</TT
|
| 556 |
|
|
>
|
| 557 |
|
|
functions and classes which are allowed special access to a class
|
| 558 |
|
|
internals. It is not yet clear whether such cases are sufficiently
|
| 559 |
|
|
frequent to warrant introducing such a facility.</P
|
| 560 |
|
|
></DIV
|
| 561 |
|
|
><DIV
|
| 562 |
|
|
CLASS="SECT3"
|
| 563 |
|
|
><H3
|
| 564 |
|
|
CLASS="SECT3"
|
| 565 |
|
|
><A
|
| 566 |
|
|
NAME="PACKAGE.SOURCE.CONFIG">Source Code and Configuration Options</H3
|
| 567 |
|
|
><P
|
| 568 |
|
|
>Configurability usually involves source code that needs to implement
|
| 569 |
|
|
different behavior depending on the settings of configuration
|
| 570 |
|
|
options. It is possible to write packages where the only consequence
|
| 571 |
|
|
associated with various configuration options is to control what gets
|
| 572 |
|
|
built, but this approach is limited and does not allow for
|
| 573 |
|
|
fine-grained configurability. There are three main ways in which
|
| 574 |
|
|
options could affect source code at build time:</P
|
| 575 |
|
|
><P
|
| 576 |
|
|
></P
|
| 577 |
|
|
><OL
|
| 578 |
|
|
TYPE="1"
|
| 579 |
|
|
><LI
|
| 580 |
|
|
><P
|
| 581 |
|
|
>The component code can be passed through a suitable preprocessor,
|
| 582 |
|
|
either an existing one such as <SPAN
|
| 583 |
|
|
CLASS="APPLICATION"
|
| 584 |
|
|
>m4</SPAN
|
| 585 |
|
|
> or a new one specially designed with
|
| 586 |
|
|
configurability in mind. The original sources would reside in the
|
| 587 |
|
|
component repository and the processed sources would reside in the
|
| 588 |
|
|
build tree. These processed sources can then be compiled in the usual
|
| 589 |
|
|
way.</P
|
| 590 |
|
|
><P
|
| 591 |
|
|
>This approach has two main advantages. First, it is independent from
|
| 592 |
|
|
the programming language used to code the components, provided
|
| 593 |
|
|
reasonable precautions are taken to avoid syntax clashes between
|
| 594 |
|
|
preprocessor statements and actual code. This would make it easier in
|
| 595 |
|
|
future to support languages other than C and C++. Second, configurable
|
| 596 |
|
|
code can make use of advanced preprocessing facilities such as loops
|
| 597 |
|
|
and recursion. The disadvantage is that component writers would have
|
| 598 |
|
|
to learn about a new preprocessor and embed appropriate directives in
|
| 599 |
|
|
the code. This makes it much more difficult to turn existing code into
|
| 600 |
|
|
components, and it involves extra training costs for the component
|
| 601 |
|
|
writers.</P
|
| 602 |
|
|
></LI
|
| 603 |
|
|
><LI
|
| 604 |
|
|
><P
|
| 605 |
|
|
>Compiler optimizations can be used to elide code that should not be
|
| 606 |
|
|
present, for example:</P
|
| 607 |
|
|
><TABLE
|
| 608 |
|
|
BORDER="5"
|
| 609 |
|
|
BGCOLOR="#E0E0F0"
|
| 610 |
|
|
WIDTH="70%"
|
| 611 |
|
|
><TR
|
| 612 |
|
|
><TD
|
| 613 |
|
|
><PRE
|
| 614 |
|
|
CLASS="PROGRAMLISTING"
|
| 615 |
|
|
> …
|
| 616 |
|
|
if (CYGHWR_NUMBER_UARTS > 0) {
|
| 617 |
|
|
…
|
| 618 |
|
|
}
|
| 619 |
|
|
…</PRE
|
| 620 |
|
|
></TD
|
| 621 |
|
|
></TR
|
| 622 |
|
|
></TABLE
|
| 623 |
|
|
><P
|
| 624 |
|
|
>If the compiler knows that <TT
|
| 625 |
|
|
CLASS="VARNAME"
|
| 626 |
|
|
>CYGHWR_NUMBER_UARTS</TT
|
| 627 |
|
|
> is
|
| 628 |
|
|
the constant number 0 then it is a trivial operation to get rid of the
|
| 629 |
|
|
unnecessary code. The component framework still has to define this
|
| 630 |
|
|
symbol in a way that is acceptable to the compiler, typically by using
|
| 631 |
|
|
a <TT
|
| 632 |
|
|
CLASS="LITERAL"
|
| 633 |
|
|
>const</TT
|
| 634 |
|
|
> variable or a preprocessor symbol. In some
|
| 635 |
|
|
respects this is a clean approach to configurability, but it has
|
| 636 |
|
|
limitations. It cannot be used in the declarations of data structures
|
| 637 |
|
|
or classes, nor does it provide control over entire functions. In
|
| 638 |
|
|
addition it may not be immediately obvious that this code is affected
|
| 639 |
|
|
by configuration options, which may make it more difficult to
|
| 640 |
|
|
understand.</P
|
| 641 |
|
|
></LI
|
| 642 |
|
|
><LI
|
| 643 |
|
|
><P
|
| 644 |
|
|
>Existing language preprocessors can be used. In the case of C or C++
|
| 645 |
|
|
this would be the standard C preprocessor, and configurable code would
|
| 646 |
|
|
contain a number of <TT
|
| 647 |
|
|
CLASS="LITERAL"
|
| 648 |
|
|
>#ifdef</TT
|
| 649 |
|
|
> and
|
| 650 |
|
|
<TT
|
| 651 |
|
|
CLASS="LITERAL"
|
| 652 |
|
|
>#if</TT
|
| 653 |
|
|
> statements.</P
|
| 654 |
|
|
><TABLE
|
| 655 |
|
|
BORDER="5"
|
| 656 |
|
|
BGCOLOR="#E0E0F0"
|
| 657 |
|
|
WIDTH="70%"
|
| 658 |
|
|
><TR
|
| 659 |
|
|
><TD
|
| 660 |
|
|
><PRE
|
| 661 |
|
|
CLASS="PROGRAMLISTING"
|
| 662 |
|
|
>#if (CYGHWR_NUMBER_UARTS > 0)
|
| 663 |
|
|
…
|
| 664 |
|
|
#endif</PRE
|
| 665 |
|
|
></TD
|
| 666 |
|
|
></TR
|
| 667 |
|
|
></TABLE
|
| 668 |
|
|
><P
|
| 669 |
|
|
>This approach has the big advantage that the C preprocessor is a
|
| 670 |
|
|
technology that is both well-understood and widely used. There are
|
| 671 |
|
|
also disadvantages: it is not directly applicable to components
|
| 672 |
|
|
written in other languages such as Java (although it is possible to
|
| 673 |
|
|
use the C preprocessor as a stand-alone program); the preprocessing
|
| 674 |
|
|
facilities are rather limited, for example there is no looping
|
| 675 |
|
|
facility; and some people consider the technology to be ugly. Of
|
| 676 |
|
|
course it may be possible to get around the second objection by
|
| 677 |
|
|
extending the preprocessor that is used by gcc and g++.</P
|
| 678 |
|
|
></LI
|
| 679 |
|
|
></OL
|
| 680 |
|
|
><P
|
| 681 |
|
|
>The current component framework generates configuration header files
|
| 682 |
|
|
with C preprocessor <TT
|
| 683 |
|
|
CLASS="LITERAL"
|
| 684 |
|
|
>#define's</TT
|
| 685 |
|
|
> for each option
|
| 686 |
|
|
(typically, there various properties which can be used to control
|
| 687 |
|
|
this). It is up to component writers to decide whether to use
|
| 688 |
|
|
preprocessor <TT
|
| 689 |
|
|
CLASS="LITERAL"
|
| 690 |
|
|
>#ifdef</TT
|
| 691 |
|
|
> statements or language
|
| 692 |
|
|
constructs such as <TT
|
| 693 |
|
|
CLASS="LITERAL"
|
| 694 |
|
|
>if</TT
|
| 695 |
|
|
>. At present there is no
|
| 696 |
|
|
support for languages which do not involve the C preprocessor,
|
| 697 |
|
|
although such support can be added in future when the need arises.</P
|
| 698 |
|
|
></DIV
|
| 699 |
|
|
></DIV
|
| 700 |
|
|
><DIV
|
| 701 |
|
|
CLASS="SECT2"
|
| 702 |
|
|
><H2
|
| 703 |
|
|
CLASS="SECT2"
|
| 704 |
|
|
><A
|
| 705 |
|
|
NAME="PACKAGE.HEADERS">Exported Header Files</H2
|
| 706 |
|
|
><P
|
| 707 |
|
|
>A package's exported header files should specify the interface
|
| 708 |
|
|
provided by that package, and avoid any implementation details.
|
| 709 |
|
|
However there may be performance or other reasons why implementation
|
| 710 |
|
|
details occasionally need to be present in the exported headers.</P
|
| 711 |
|
|
><DIV
|
| 712 |
|
|
CLASS="NOTE"
|
| 713 |
|
|
><BLOCKQUOTE
|
| 714 |
|
|
CLASS="NOTE"
|
| 715 |
|
|
><P
|
| 716 |
|
|
><B
|
| 717 |
|
|
>Note: </B
|
| 718 |
|
|
>Not all programming languages have the concept of a header file. In
|
| 719 |
|
|
some cases the component framework would need extensions to support
|
| 720 |
|
|
packages written in such languages. </P
|
| 721 |
|
|
></BLOCKQUOTE
|
| 722 |
|
|
></DIV
|
| 723 |
|
|
><P
|
| 724 |
|
|
>Configurability has a number of effects on the way exported header
|
| 725 |
|
|
files should be written. There may be configuration options which
|
| 726 |
|
|
affect the interface of a package, not just the implementation. It is
|
| 727 |
|
|
necessary to worry about nested <TT
|
| 728 |
|
|
CLASS="LITERAL"
|
| 729 |
|
|
>#include's</TT
|
| 730 |
|
|
> and how
|
| 731 |
|
|
this affects package and application builds. A special case of this
|
| 732 |
|
|
relates to whether or not exported header files should
|
| 733 |
|
|
<TT
|
| 734 |
|
|
CLASS="LITERAL"
|
| 735 |
|
|
>#include</TT
|
| 736 |
|
|
> configuration headers. These configuration
|
| 737 |
|
|
headers are exported, but should only be <TT
|
| 738 |
|
|
CLASS="LITERAL"
|
| 739 |
|
|
>#include'd</TT
|
| 740 |
|
|
>
|
| 741 |
|
|
when necessary.</P
|
| 742 |
|
|
><DIV
|
| 743 |
|
|
CLASS="SECT3"
|
| 744 |
|
|
><H3
|
| 745 |
|
|
CLASS="SECT3"
|
| 746 |
|
|
><A
|
| 747 |
|
|
NAME="PACKAGE.HEADERS.FUNCTIONS">Configurable Functionality</H3
|
| 748 |
|
|
><P
|
| 749 |
|
|
>Many configuration options affect only the implementation of a
|
| 750 |
|
|
package, not the interface. However some options will affect the
|
| 751 |
|
|
interface as well, which means that the options have to be tested in
|
| 752 |
|
|
the exported header files. Some implementation choices, for example
|
| 753 |
|
|
whether or not a particular function should be inlined, also need to
|
| 754 |
|
|
be tested in the header file because of language limitations.</P
|
| 755 |
|
|
><P
|
| 756 |
|
|
>Consider a configuration option
|
| 757 |
|
|
<TT
|
| 758 |
|
|
CLASS="VARNAME"
|
| 759 |
|
|
>CYGFUN_KERNEL_MUTEX_TIMEDLOCK</TT
|
| 760 |
|
|
> which controls
|
| 761 |
|
|
whether or not a function <TT
|
| 762 |
|
|
CLASS="FUNCTION"
|
| 763 |
|
|
>cyg_mutex_timedlock</TT
|
| 764 |
|
|
> is
|
| 765 |
|
|
provided. The exported kernel header file <TT
|
| 766 |
|
|
CLASS="FILENAME"
|
| 767 |
|
|
>cyg/kernel/kapi.h</TT
|
| 768 |
|
|
> could contain the
|
| 769 |
|
|
following:</P
|
| 770 |
|
|
><TABLE
|
| 771 |
|
|
BORDER="5"
|
| 772 |
|
|
BGCOLOR="#E0E0F0"
|
| 773 |
|
|
WIDTH="70%"
|
| 774 |
|
|
><TR
|
| 775 |
|
|
><TD
|
| 776 |
|
|
><PRE
|
| 777 |
|
|
CLASS="PROGRAMLISTING"
|
| 778 |
|
|
>#include <pkgconf/kernel.h>
|
| 779 |
|
|
…
|
| 780 |
|
|
#ifdef CYGFUN_KERNEL_MUTEX_TIMEDLOCK
|
| 781 |
|
|
extern bool cyg_mutex_timedlock(cyg_mutex_t*);
|
| 782 |
|
|
#endif</PRE
|
| 783 |
|
|
></TD
|
| 784 |
|
|
></TR
|
| 785 |
|
|
></TABLE
|
| 786 |
|
|
><P
|
| 787 |
|
|
>This is a correct header file, in that it defines the exact interface
|
| 788 |
|
|
provided by the package at all times. However is has a number of
|
| 789 |
|
|
implications. First, the header file is now dependent on <TT
|
| 790 |
|
|
CLASS="FILENAME"
|
| 791 |
|
|
>pkgconf/kernel.h</TT
|
| 792 |
|
|
>, so any changes to
|
| 793 |
|
|
kernel configuration options will cause <TT
|
| 794 |
|
|
CLASS="FILENAME"
|
| 795 |
|
|
>cyg/kernel/kapi.h</TT
|
| 796 |
|
|
> to be out of date, and
|
| 797 |
|
|
any source files that use the kernel interface will need rebuilding.
|
| 798 |
|
|
This may affect sources in the kernel package, in other packages, and
|
| 799 |
|
|
in application source code. Second, if the application makes use of
|
| 800 |
|
|
this function somewhere but the application developer has
|
| 801 |
|
|
misconfigured the system and disabled this functionality anyway then
|
| 802 |
|
|
there will now be a compile-time error when building the application.
|
| 803 |
|
|
Note that other packages should not be affected, since they should
|
| 804 |
|
|
impose appropriate constraints on
|
| 805 |
|
|
<TT
|
| 806 |
|
|
CLASS="VARNAME"
|
| 807 |
|
|
>CYGFUN_KERNEL_MUTEX_TIMEDLOCK</TT
|
| 808 |
|
|
> if they use that
|
| 809 |
|
|
functionality (although of course some dependencies like this may get
|
| 810 |
|
|
missed by component developers).</P
|
| 811 |
|
|
><P
|
| 812 |
|
|
>An alternative approach would be:</P
|
| 813 |
|
|
><TABLE
|
| 814 |
|
|
BORDER="5"
|
| 815 |
|
|
BGCOLOR="#E0E0F0"
|
| 816 |
|
|
WIDTH="70%"
|
| 817 |
|
|
><TR
|
| 818 |
|
|
><TD
|
| 819 |
|
|
><PRE
|
| 820 |
|
|
CLASS="PROGRAMLISTING"
|
| 821 |
|
|
>extern bool cyg_mutex_timedlock(cyg_mutex_t*);</PRE
|
| 822 |
|
|
></TD
|
| 823 |
|
|
></TR
|
| 824 |
|
|
></TABLE
|
| 825 |
|
|
><P
|
| 826 |
|
|
>Effectively the header file is now lying about the functionality
|
| 827 |
|
|
provided by the package. The first result is that there is no longer a
|
| 828 |
|
|
dependency on the kernel configuration header. The second result is
|
| 829 |
|
|
that an application file using the timed-lock function will now
|
| 830 |
|
|
compile, but the application will fail to link. At this stage the
|
| 831 |
|
|
application developer still has to intervene, change the
|
| 832 |
|
|
configuration, and rebuild the system. However no application
|
| 833 |
|
|
recompilations are necessary, just a relink.</P
|
| 834 |
|
|
><P
|
| 835 |
|
|
>Theoretically it would be possible for a tool to analyze linker errors
|
| 836 |
|
|
and suggest possible configuration changes that would resolve the
|
| 837 |
|
|
problem, reducing the burden on the application developer. No such
|
| 838 |
|
|
tool is planned in the short term.</P
|
| 839 |
|
|
><P
|
| 840 |
|
|
>It is up to component writers to decide which of these two approaches
|
| 841 |
|
|
should be preferred. Note that it is not always possible to avoid
|
| 842 |
|
|
<TT
|
| 843 |
|
|
CLASS="LITERAL"
|
| 844 |
|
|
>#include'ing</TT
|
| 845 |
|
|
> a configuration header file in an
|
| 846 |
|
|
exported one, for example an option may affect a data structure rather
|
| 847 |
|
|
than just the presence or absence of a function. Issues like this will
|
| 848 |
|
|
vary from package to package.</P
|
| 849 |
|
|
></DIV
|
| 850 |
|
|
><DIV
|
| 851 |
|
|
CLASS="SECT3"
|
| 852 |
|
|
><H3
|
| 853 |
|
|
CLASS="SECT3"
|
| 854 |
|
|
><A
|
| 855 |
|
|
NAME="PACKAGE.HEADERS.INCLUDES">Nested <TT
|
| 856 |
|
|
CLASS="LITERAL"
|
| 857 |
|
|
>#include's</TT
|
| 858 |
|
|
></H3
|
| 859 |
|
|
><P
|
| 860 |
|
|
>As a general rule, unnecessary <TT
|
| 861 |
|
|
CLASS="LITERAL"
|
| 862 |
|
|
>#include's</TT
|
| 863 |
|
|
> should be
|
| 864 |
|
|
avoided. A header file should <TT
|
| 865 |
|
|
CLASS="LITERAL"
|
| 866 |
|
|
>#include</TT
|
| 867 |
|
|
> only those
|
| 868 |
|
|
header files which are absolutely needed for it to define its
|
| 869 |
|
|
interface. Any additional <TT
|
| 870 |
|
|
CLASS="LITERAL"
|
| 871 |
|
|
>#include's</TT
|
| 872 |
|
|
> make it more
|
| 873 |
|
|
likely that package or application source files become dependent on
|
| 874 |
|
|
configuration header files and will get rebuilt unnecessarily when
|
| 875 |
|
|
there are minor configuration changes.</P
|
| 876 |
|
|
></DIV
|
| 877 |
|
|
><DIV
|
| 878 |
|
|
CLASS="SECT3"
|
| 879 |
|
|
><H3
|
| 880 |
|
|
CLASS="SECT3"
|
| 881 |
|
|
><A
|
| 882 |
|
|
NAME="PACKAGE.HEADERS.CONFIGINCLUDES">Including Configuration Headers</H3
|
| 883 |
|
|
><P
|
| 884 |
|
|
>Exported header files should avoid <TT
|
| 885 |
|
|
CLASS="LITERAL"
|
| 886 |
|
|
>#include'ing</TT
|
| 887 |
|
|
>
|
| 888 |
|
|
configuration header files unless absolutely necessary, to avoid
|
| 889 |
|
|
unnecessary rebuilding of both application code and other packages
|
| 890 |
|
|
when there are minor configuration changes. A
|
| 891 |
|
|
<TT
|
| 892 |
|
|
CLASS="LITERAL"
|
| 893 |
|
|
>#include</TT
|
| 894 |
|
|
> is needed only when a configuration option
|
| 895 |
|
|
affects the exported interface, or when it affects some implementation
|
| 896 |
|
|
details which is controlled by the header file such as whether or not
|
| 897 |
|
|
a particular function gets inlined.</P
|
| 898 |
|
|
><P
|
| 899 |
|
|
>There are a couple of ways in which the problem of unnecessary
|
| 900 |
|
|
rebuilding could be addressed. The first would require more
|
| 901 |
|
|
intelligent handling of header file dependency handling by the tools
|
| 902 |
|
|
(especially the compiler) and the build system. This would require
|
| 903 |
|
|
changes to various non-eCos tools. An alternative approach would be to
|
| 904 |
|
|
support finer-grained configuration header files, for example there
|
| 905 |
|
|
could be a file <TT
|
| 906 |
|
|
CLASS="FILENAME"
|
| 907 |
|
|
>pkgconf/libc/inline.h</TT
|
| 908 |
|
|
> controlling which
|
| 909 |
|
|
functions should be inlined. This could be achieved by some fairly
|
| 910 |
|
|
simple extensions to the component framework, but it makes it more
|
| 911 |
|
|
difficult to get the package header files and source code correct:
|
| 912 |
|
|
a C preprocessor <TT
|
| 913 |
|
|
CLASS="LITERAL"
|
| 914 |
|
|
>#ifdef</TT
|
| 915 |
|
|
> directive does not
|
| 916 |
|
|
distinguish between a symbol not being defined because the option is
|
| 917 |
|
|
disabled, or the symbol not being defined because the appropriate
|
| 918 |
|
|
configuration header file has not been <TT
|
| 919 |
|
|
CLASS="LITERAL"
|
| 920 |
|
|
>#include'd</TT
|
| 921 |
|
|
>.
|
| 922 |
|
|
It is likely that a cross-referencing tool would have to be developed
|
| 923 |
|
|
first to catch problems like this, before the component framework
|
| 924 |
|
|
could support finer-grained configuration headers.</P
|
| 925 |
|
|
></DIV
|
| 926 |
|
|
></DIV
|
| 927 |
|
|
><DIV
|
| 928 |
|
|
CLASS="SECT2"
|
| 929 |
|
|
><H2
|
| 930 |
|
|
CLASS="SECT2"
|
| 931 |
|
|
><A
|
| 932 |
|
|
NAME="PACKAGE.DOCUMENTATION">Package Documentation</H2
|
| 933 |
|
|
><P
|
| 934 |
|
|
>On-line package documentation should be in HTML format. The component
|
| 935 |
|
|
framework imposes no special limitations: component writers can decide
|
| 936 |
|
|
which version of the HTML specification should be followed; they can
|
| 937 |
|
|
also decide on how best to cope with the limitations of different
|
| 938 |
|
|
browsers. In general it is a good idea to keep things simple.</P
|
| 939 |
|
|
></DIV
|
| 940 |
|
|
><DIV
|
| 941 |
|
|
CLASS="SECT2"
|
| 942 |
|
|
><H2
|
| 943 |
|
|
CLASS="SECT2"
|
| 944 |
|
|
><A
|
| 945 |
|
|
NAME="PACKAGE.TESTS">Test Cases</H2
|
| 946 |
|
|
><P
|
| 947 |
|
|
>Packages should normally come with one or more test cases. This allows
|
| 948 |
|
|
application developers to verify that a given package works correctly
|
| 949 |
|
|
on their particular hardware and in their particular configuration,
|
| 950 |
|
|
making it slightly more likely that they will attempt to find bugs in
|
| 951 |
|
|
their own code rather than automatically blaming the component
|
| 952 |
|
|
writers.</P
|
| 953 |
|
|
><P
|
| 954 |
|
|
>At the time of writing the application developer support for building
|
| 955 |
|
|
and running test cases via the component framework is under review and
|
| 956 |
|
|
likely to change. Currently each test case should consist of a single
|
| 957 |
|
|
C or C++ source file that can be compiled with the package's set of
|
| 958 |
|
|
compiler flags and linked like any application program. Each test case
|
| 959 |
|
|
should use the testing API defined by the infrastructure. A
|
| 960 |
|
|
magically-named calculated configuration option of the form
|
| 961 |
|
|
<TT
|
| 962 |
|
|
CLASS="VARNAME"
|
| 963 |
|
|
>CYGPKG_<PACKAGE-NAME>_TESTS</TT
|
| 964 |
|
|
> lists the test
|
| 965 |
|
|
cases.</P
|
| 966 |
|
|
></DIV
|
| 967 |
|
|
><DIV
|
| 968 |
|
|
CLASS="SECT2"
|
| 969 |
|
|
><H2
|
| 970 |
|
|
CLASS="SECT2"
|
| 971 |
|
|
><A
|
| 972 |
|
|
NAME="PACKAGE.HOST">Host-side Support</H2
|
| 973 |
|
|
><P
|
| 974 |
|
|
>On occasion it would be useful for an <SPAN
|
| 975 |
|
|
CLASS="APPLICATION"
|
| 976 |
|
|
>eCos</SPAN
|
| 977 |
|
|
> package to be shipped
|
| 978 |
|
|
with host-side support. This could take the form of an additional tool
|
| 979 |
|
|
needed to build that package. It could be an application intended to
|
| 980 |
|
|
communicate with the target-side package code and display monitoring
|
| 981 |
|
|
information. It could be a utility needed for running the package test
|
| 982 |
|
|
cases, especially in the case of device drivers. The component
|
| 983 |
|
|
framework does not yet provide any such support for host-side
|
| 984 |
|
|
software, and there are obvious issues related to portability to the
|
| 985 |
|
|
different machines that can be used for hosts. This issue may get
|
| 986 |
|
|
addressed in some future release. In some cases custom build steps can
|
| 987 |
|
|
be subverted to do things on the host side rather than the target
|
| 988 |
|
|
side, but this is not recommended.</P
|
| 989 |
|
|
></DIV
|
| 990 |
|
|
></DIV
|
| 991 |
|
|
><DIV
|
| 992 |
|
|
CLASS="NAVFOOTER"
|
| 993 |
|
|
><HR
|
| 994 |
|
|
ALIGN="LEFT"
|
| 995 |
|
|
WIDTH="100%"><TABLE
|
| 996 |
|
|
SUMMARY="Footer navigation table"
|
| 997 |
|
|
WIDTH="100%"
|
| 998 |
|
|
BORDER="0"
|
| 999 |
|
|
CELLPADDING="0"
|
| 1000 |
|
|
CELLSPACING="0"
|
| 1001 |
|
|
><TR
|
| 1002 |
|
|
><TD
|
| 1003 |
|
|
WIDTH="33%"
|
| 1004 |
|
|
ALIGN="left"
|
| 1005 |
|
|
VALIGN="top"
|
| 1006 |
|
|
><A
|
| 1007 |
|
|
HREF="package.versions.html"
|
| 1008 |
|
|
ACCESSKEY="P"
|
| 1009 |
|
|
>Prev</A
|
| 1010 |
|
|
></TD
|
| 1011 |
|
|
><TD
|
| 1012 |
|
|
WIDTH="34%"
|
| 1013 |
|
|
ALIGN="center"
|
| 1014 |
|
|
VALIGN="top"
|
| 1015 |
|
|
><A
|
| 1016 |
|
|
HREF="cdl-guide.html"
|
| 1017 |
|
|
ACCESSKEY="H"
|
| 1018 |
|
|
>Home</A
|
| 1019 |
|
|
></TD
|
| 1020 |
|
|
><TD
|
| 1021 |
|
|
WIDTH="33%"
|
| 1022 |
|
|
ALIGN="right"
|
| 1023 |
|
|
VALIGN="top"
|
| 1024 |
|
|
><A
|
| 1025 |
|
|
HREF="package.distrib.html"
|
| 1026 |
|
|
ACCESSKEY="N"
|
| 1027 |
|
|
>Next</A
|
| 1028 |
|
|
></TD
|
| 1029 |
|
|
></TR
|
| 1030 |
|
|
><TR
|
| 1031 |
|
|
><TD
|
| 1032 |
|
|
WIDTH="33%"
|
| 1033 |
|
|
ALIGN="left"
|
| 1034 |
|
|
VALIGN="top"
|
| 1035 |
|
|
>Package Versioning</TD
|
| 1036 |
|
|
><TD
|
| 1037 |
|
|
WIDTH="34%"
|
| 1038 |
|
|
ALIGN="center"
|
| 1039 |
|
|
VALIGN="top"
|
| 1040 |
|
|
><A
|
| 1041 |
|
|
HREF="package.html"
|
| 1042 |
|
|
ACCESSKEY="U"
|
| 1043 |
|
|
>Up</A
|
| 1044 |
|
|
></TD
|
| 1045 |
|
|
><TD
|
| 1046 |
|
|
WIDTH="33%"
|
| 1047 |
|
|
ALIGN="right"
|
| 1048 |
|
|
VALIGN="top"
|
| 1049 |
|
|
>Making a Package Distribution</TD
|
| 1050 |
|
|
></TR
|
| 1051 |
|
|
></TABLE
|
| 1052 |
|
|
></DIV
|
| 1053 |
|
|
></BODY
|
| 1054 |
|
|
></HTML
|
| 1055 |
|
|
>
|
