OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

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

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.