This project supplies a C++ standard library and C++ ABI library that can be used for microcontroller-based embedded systems projects.
This project is based on the clang libc++ and libc++abi libraries. Alternative implementations are provided for various files to support embedded systems usage.
The builds are highly configurable, allowing you to create a libc++ and libc++abi set that is tuned specifically to your system's needs.
- About the Project
- Project Status
- Getting Started
- Configuration Options
- Versioning
- How to Get Help
- Contributing
- License
- Authors
This project supplies a C++ standard library and C++ ABI library that can be used for microcontroller-based embedded systems projects.
This project is based on the clang libc++ and libc++abi libraries. Alternative implementations are provided for various files to support embedded systems usage.
The builds are highly configurable, allowing you to create a libc++ and libc++abi set that is tuned specifically to your system's needs.
This project currently builds libc++ and libc++abi for x86, x86_64, arm, and arm64 processors. All relevant library configuration options have been ported from the CMake builds. See Configuration Options and meson_options.txt for the list of configurable settings.
This library has also been tested with Embedded Artistry libc and is used on multiple Embedded Artistry projects.
This project uses Embedded Artistry's standard Meson build system, and dependencies are described in detail on our website.
At a minimum you will need:
git-lfs, which is used to store binary files in this repository- Meson is the build system
- Some kind of compiler for your target system.
- This repository has been tested with:
- gcc-7, gcc-8, gcc-9
- arm-none-eabi-gcc
- Apple clang
- Mainline clang
- This repository has been tested with:
This project stores some files using git-lfs.
To install git-lfs on Linux:
sudo apt install git-lfs
To install git-lfs on OS X:
brew install git-lfs
Additional installation instructions can be found on the git-lfs website.
The Meson build system depends on python3 and ninja-build.
To install on Linux:
sudo apt-get install python3 python3-pip ninja-build
To install on OSX:
brew install python3 ninja
Meson can be installed through pip3:
pip3 install meson
If you want to install Meson globally on Linux, use:
sudo -H pip3 install meson
This project uses git-lfs, so please install it before cloning. If you cloned prior to installing git-lfs, simply run git lfs pull after installation.
This project is hosted on GitHub. You can clone the project directly using this command:
git clone --recursive [email protected]:embeddedartistry/libcpp.git
If you don't clone recursively, be sure to run the following command in the repository or your build will fail:
git submodule update --init
The library can be built by issuing the following command:
make
This will build all targets for the host system using the default options (specified in meson_options.txt). Build output will be placed in the buildresults folder.
You can clean builds using:
make clean
You can eliminate the generated buildresults folder using:
make distclean
You can also use the meson method for compiling.
You can choose your own build output folder with meson, but you must build using ninja within the build output folder.
$ meson my_build_output/
$ cd my_build_output/
$ ninja
At this point, make would still work.
You can also use meson directly for compiling.
Create a build output folder:
meson buildresults
And build all targets by running
ninja -C buildresults
Cross-compilation is handled using meson cross files. Example files are included in the build/cross folder. You can write your own cross files for your specific processor by defining the toolchain, compilation flags, and linker flags. These settings will be used to compile libc. (or open an issue and we can help you).
Cross-compilation must be configured using the meson command when creating the build output folder. For example:
meson buildresults --cross-file build/cross/arm.txt --cross-file build/cross/gcc_arm_cortex-m4.txt
Following that, you can run make (at the project root) or ninja to build the project.
Note that the standard settings may need to be adjusted when cross-compiling. For example, when using gnu-arm-none-eabi, you will likely need to set enable-threading=false and libcxx-enable-chrono=false.
Also note that if you are cross-compiling for ARM using the arm-none-eabi-gcc toolchain, you will need to use version 9.0 or later. If you cannot get this version for your platform due to package availability, you can build the most recent compiler version using the arm-gcc-bleeding-edge project.
Full instructions for building the project, using alternate toolchains, and running supporting tooling are documented in Embedded Artistry's Standardized Meson Build System on our website.
If you don't use meson for your project, the best method to use this project is to build it separately and copy the headers and library contents into your source tree.
- Copy the
include/directory contents into your source tree. - Library artifacts are stored in the
buildresults/folder - Copy the desired library to your project and add the library to your link step.
Example linker flags:
-Lpath/to/libraries -lc++ -lc++abi
You can use libcpp as a subproject inside of another meson project. Include this project with the subproject command:
libcpp = subproject('libcpp')
Then make dependencies available to your project:
libcxx_full_dep = libcpp.get_variable('libcxx_full_dep')
libcxx_full_native_dep = libcpp.get_variable('libcxx_full_native_dep')
libcxx_header_include_dep = libcpp.get_variable('libcxx_header_include_dep')
libcxx_native_header_include_dep = libcpp.get_variable('libcxx_native_header_include_dep')
You can use these dependencies elsewhere in your project:
fwdemo_sim_platform_dep = declare_dependency(
include_directories: fwdemo_sim_platform_inc,
dependencies: [
fwdemo_simulator_hw_platform_dep,
fwdemo_platform_dep,
libmemory_native_dep,
libc_native_dep,
libcxx_full_native_dep, # <---- here
],
sources: files('boot.cpp', 'platform.cpp'),
)
Well, let's be honest: there are way too many options for this project (see meson_options.txt). But we support a variety of project-specific options as well as the majority of the useful options provided by the libc++ and libc++abi Cmake projects.
Here are the configurable options:
enable-werror: Cause the build to fail if warnings are presentenable-pedantic-error: Turn onpedanticwarnings and errorsforce-32-bit: forces 32-bit compilation instead of 64-bitos-header-path: Path to the headers for your OS, if using a custom threading solutionsdisable-rtti: Build without RTTI support (excludes some C++ features such as name demangling)disable-exceptions: Build without exception supportuse-compiler-rt: Build with compiler-rt supportalways-enable-assert: Enable assert even with release buildsuse-llvm-libunwind: Tell libc++abi to use the llvm libunwinder (don't change unless you know what you're doing)libcxx-enable-chrono: Builds with chrono.cppenable-threading: Build with threading supportlibcxx-thread-library: Select the threading library to use with libc++: none, pthread, or the framework thread shimslibcxx-has-external-thread-api: Tell C++ to look for an __external_threading header with thread function shimslibcxx-build-external-thread-api: ???libcxx-enable-filesystem: enable filesystem supportlibcxx-enable-stdinout: enable stdio supportlibcxx-default-newdelete: Enable support for the default new/delete implementationslibcxx-silent-terminate: Enable silent termination. The default terminate handler attempts to demangle uncaught exceptions, which causes extra I/O and demangling code to be pulled in.libcxx-monotonic-clock: Enable/disable support for the monotonic clock (can only be disabled if threading is disabled)use-libc-subproject: When true, use the subproject defined in the libc-subproject option. An alternate approach is to override c_stdlib in your cross files.libc-subproject: This array is used in combination withuse-libc-subproject. The first entry is the subproject name. The second is the cross-compilation dependency to use. The third value is optional. If used, it is a native dependency to use with native library targets.
Options can be specified using -D and the option name:
meson buildresults -Denable-werror=true
The same style works with meson configure:
cd buildresults
meson configure -Denable-werror=true
You can enable threading support with an RTOS using an __external_threading header. Supply the include path to your RTOS headers:
meson buildresults --cross-file build/cross/gcc/arm/gcc_arm_cortex-m4.txt -Dlibcxx-thread-library=threadx -Dos-header-path=../../os/threadx/include
You can block the new and delete operators by setting the libcxx-default-newdelete to false:
meson buildresults -Dlibcxx-default-newdelete=false
You can also use meson configure:
cd buildresults
meson configure -Dlibcxx-default-newdelete=false
If you are using libcpp as a subproject, you can specify this setting in the containing project options.
This project is designed to be used along with a libc implementation. If you are using this library, you may not be using the standard libc that ships with you compiler. This library needs to know about the particular libc implementation during its build, in case there are important differences in definitions.
There are two ways to tell this library about a libc:
- Override
c_stdlibin a cross-file, which will be automatically used when building this library. - Set
use-libc-subprojecttotrue- By default, this will use the Embedded Artistry libc
- You can specify another Meson subproject by configuring
libc-subproject. This is an array: the first value is the subproject name, the second the libc dependency variable, and the third is an optional native dependency that will be used with native library variants.
NOTE: External libc dependencies are only used for building the library. They are not forwarded through dependencies. You are expected to handle that with the rest of your program.
This project itself is unversioned and simply pulls in the latest libc++ and libc++abi commits periodically.
If you need further assistance or have any questions, please file a GitHub Issue or send us an email using the Embedded Artistry Contact Form.
You can also reach out on Twitter: @mbeddedartistry.
If you are interested in contributing to this project, please read our contributing guidelines.
This container project is licensed under the MIT license.
libc++ and libc++abi (and the llvm project in general) are released under a modified Apache 2.0 license. Source files which have been modified are licensed under those terms.
- Phillip Johnston - Initial work - Embedded Artistry