General information

This library contains code that extends and simplifies different operations for C language based programs. In other words it contains some programming tools that can be used inside every quite advanced C program. All code as much as possible is compatible with C99, C++98 and C++2011 standards and therefore can be easy integrated with C++ code (with proper optimizations). It's very important to stick around C99. As of 2015 year C11 is not supported well around the world. Besides, there are other interesting standard like OpenCL which compatible with C99. The library is supposed to be used for development for both bare-metal and complicated code that run under any kind of operating system, for any processor architecture with any machine's word length. The main purpose of library's existence is to provide handy layer between operating systems (they usually have C API), compilers (with some useful extensions) and application programs developed with C/C++.

Macros and preprocessor definitions exported by library have CT prefix. Internal definitions (and so types and functions) have __ postfix (e.g. CT_B8__). All variables, constants and functions for C++ programs belong to ctools namespace.

Content

• Definitions of compilers, system libraries, operating systems and unification of their extensions;
• Runtime and compiletime asserts support;
• Binary constants and bitwise operations;
• Adjustable compiletime and runtime traces;
• Preprocessor calculations;
• Working with pointers;
• Enums with extended facilities;
• Various constants.

Library's interface (include/ctools):

• mcu - contains primitives for microcontrollers. Perhaps in the future will be moved to another standalone library;
• net - contains primitives for networks. Perhaps in the future will be moved to another standalone library;
• os - not aimed for projects with bare-metal target platform;
• predef - see "Rationale" sections;
• std - replacement for standard include headers. They allow workaround limitations of some platforms, compilers and bring handy extensions to non-native configurations. Some modules contain "wrappers" over library functions. The only reason for their existence is to provide logging of operations.

Other known related projects

• boost/predef
• predef
• Qt/qtbase
• P99
• libowfat

All these projects is a good source of various ideas. But they most likely have incompatible license. Library is supposed to be minimalistic. That's why lots of dependencies are not welcome. Some ideas for predef could be borrowed from boost/predef, predef and Qt/qtbase. Those projects could be integrated here as subprojects but:

• These subprojects should become a part of the ctools interface. If an external program use for example boost on its own then we have 2 boost's version and probably a conflict;
• predef code from sourceforge.net isn't supported and improved ever since 2005. But wiki is still up to date;
• Qt/qtbase is a C++ library, not our case.

Target platforms

Any platforms that support C99, C++98 (and higher) compatible compilers with any machine's word length and any endianness are suitable. Some useful but not completely C99-compatible compilers like MS VC++ are allowed as exceptions.

Tested mainly though:

• Linux x86_64 + gcc;
• Linux x86_64 + clang;
• Windows XP + minwg;
• Windows 10 + MSVC2019.

The library must be compatible both with resources constrained platfoms (bare metal without OS) and with modern OS. Library should work at large all the time, although some features can not be available on the particular platform (e.g. realization of mutexes or msleep() function based on system calls). It is supposed that any definitions and declarations from library's interface can be freely used in any combinations. To achieve that they split into independent modules as much as possible. The project has never been tested with gcc before 4.2.4. Support for gLibc 2.19 is confirmed. When this library is used for constrained platforms developers should be cautious and check all the things to be sure that everything is doing right.

Dependencies

All scripts are written with Python programming (Version 3.4 is the latest that supports Windows XP and 3.8 is the latest that supports Windows 7). The project could be built with CMake building system. CMake 2.8.3 and above is needed in that case. Both dependencies are not mandatory. This project uses Git_(Version 2.10 is the latest that supports Windows XP) and Mercurial concurent versions systems. Some systems may demand installing of system library libiberty.

The scripts/cmake_build.py script depends on flufl.enum module. See README from pyrepo about installation details.

pyrepo's, cmake_tools's and tests' subfolder dependencies also must be installed in the system.

Building

There are 4 ways of how the library can be used:

• Building is not taking place. A project that is going to use ctools should worry about a building process. include and build_info/include directories should be passed to the compiler as directories of headers files. All the modules from src and its subdirectories should be linked to the output binary (if it is required). In some cases preprocessor definitions should be set up to choose mode of various subsystems. As the library evolving these build rules should be maintained. All the latest information about those rules can be borrowed from CMakeLists.txt files of libctools и libcpptools projects. This case can be recommended only when the others are unimplementable or unpreferable for some reasons.

• Building with CMakeLists.txt . A hierarchy of such files is formed. An uplevel project should import libctools like this:

  add_subdirectory(libctools)

  Some other cmake's definitions or environment variables can be set up to tune the process. An example of such hierarchy is a libctools's CMakeLists.txt;

• Building with the single CMakeLists.txt . The majority of library features is turned off at the building. This case is useful for editing the project in some IDEs;

• Building is performed by using cmake_*.py scripts. The built debug or release library is placed to the appropriate build subdirectory.

Some preprocessor identifiers which could be defined for MCU-targeted builds are described below:

• CT_NO_DYNAMIC_MEMORY - library will lack of dynamic memory support and some other inherent things;
• CT_RETARGET_PUTCHAR - provide to the linker code of standard putchar() function. It fixes linking errors for standalone builds. Any project-user have to implement this function if necessary;
• CT_NO_64 - disable 64 bit data type support

Library initialization

Sometimes some actions need to be done right after loading of the library. Otherwise some subsystems may not work correctly. If an external project just use some common macros then initialization is not required. Otherwise these is recommended to call:

• initializeCtools() before using of library;
• finalizeCtools() after of ceasing any work with library (unloading dynamic library from the memory or program termination).

Testing

See tests subfolder.

TODO