1 <!-- 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. -->
12 >Package Contents and Layout</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="The eCos Component Writer's Guide"
20 HREF="cdl-guide.html"><LINK
22 TITLE="Package Organization"
23 HREF="package.html"><LINK
25 TITLE="Package Versioning"
26 HREF="package.versions.html"><LINK
28 TITLE="Making a Package Distribution"
29 HREF="package.distrib.html"></HEAD
40 SUMMARY="Header navigation table"
52 > Component Writer's Guide</TH
60 HREF="package.versions.html"
68 >Chapter 2. Package Organization</TD
74 HREF="package.distrib.html"
88 NAME="PACKAGE.CONTENTS">Package Contents and Layout</H1
90 >A typical package contains the following:</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
104 >Exported header files which define the interface provided by the
109 >On-line documentation, for example reference pages for each exported
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
123 > scripts describing the package to the configuration
128 >It is also conventional to have a per-package
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
139 >Any given packages need not contain all of these. It is compulsory to
140 have at least one <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
158 >The component framework has a recommended per-package directory layout
159 which splits the package contents on a functional basis:</P
161 CLASS="INFORMALFIGURE"
176 >For example, if a package has an <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
185 > property indicating the
186 location of on-line documentation then the component framework will
187 first look in the <TT
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
214 > will be treated as an exported header
215 file, although this can be overridden with the <A
216 HREF="ref.include-files.html"
225 > property referring to <TT
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
250 >Older versions of the <SPAN
253 > build system only supported packages that
254 followed the directory structure exactly. Hence certain core packages
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
270 NAME="PACKAGE.BUILD">Outline of the Build Process</H2
272 >The full build process is described in <A
276 a summary is appropriate here. A build involves three directory
284 >The component repository. This is where all the package source code is
285 held, along with <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
296 >The build tree. Each configuration has its own build tree, which can
297 be regenerated at any time using the configuration's
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
309 >The install tree. This is populated during a build, and contains all
310 the files relevant to application development. There will be a
314 > sub-directory which
315 typically contains <TT
319 start-up code, and so on. There will also be an <TT
322 > sub-directory containing all the
323 header files exported by the various packages. There will also be a
328 containing various configuration header files with
332 > for the options. Typically the install
333 tree is created within the build tree, but this is not a requirement.</P
337 >The build process involves the following steps:</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
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
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
379 directory as one of the places to search for header files.</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
392 HREF="ref.compile.html"
397 > property is used to
398 list the files that should get compiled. All object files end up in
403 >Once all the object files have been built they are collected into a
404 library, typically <TT
408 linked with application code. The library is generated in the install
413 >The component framework provides support for custom build steps, using
415 HREF="ref.make-object.html"
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
441 NAME="PACKAGE.SOURCE">Configurable Source Code</H2
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
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
464 NAME="PACKAGE.SOURCE.FLAGS">Compiler Flag Dependencies</H3
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
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
496 NAME="PACKAGE.SOURCE.INTERFACES">Package Interfaces and Implementations</H3
498 >The component framework provides encapsulation at the package level. A
502 > has no way of accessing the
503 implementation details of another package <TT
507 compile-time. In particular, if there is a private header file
508 somewhere in a package's <TT
512 sub-directory then this header file is completely invisible to other
513 packages. Any attempts to cheat by using relative pathnames beginning
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
526 >This encapsulation is a deliberate aspect of the overall <SPAN
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
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
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
553 packages, just as a C++ class can have <TT
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
566 NAME="PACKAGE.SOURCE.CONFIG">Source Code and Configuration Options</H3
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
581 >The component code can be passed through a suitable preprocessor,
582 either an existing one such as <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
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
605 >Compiler optimizations can be used to elide code that should not be
606 present, for example:</P
614 CLASS="PROGRAMLISTING"
616 if (CYGHWR_NUMBER_UARTS > 0) {
624 >If the compiler knows that <TT
626 >CYGHWR_NUMBER_UARTS</TT
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
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
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
661 CLASS="PROGRAMLISTING"
662 >#if (CYGHWR_NUMBER_UARTS > 0)
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
681 >The current component framework generates configuration header files
682 with C preprocessor <TT
686 (typically, there various properties which can be used to control
687 this). It is up to component writers to decide whether to use
691 > statements or language
692 constructs such as <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
705 NAME="PACKAGE.HEADERS">Exported Header Files</H2
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
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
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
731 this affects package and application builds. A special case of this
732 relates to whether or not exported header files should
736 > configuration headers. These configuration
737 headers are exported, but should only be <TT
747 NAME="PACKAGE.HEADERS.FUNCTIONS">Configurable Functionality</H3
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
756 >Consider a configuration option
759 >CYGFUN_KERNEL_MUTEX_TIMEDLOCK</TT
761 whether or not a function <TT
763 >cyg_mutex_timedlock</TT
765 provided. The exported kernel header file <TT
767 >cyg/kernel/kapi.h</TT
777 CLASS="PROGRAMLISTING"
778 >#include <pkgconf/kernel.h>
780 #ifdef CYGFUN_KERNEL_MUTEX_TIMEDLOCK
781 extern bool cyg_mutex_timedlock(cyg_mutex_t*);
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
791 >pkgconf/kernel.h</TT
793 kernel configuration options will cause <TT
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
807 >CYGFUN_KERNEL_MUTEX_TIMEDLOCK</TT
809 functionality (although of course some dependencies like this may get
810 missed by component developers).</P
812 >An alternative approach would be:</P
820 CLASS="PROGRAMLISTING"
821 >extern bool cyg_mutex_timedlock(cyg_mutex_t*);</PRE
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
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
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
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
855 NAME="PACKAGE.HEADERS.INCLUDES">Nested <TT
860 >As a general rule, unnecessary <TT
864 avoided. A header file should <TT
868 header files which are absolutely needed for it to define its
869 interface. Any additional <TT
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
882 NAME="PACKAGE.HEADERS.CONFIGINCLUDES">Including Configuration Headers</H3
884 >Exported header files should avoid <TT
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
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
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
907 >pkgconf/libc/inline.h</TT
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:
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
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
932 NAME="PACKAGE.DOCUMENTATION">Package Documentation</H2
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
945 NAME="PACKAGE.TESTS">Test Cases</H2
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
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
963 >CYGPKG_<PACKAGE-NAME>_TESTS</TT
972 NAME="PACKAGE.HOST">Host-side Support</H2
974 >On occasion it would be useful for an <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
996 SUMMARY="Footer navigation table"
1007 HREF="package.versions.html"
1016 HREF="cdl-guide.html"
1025 HREF="package.distrib.html"
1035 >Package Versioning</TD
1049 >Making a Package Distribution</TD
projects / karo-tx-redboot.git / blob