 | build 3.0.0.201402161939 |
| build 3.0.0.201402161939 |
A typical package contains the following:
Some number of source files which will end up in a library. The application code will be linked with this library to produce an executable. Some source files may serve other purposes, for example to provide a linker script.
Exported header files which define the interface provided by the package.
On-line documentation, for example reference pages for each exported function.
Some number of test cases, shipped in source format, allowing users to check that the package is working as expected on their particular hardware and in their specific configuration.
One or more CDL scripts describing the package to the configuration system.
It is also conventional to have a per-package ChangeLog file used to keep track of changes to that package. This is especially valuable to end users of the package who may not have convenient access to the source code control system used to manage the master copy of the package, and hence cannot find out easily what has changed. Often it can be very useful to the main developers as well.
Any given packages need not contain all of these. It is compulsory to have at least one CDL script describing the package, otherwise the component framework would be unable to process it. Some packages may not have any source code: it is possible to have a package that merely defines a common interface which can then be implemented by several other packages, especially in the context of device drivers; however it is still common to have some code in such packages to avoid replicating shareable code in all of the implementation packages. Similarly it is possible to have a package with no exported header files, just source code that implements an existing interface: for example an ethernet device driver might just implement a standard interface and not provide any additional functionality. Packages do not need to come with any on-line documentation, although this may affect how many people will want to use the package. Much the same applies to per-package test cases.
The component framework has a recommended per-package directory layout which splits the package contents on a functional basis:
For example, if a package has an include sub-directory then the component framework will assume that all header files in and below that directory are exported header files and will do the right thing at build time. Similarly if there is doc property indicating the location of on-line documentation then the component framework will first look in the doc sub-directory.
This directory layout is just a guideline, it is not enforced by the component framework. For simple packages it often makes more sense to have all of the files in just one directory. For example a package could just contain the files hello.cxx, hello.h, hello.html and hello.cdl. By default hello.h will be treated as an exported header file, although this can be overridden with the include_files property. Assuming there is a doc property referring to hello.html and there is no doc sub-directory then the tools will search for this file relative to the package's top-level and everything will just work. Much the same applies to hello.cxx and hello.cdl.
Tip: Older versions of the eCos build system only supported packages that followed the directory structure exactly. Hence certain core packages such as error implement the full directory structure, even though that is a particularly simple package and the full directory structure is inappropriate. Component writers can decide for themselves whether or not the directory structure guidelines are appropriate for their package.
The full build process is described in Chapter 4, but a summary is appropriate here. A build involves three directory structures:
The component repository. This is where all the package source code is held, along with CDL scripts, documentation, and so on. For build purposes a component repository is read-only. Application developers will only modify the component repository when installing or removing packages, via the administration tool. Component writers will typically work on just one package in the component repository.
The build tree. Each configuration has its own build tree, which can be regenerated at any time using the configuration's ecos.ecc savefile. The build tree contains only intermediate files, primarily object files. Once a build is complete the build tree contains no information that is useful for application development and can be wiped, although this would slow down any rebuilds following changes to the configuration.
The install tree. This is populated during a build, and contains all the files relevant to application development. There will be a lib sub-directory which typically contains libtarget.a, a linker script, start-up code, and so on. There will also be an include sub-directory containing all the header files exported by the various packages. There will also be a include/pkgconf sub-directory containing various configuration header files with #define's for the options. Typically the install tree is created within the build tree, but this is not a requirement.
The build process involves the following steps:
Given a configuration, the component framework is responsible for creating all the directories in the build and install trees. If these trees already exist then the component framework is responsible for any clean-ups that may be necessary, for example if a package has been removed then all related files should be expunged from the build and install trees. The configuration header files will be generated at this time. Depending on the host environment, the component framework will also generate makefiles or some other way of building the various packages. Every time the configuration is modified this step needs to be repeated, to ensure that all option consequences take effect. Care is taken that this will not result in unnecessary rebuilds.
Note: At present this step needs to be invoked manually. In a future version the generated makefile may if desired perform this step automatically, using a dependency on the ecos.ecc savefile.
The first step in an actual build is to make sure that the install tree contains all exported header files. All compilations will use the install tree's include directory as one of the places to search for header files.
All source files relevant to the current configuration get compiled. This involves a set of compiler flags initialized on a per-target basis, with each package being able to modify these flags, and with the ability for the user to override the flags as well. Care has to be taken here to avoid inappropriate target-dependencies in packages that are intended to be portable. The component framework has built-in knowledge of how to handle C, C++ and assembler source files — other languages may be added in future, as and when necessary. The compile property is used to list the files that should get compiled. All object files end up in the build tree.
Once all the object files have been built they are collected into a library, typically libtarget.a, which can then be linked with application code. The library is generated in the install tree.
The component framework provides support for custom build steps, using the make_object and make properties. The results of these custom build steps can either be object files that should end up in a library, or other files such as a linker script. It is possible to control the order in which these custom build steps take place, for example it is possible to run a particular build step before any of the compilations happen.
All packages should be totally portable to all target hardware (with the obvious exceptions of HAL and device driver packages). They should also be totally bug-free, require the absolute minimum amount of code and data space, be so efficient that cpu time usage is negligible, and provide lots of configuration options so that application developers have full control over the behavior. The configuration options are optional only if a package can meet the requirements of every potential application without any overheads. It is not the purpose of this guide to explain how to achieve all of these requirements.
The eCos component framework does have some important implications for the source code: compiler flag dependencies; package interfaces vs. implementations; and how configuration options affect source code.
Wherever possible component writers should avoid dependencies on particular compiler flags. Any such dependencies are likely to impact portability. For example, if one package needs to be built in big-endian mode and another package needs to be built in little-endian mode then usually it will not be possible for application developers to use both packages at the same time; in addition the application developer is no longer given a choice in the matter. It is far better for the package source code to adapt the endianness at compile-time, or possibly at run-time although that will involve code-size overheads.
Note: A related issue is that the current support for handling compiler flags in the component framework is still limited and incapable of handling flags at a very fine-grain. The support is likely to be enhanced in future versions of the framework, but there are non-trivial problems to be resolved.
The component framework provides encapsulation at the package level. A package A has no way of accessing the implementation details of another package B at compile-time. In particular, if there is a private header file somewhere in a package's src sub-directory then this header file is completely invisible to other packages. Any attempts to cheat by using relative pathnames beginning with ../.. are generally doomed to failure because of the presence of package version directories. There are two ways in which one package can affect another: by means of the exported header files, which define a public interface; or via the CDL scripts.
This encapsulation is a deliberate aspect of the overall eCos component framework design. In most cases it does not cause any problems for component writers. In some cases enforcing a clean separation between interface and implementation details can improve the code. Also it reduces problems when a package gets upgraded: component writers are free to do pretty much anything on the implementation side, including renaming every single source file; care has to be taken only with the exported header files and with the CDL data, because those have the potential of impacting other packages. Application code is similarly unable to access package implementation details, only the exported interface.
Very occasionally the inability of one package to see implementation details of another does cause problems. One example occurs in HAL packages, where it may be desirable for the architectural, variant and platform HAL's to share some information that should not be visible to other packages or to application code. This may be addressed in the future by introducing the concept of friend packages, just as a C++ class can have friend functions and classes which are allowed special access to a class internals. It is not yet clear whether such cases are sufficiently frequent to warrant introducing such a facility.
Configurability usually involves source code that needs to implement different behavior depending on the settings of configuration options. It is possible to write packages where the only consequence associated with various configuration options is to control what gets built, but this approach is limited and does not allow for fine-grained configurability. There are three main ways in which options could affect source code at build time:
The component code can be passed through a suitable preprocessor, either an existing one such as m4 or a new one specially designed with configurability in mind. The original sources would reside in the component repository and the processed sources would reside in the build tree. These processed sources can then be compiled in the usual way.
This approach has two main advantages. First, it is independent from the programming language used to code the components, provided reasonable precautions are taken to avoid syntax clashes between preprocessor statements and actual code. This would make it easier in future to support languages other than C and C++. Second, configurable code can make use of advanced preprocessing facilities such as loops and recursion. The disadvantage is that component writers would have to learn about a new preprocessor and embed appropriate directives in the code. This makes it much more difficult to turn existing code into components, and it involves extra training costs for the component writers.
Compiler optimizations can be used to elide code that should not be present, for example:
…
if (CYGHWR_NUMBER_UARTS > 0) {
…
}
… |
If the compiler knows that CYGHWR_NUMBER_UARTS is
the constant number 0 then it is a trivial operation to get rid of the
unnecessary code. The component framework still has to define this
symbol in a way that is acceptable to the compiler, typically by using
a const variable or a preprocessor symbol. In some
respects this is a clean approach to configurability, but it has
limitations. It cannot be used in the declarations of data structures
or classes, nor does it provide control over entire functions. In
addition it may not be immediately obvious that this code is affected
by configuration options, which may make it more difficult to
understand.
Existing language preprocessors can be used. In the case of C or C++ this would be the standard C preprocessor, and configurable code would contain a number of #ifdef and #if statements.
#if (CYGHWR_NUMBER_UARTS > 0)
…
#endif |
This approach has the big advantage that the C preprocessor is a technology that is both well-understood and widely used. There are also disadvantages: it is not directly applicable to components written in other languages such as Java (although it is possible to use the C preprocessor as a stand-alone program); the preprocessing facilities are rather limited, for example there is no looping facility; and some people consider the technology to be ugly. Of course it may be possible to get around the second objection by extending the preprocessor that is used by gcc and g++.
The current component framework generates configuration header files with C preprocessor #define's for each option (typically, there various properties which can be used to control this). It is up to component writers to decide whether to use preprocessor #ifdef statements or language constructs such as if. At present there is no support for languages which do not involve the C preprocessor, although such support can be added in future when the need arises.
A package's exported header files should specify the interface provided by that package, and avoid any implementation details. However there may be performance or other reasons why implementation details occasionally need to be present in the exported headers.
Note: Not all programming languages have the concept of a header file. In some cases the component framework would need extensions to support packages written in such languages.
Configurability has a number of effects on the way exported header files should be written. There may be configuration options which affect the interface of a package, not just the implementation. It is necessary to worry about nested #include's and how this affects package and application builds. A special case of this relates to whether or not exported header files should #include configuration headers. These configuration headers are exported, but should only be #include'd when necessary.
Many configuration options affect only the implementation of a package, not the interface. However some options will affect the interface as well, which means that the options have to be tested in the exported header files. Some implementation choices, for example whether or not a particular function should be inlined, also need to be tested in the header file because of language limitations.
Consider a configuration option
CYGFUN_KERNEL_MUTEX_TIMEDLOCK which controls
whether or not a function cyg_mutex_timedlock is
provided. The exported kernel header file cyg/kernel/kapi.h could contain the
following:
#include <pkgconf/kernel.h> … #ifdef CYGFUN_KERNEL_MUTEX_TIMEDLOCK extern bool cyg_mutex_timedlock(cyg_mutex_t*); #endif |
This is a correct header file, in that it defines the exact interface
provided by the package at all times. However is has a number of
implications. First, the header file is now dependent on pkgconf/kernel.h, so any changes to
kernel configuration options will cause cyg/kernel/kapi.h to be out of date, and
any source files that use the kernel interface will need rebuilding.
This may affect sources in the kernel package, in other packages, and
in application source code. Second, if the application makes use of
this function somewhere but the application developer has
misconfigured the system and disabled this functionality anyway then
there will now be a compile-time error when building the application.
Note that other packages should not be affected, since they should
impose appropriate constraints on
CYGFUN_KERNEL_MUTEX_TIMEDLOCK if they use that
functionality (although of course some dependencies like this may get
missed by component developers).
An alternative approach would be:
extern bool cyg_mutex_timedlock(cyg_mutex_t*); |
Effectively the header file is now lying about the functionality provided by the package. The first result is that there is no longer a dependency on the kernel configuration header. The second result is that an application file using the timed-lock function will now compile, but the application will fail to link. At this stage the application developer still has to intervene, change the configuration, and rebuild the system. However no application recompilations are necessary, just a relink.
Theoretically it would be possible for a tool to analyze linker errors and suggest possible configuration changes that would resolve the problem, reducing the burden on the application developer. No such tool is planned in the short term.
It is up to component writers to decide which of these two approaches should be preferred. Note that it is not always possible to avoid #include'ing a configuration header file in an exported one, for example an option may affect a data structure rather than just the presence or absence of a function. Issues like this will vary from package to package.
As a general rule, unnecessary #include's should be avoided. A header file should #include only those header files which are absolutely needed for it to define its interface. Any additional #include's make it more likely that package or application source files become dependent on configuration header files and will get rebuilt unnecessarily when there are minor configuration changes.
Exported header files should avoid #include'ing configuration header files unless absolutely necessary, to avoid unnecessary rebuilding of both application code and other packages when there are minor configuration changes. A #include is needed only when a configuration option affects the exported interface, or when it affects some implementation details which is controlled by the header file such as whether or not a particular function gets inlined.
There are a couple of ways in which the problem of unnecessary rebuilding could be addressed. The first would require more intelligent handling of header file dependency handling by the tools (especially the compiler) and the build system. This would require changes to various non-eCos tools. An alternative approach would be to support finer-grained configuration header files, for example there could be a file pkgconf/libc/inline.h controlling which functions should be inlined. This could be achieved by some fairly simple extensions to the component framework, but it makes it more difficult to get the package header files and source code correct: a C preprocessor #ifdef directive does not distinguish between a symbol not being defined because the option is disabled, or the symbol not being defined because the appropriate configuration header file has not been #include'd. It is likely that a cross-referencing tool would have to be developed first to catch problems like this, before the component framework could support finer-grained configuration headers.
On-line package documentation should be in HTML format. The component framework imposes no special limitations: component writers can decide which version of the HTML specification should be followed; they can also decide on how best to cope with the limitations of different browsers. In general it is a good idea to keep things simple.
Packages should normally come with one or more test cases. This allows application developers to verify that a given package works correctly on their particular hardware and in their particular configuration, making it slightly more likely that they will attempt to find bugs in their own code rather than automatically blaming the component writers.
At the time of writing the application developer support for building
and running test cases via the component framework is under review and
likely to change. Currently each test case should consist of a single
C or C++ source file that can be compiled with the package's set of
compiler flags and linked like any application program. Each test case
should use the testing API defined by the infrastructure. A
magically-named calculated configuration option of the form
CYGPKG_<PACKAGE-NAME>_TESTS lists the test
cases.
On occasion it would be useful for an eCos package to be shipped with host-side support. This could take the form of an additional tool needed to build that package. It could be an application intended to communicate with the target-side package code and display monitoring information. It could be a utility needed for running the package test cases, especially in the case of device drivers. The component framework does not yet provide any such support for host-side software, and there are obvious issues related to portability to the different machines that can be used for hosts. This issue may get addressed in some future release. In some cases custom build steps can be subverted to do things on the host side rather than the target side, but this is not recommended.
