Repository files navigation

Provide an introductory paragraph, describing:

• What your project does
• Why people should consider using your project
• Link to project home page

1. About the Project
2. Project Status
3. Getting Started
   1. Requirements
      1. git-lfs
      2. Meson Build System
   2. Getting the Source
   3. Building
      1. Enabling Link-time Optimization
   4. Installation
   5. Usage
4. Configuration Options
5. Documentation
6. Need Help?
7. Contributing
8. Further Reading
9. Authors
10. License
11. Acknowledgments

Here you can provide more details about the project

• What features does your project provide?
• Short motivation for the project? (Don't be too long winded)
• Links to the project site

Show some example code to describe what your project doesShow some of your APIs

Back to top

Describe the current release and any notes about the current state of the project. Examples: currently compiles on your host machine, but is not cross-compiling for ARM, APIs are not set, feature not implemented, etc.

Back to top

This project usesEmbedded Artistry's standard Meson build system, and dependencies are described in detailon 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 project stores some files usinggit-lfs.

To installgit-lfs on Linux:

sudo apt install git-lfs

To installgit-lfs on OS X:

brew install git-lfs

Additional installation instructions can be found on thegit-lfs website.

TheMeson build system depends onpython3 andninja-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 throughpip3:

pip3 install meson

If you want to install Meson globally on Linux, use:

sudo -H pip3 install meson

Back to top

This project usesgit-lfs, so please install it before cloning. If you cloned prior to installinggit-lfs, simply rungit 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/project-skeleton.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

Back to top

If Make is installed, 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 generatedbuildresults folder using:

make distclean

You can also usemeson directly for compiling.

Create a build output folder:

meson buildresults

And build all targets by running

ninja -C buildresults

Cross-compilation is handled usingmeson cross files. Example files are included in thebuild/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 the project.

Cross-compilation must be configured using the meson command when creating the build output folder. For files stored withinbuild/cross, we provide a MakefileCROSS to simplify the process. This variable will automatically supply the proper Meson argument,build/cross/ prefix, and.txt filename extension.

You can use a single file, or you can layer multiple files by separating the names with a colon.

make CROSS=arm:cortex-m4_hardfloat

You can also do this manually with the Meson interface. Note, however, that you will need to include a special--cross-file=build/cross/embvm.txt cross file to ensure that the required Embedded VM settings are applied.

meson buildresults --cross-file build/cross/arm.txt --cross-file build/cross/cortex-m4_hardfloat.txt --cross-file=build/cross/embvm.txt

Following that, you can runmake (at the project root) orninja -C buildresults to build the project.

Note: Tests will not be cross-compiled. They will only be built for the native platform.

Full instructions for working with the build system, including topics like using alternate toolchains and running supporting tooling, are documented inEmbedded Artistry's Standardized Meson Build System on our website.

Back to top

Link-time Optimization (LTO) can be enabled during the meson configuration stage by setting the built-in optionb_lto totrue:

meson buildresults -Db_lto=true

This can be combined with other build options.

Back to top

The tests for this library are written with CMocka, which is included as a subproject and does not need to be installed on your system. 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 inbuildresults/test/.

Back to top

The following meson project options can be set for this library when creating the build results directory withmeson, or by usingmeson configure:

• disable-builtins will tell the compiler not to generate built-in function
• disable-stack-protection will tell the compiler not to insert stack protection calls
• disable-rtti will disable RTTI for C++ projects
• disable-exceptions will disable exceptions for C++ projects
• enable-threading can be used to control threaded targets and libc++ threading support
• enable-pedantic: Turn onpedantic warnings
• enable-pedantic-error: Turn onpedantic warnings and errors
• hide-unimplemented-libc-apis: Hides the header definitions for functions which are not actually implemented
• enable-gnu-extensions will enable GNU libc extensions that are implemented in this library

The following options can be used to configurelibc++ if used with this project:

• libcxx-use-compiler-rt
• libcxx-use-llvm-libunwind
• libcxx-thread-library
• libcxx-has-external-thread-api
• libcxx-build-external-thread-api
• libcxx-enable-chrono
• libcxx-enable-filesystem
• libcxx-enable-stdinout
• libcxx-default-newdelete
• libcxx-silent-terminate
• libcxx-monotonic-clock

Options can be specified using-D and the option name:

meson buildresults -Ddisable-builtins=false

The same style works withmeson configure:

cd buildresultsmeson configure -Ddisable-builtins=false

Back to top

Documentation can be built locally by running the following command:

make docs

Documentation can be found inbuildresults/docs, and the root page isindex.html.

Back to top

If you need further assistance or have any questions, please file a GitHub issue or send us an email using theEmbedded Artistry Contact Form.

You can alsoreach out on Twitter: mbeddedartistry.

If you are interested in contributing to this project, please read ourcontributing guidelines.

• Phillip Johnston

Copyright © 2020 Embedded Artistry LLC

See theLICENSE file for licensing details.

For other open-source licenses, please see theSoftware Inventory.

Make any public acknowledgments here

Back to top