Chapter 11. Usage

The easiest way to start using eCos for C++ development is to use the special configuration template included in this release for this purpose. With command line configuration it may be used as in the following example for the Atmel EB40A target:

       $ ecosconfig new eb40a libstdc++
If using the graphical tool, the template may be selected with the Build->Templates menu item.

Once the eCos libraries are configured and built, you may link your application. Be sure to append -lstdc++ to the end of the link line. If you wish to use C++ exceptions, be sure to either remove -fno-exceptions from your compilation line, or append -fexceptions at the end of the compilation line. Similarly, to use RTTI, either remove -fno-rtti from your compilation line, or append -frtti to the end of the compilation line. Finally, despite what some targets may have used for their default compiler flags it is important that the option -fvtable-gc is not used.

Requirements

As noted earlier, this package uses CDL to set constraints on the rest of the eCos system for correct and standards compliant operation of the C++ library. By selecting with the libstdc++ configuration template, you will be able to start with a configuration with all the necessary packages included and options set.

Building C++ programs, particularly those that use templates heavily (either directly, or using the templates from libstdc++), can take a lot of memory on the build machine - figures in excess of 220Mb have been observed building the testsuite included with this package. Be sure to have sufficient RAM to prevent extended build times.

This package requires a patched version of the GNU compiler in order to correctly support thread-safe C++ exceptions, and avoid problems with common infrastructure underlying most standard C++ library classes. Refer to the tools building notes below for further details.

Warning

If a compiler is used which was not supplied by eCosCentric, nor built with eCosCentric's patch, the facilities provided by the standard C++ library will not be thread-safe. This may result in corruption, unexpected behaviour or a crash. In particular, C++ exceptions will not be thread-safe. Even if an application does not use exceptions directly, they may be used internally within the standard C++ library. Furthermore, certain infrastructure used by multiple C++ library objects (such as allocators) will also not be thread-safe.

The multi-thread protection provided by the standard C++ library intentionally only extends to subsystems shared by multiple classes. It does not mean that multiple threads can safely access individual object instances. If an individual object may be accessed by multiple threads simultaneously, access to that object will still need to be protected separately by the user at the application level, for example with a mutex. The thread-safety protection provided by the eCosCentric-enhanced version of the standard C++ library only ensures that threads can safely access different instances of C++ library objects without special protection by the user, despite many of these objects using functionality which requires shared global state. This approach is an intentional design decision in order to avoid unnecessary locking overhead.

Due partly to this specialised toolchain support it is not possible to use this package with the synthetic target, as native toolchains are built with specialised knowledge of the C++ runtime installed on the native OS. This is not solely due to the aforementioned patches, but also because of direct assumptions made as part of the GNU toolchain build procedure. As such, use under the synthetic target is unlikely ever to be possible.

It has been observed that GDB releases prior to GDB 6.1 can have difficulty debugging complex C++ applications, particularly those that extensively include template classes containing virtual functions. GDB 6.1 or above is recommended.

2017-02-09
Documentation license for this page: eCosPro License