ecl_config Documentation

ecl_config

These tools inspect and describe your system with macros, types and functions.

packageSummary

Different platforms have minor differences in their implementations. Apart from the higher level api's such as threads and io devices, there is also the platform's actual implementation of the c++ standard that may differ from one machine to the next. For an instance, an int on a DSP is not the same width as an int on an amd processor. Partly via the cmake build process and partly via header referencing, the config module's elements some checking on the actual implementation for your system and define some cross-platform macros, types and classes that facilitate easy handling of these fundamental properties.

Cross Platform

Major Platforms

At the moment, the major implementations supported:

Custom Platforms

It also has provision to supply details about custom (primarily wierd embedded) platforms via the ECL_IS_CUSTOM macro. More detail below.

Compiling & Linking

Include the following at the top of any translation unit that utilises the configuration definitions and tools.

        #include <ecl/config.hpp>
        
        // Functions
        using ecl::is_big_endian;
        using ecl::is_char_signed;
        
        // Types  - refer to portable_types.hpp
        using ecl::int8;
        using ecl::uint8; 
        // ...

Usage

CMake Configuration

CMake can do the hard yards on most platforms/toolchains and autodetect what variables and headers can be used - this works mostly for the main platforms as outlined above. The result of this guesswork are a suite of macros stored in the ecl/config/ecl.hpp header. All macros are prefixed by an ECL, e.g. ECL_IS_POSIX.

Note that other packages also do some platform detection to varying degrees, e.g ecl_time_lite. The macros defined here are the most general purpose macros only.

Custom Configuration

Alternatively, a header can be hand customised to tailor for your own schwanky embedded board. To do this simply define the ECL_IS_CUSTOM macro as pointing to a header somewhere on your system before you call any ecl headers in your code. For example:

        #define ECL_IS_CUSTOM <ecl_dsp2812.hpp>

This will abort the cmake generated header and use your own hand crafted header in its place.

Unknown Configuration

If your system is truly unknown, you can define the ECL_IS_UNKNOWN (set to 1) macro before calling any other ecl headers. The ecl will then roughly try and determine your system from whatever macros are defined by your compiler.

This hasn't really been tested yet and probably will fall over horribly.

Macros

The following macros are the most important of those defined in this section.

    // Platform macros - automatically detected by the build.
    - ECL_IS_POSIX || ECL_IS_WIN32 || ECL_IS_APPLE || ECL_IS_CUSTOM
    - ECL_HAS_POSIX_THREADS || ECL_HAS_WIN32_THREADS
    - ECL_SIZE_OF_CHAR
    - ECL_SIZE_OF_SHORT
    - ECL_SIZE_OF_INT
    - ECL_SIZE_OF_LONG
    - ECL_SIZE_OF_LONG_LONG
    - ECL_SIZE_OF_FLOAT
    - ECL_SIZE_OF_DOUBLE
    - ECL_SIZE_OF_LONG_DOUBLE
    - ECL_CHAR_IS_SIGNED || ECL_CHAR_IS_UNSIGNED
    - ECL_HAS_SHARED_LIBS || ECL_HAS_STATIC_LIBS
    // ECL Development macros
    - ECL_DISABLE_EXCEPTIONS
    - ECL_DONT_INLINE
    - ECL_DEPRECATED
    - ECL_PUBLIC || ECL_LOCAL

Note that you may predefine ECL_HAS_SHARED_LIBS or ECL_HAS_STATIC_LIBS for your project if both are available and you want to force appropriate behaviour for the target set you are linking against.

Types

When you absolutely need to specify the bit-width type you need to use, the following typedefs are defined by the ECL when the appropriate types are available.

The float96 and float128 types may or may not also be defined depending on your platform.

Platform Sniffers

This is a set of functions that can be used to sniff your platform to determine various characteristics. Checking for endianness:

        // The function operates like a macro, and a good compiler will compile 
        // out the if mechanism and leave behind the required section of code. 
        if ( ecl::is_big_endian() {
            // ... 
        else {
            // ... 
        }

To check if your default char type is signed, or otherwise, use the following. Note that this only works for runtime checks. To do compile time checks (for use in template parameters etc), there is the ECL_CHAR_IS_SIGNED and ECL_CHAR_IS_UNSIGNED macros.

        if ( ecl::is_char_signed() {
            // ... 
        else {
            // ... 
        }

Unit Tests

Utilities

Both utilities detect various properties on your system and send the data to stdout. Useful for quick testing on embedded devices.

ChangeLog

ChangeLog



ecl_config
Author(s): Daniel Stonier
autogenerated on Wed Aug 26 2015 11:27:12