OpenCores
URL https://opencores.org/ocsvn/openrisc_2011-10-31/openrisc_2011-10-31/trunk

Subversion Repositories openrisc_2011-10-31

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [cdl-guide/] [package.contents.html] - Blame information for rev 369

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
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 &#8212;
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 
>    &#8230;
616 
    if (CYGHWR_NUMBER_UARTS &gt; 0) {
617 
        &#8230;
618 
     }
619 
    &#8230;</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 &gt; 0)
663 
     &#8230;
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 &lt;pkgconf/kernel.h&gt;
779 
&#8230;
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_&lt;PACKAGE-NAME&gt;_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 
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.