libc targeted for embedded systems usage. Reduced set of functionality (due to embedded nature). Chosen for portability and quick bringup.
Branch: master
Clone or download
phillipjohnston Resolve STL I definition problems
Don't include openlibm.h in math.h, as it's pulling in complex number definitions and messing things up.
We instead directly include the fenv and math headers.

We also created a new complex.h header which includes the openlibm definitions
Latest commit 395ac71 Jan 16, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
arch Fix intmax_t definition which was causing C++ STL linker errors Nov 26, 2018
build @ c8ee419 Add clang-tidy support to the libc build Dec 4, 2018
docs Relocate Jenkinsfiles from docs -> tools Sep 5, 2018
include Resolve STL I definition problems Jan 16, 2019
openlibm @ cca41bc Add openlibm and printf submodules Sep 28, 2018
printf @ 233bfcf Update printf submodule for fctprintf fix Jan 16, 2019
src Update formatting for putchar_native.c Jan 15, 2019
test Add openlibm definitions to libc. Currently not being compiled/linked Sep 28, 2018
tools Exclude test files from cppcheck Dec 5, 2018
.adr-dir Enable ADR for this repository Mar 20, 2018
.clang-format Update AllowShortFunctionsOnASingleLine to be Empty Sep 4, 2017
.gitattributes Add xlsx files to git-lfs Aug 1, 2018
.gitignore Add coverage build option to libc project Dec 4, 2018
.gitmodules
LICENSE Update the libc licenses - project license is MIT, add a LICENSES.md … Dec 7, 2017
Makefile Add clang-tidy support to the libc build Dec 4, 2018
README.md Remove internal cmocka, use installed version Sep 9, 2018
meson.build Add a printf-only dependency Jan 15, 2019
meson_options.txt

README.md

libc

Embedded Artistry's libc is a C standard library implementation targeted for embedded systems.

In order to conserve precious memory resources, this library does not supply the complete C standard library functionality. Instead, a subset of functions which are useful on bare-metal embedded systems has been selected. If you have a bare metal system and want to use the standard set of C functions, this library is for you!

Unlike many other C libraries that I've come across, this library implements unit tests and has addressed flaws in open-source implementations of the C standard library functions.

malloc and free are not included in this library. If you need dynamic memory allocation support, you can couple this library with the Embedded Artistry libmemory, which contains implementations of malloc and free.

If you are interested in contributing to this project, please read the CONTRIBUTING guide.

Table of Contents

  1. About the Project
  2. Project Status
  3. Getting Started
    1. Requirements
      1. Meson Build System
    2. Getting the Source
    3. Building
      1. Cross-compiling
    4. Installation
    5. Usage
      1. Aligned Malloc
    6. Testing
  4. Formatting
  5. Documentation
  6. Need Help?
  7. Contributing
  8. Futher Reading
  9. Authors
  10. License
  11. Acknowledgements

About the Project

Embedded Artistry's libc is intended to provide a portable set of useful C standard library functions that allows quick bringup of new bare-metal embedded systems.

Additionally, we want to ensure a high-quality libc implementation by ensuring that each function has unit test coverage. Many C library function implementations are untested and contain errors. We are fighting poor implementations by adding test coverage.

In order to conserve precious memory resources, this library does not supply the complete C standard library functionality. Instead, a subset of functions which are useful on bare-metal embedded systems has been selected. This selection has primarily been driven by my own experience in bare-metal development. If you need additional features, please open a feature request.

The functional implementations in this library have been selected for portability and quick bringup of new systems. There may be more efficient implementations for these functions, but often they are architecture specific.

malloc and free are not included in this library. Because memory allocation schemes vary greatly with embedded systems (some not even allowing dynamic memory), you will need to supply your own implementations based on your system's needs. You can also couple this library with the Embedded Artistry libmemory, which contains implementations of malloc and free.

Project Status

This library does not supply errno support at this time.

The following portions of the C library have been implemented:

  • ctype
  • string
  • stdlib
    • atoX
    • abs, labs, llabs
    • bsearch
    • calloc
    • div, ldiv, lldiv
    • heapsort, heapsort_r
    • imaxabs, imaxdiv
    • qsort, qsort_r
    • rand family
    • realloc
    • strtoX functions (many via gdtoa)

The following architectures are currently supported:

  • x86
  • x86_64

Up next:

  • assert (assert.h)
  • Hooks for exit and abort (stdlib)
  • ARM architecture support
  • Cross-compilation for ARM
  • math.h and some definitions (INFINITY, NaN)
  • stdio

The following unit tests need to be added:

  • bsearch
  • imaxdiv
  • div, ldiv
  • realloc
  • rand family
  • strnstr
  • memmove

Maybe in the future:

  • wchar support
  • errno support (enabled as a compile-time switch)
  • getopt support

Getting Started

Requirements

  • CMocka must be installed on your system to compile the unit tests
  • Doxygen must be installed to generate documentation
  • Meson is used as the buildsystem
  • git-lfs is used to store binary files
  • make and gcc should be installed in order to compile the files

Meson Build System

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

adr-tools

This repository uses Architecture Decision Records. Please install adr-tools to contribute to architecture decisions.

If you are using OSX, you can install adr-tools through Homebrew:

brew install adr-tools

If you are using Windows or Linux, please install adr-tools via GitHub.

Getting the Source

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 git@github.com:embeddedartistry/libc.git

Building

The library can be built by issuing the following command:

make

This will build all targets for your current architecture.

You can clean builds using:

make clean

You can eliminate the generated Makefiles and buildresults using:

make purify

Cross-compiling

Output is currently limited to x86_64, but cross-compiling for ARM will be implemented in the near future.

Installation

Currently the best method to use this project is to build it separately and copy the contents into your tree. I will improve this method to allow easier usage as a submodule.

Copy the include/ directory contents into your source tree.

Build artifacts are stored in the buildresults folder. You will find a libc folder which contains the compiled static library: libc.a

Copy the desired library to your project and add the library to your link step.

Example linker flags:

-lc -Lpath/to/libc.a

Testing

The tests for this library are written with CMocka. You can run the tests by issuing the following command:

make test

By default, test results are generated for use by the CI server and are formatted in JUnit XML. The test results XML files can be found in buildresults/testresults/.

If you would prefer to see the test result summary printed to stdout instead, simply use the following command:

CMOCKA_MESSAGE_OUTPUT=stdout make test

Formatting

This repository enforces formatting using clang-format.

You can auto-format your code to match the style guidelines by issuing the following command:

make format

Formatting is enforced by the Jenkins build server which runs continuous integration for this project. Your pull request will not be accepted if the formatting check fails.

Documentation

Documentation for the latest release can always be found here.

Documentation can be built locally by running the following command:

make doc

Documentation can be found in buildresults/doc, and the root page is index.html.

Need help?

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.

Contributing

If you are intersted in contributing to this project, please read our contributing guidelines.

Further Reading

Authors

License

Copyright © 2017 Embedded Artistry LLC

This project is licensed under the MIT License - see LICENSE file for details.

musl libc is licensed under the MIT License - see LICENSE file for details.

Acknowledgments

I'd like to thank the following individuals for their direct contributions on this project:

Many of the open-source function implementations used in this library have been pulled from two primary sources:

  • Apple Open Source libc
    • abs, atof, bsearch, div family, heapsort/qsort family, abs family, imax family, strtol/ll/ull
    • fls, flsl, flsll
    • strstr, strtok. strnstr, strnlen, strndup, strncpy, strncat, strlen, strdup, strcpy, strcat
    • memmem, memcpy
  • musl libc
    • All ctype member functions (locale support removed)
    • strrchr, strchrnul, strchr
    • memset, memrchr

I have also used and improved the open-source gdtoa library.

The initial groundwork of testing was implemented by referencing the libc-test project.

Back to top