https://github.com/embeddedartistry/project-skeleton
A C & C++ project skeleton for new Embedded Artistry projects
https://github.com/embeddedartistry/project-skeleton
Last synced: about 2 months ago
JSON representation
A C & C++ project skeleton for new Embedded Artistry projects
- Host: GitHub
- URL: https://github.com/embeddedartistry/project-skeleton
- Owner: embeddedartistry
- License: apache-2.0
- Created: 2020-04-10T16:24:45.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2023-12-07T21:45:09.000Z (over 1 year ago)
- Last Synced: 2025-01-17T23:41:55.076Z (3 months ago)
- Language: Meson
- Size: 114 KB
- Stars: 23
- Watchers: 3
- Forks: 3
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: docs/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Project Title
Provide an introductory paragraph, describing:
* What your project does
* Why people should consider using your project
* Link to project home page
## Table of Contents
1. [About the Project](#about-the-project)
2. [Project Status](#project-status)
3. [Getting Started](#getting-started)
1. [Requirements](#requirements)
1. [git-lfs](#git-lfs)
1. [Meson Build System](#meson-build-system)
2. [Getting the Source](#getting-the-source)
3. [Building](#building)
1. [Enabling Link-time Optimization](#enabling-link-time-optimization)
4. [Installation](#installation)
5. [Usage](#usage)
4. [Configuration Options](#configuration-options)
5. [Documentation](#documentation)
6. [Need Help?](#need-help)
7. [Contributing](#contributing)
8. [Further Reading](#further-reading)
9. [Authors](#authors)
10. [License](#license)
11. [Acknowledgments](#acknowledgements)
# About the Project
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 does
Show some of your APIs
```
**[Back to top](#table-of-contents)**
# Project Status
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](#table-of-contents)**
## Getting Started
### Requirements
This project uses [Embedded Artistry's standard Meson build system](https://embeddedartistry.com/fieldatlas/embedded-artistrys-standardized-meson-build-system/), and dependencies are described in detail [on our website](https://embeddedartistry.com/fieldatlas/embedded-artistrys-standardized-meson-build-system/).
At a minimum you will need:
* [`git-lfs`](https://git-lfs.github.com), which is used to store binary files in this repository
* [Meson](#meson-build-system) 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
#### git-lfs
This project stores some files using [`git-lfs`](https://git-lfs.github.com).
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](https://git-lfs.github.com).
#### Meson Build System
The [Meson](https://mesonbuild.com) 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
```
**[Back to top](#table-of-contents)**
### Getting the Source
This project uses [`git-lfs`](https://git-lfs.github.com), 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/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](#table-of-contents)**
### Building
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 generated `buildresults` folder using:
```
make distclean
```
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`](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 the project.
Cross-compilation must be configured using the meson command when creating the build output folder. For files stored within `build/cross`, we provide a Makefile `CROSS` 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 run `make` (at the project root) or `ninja -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 in [Embedded Artistry's Standardized Meson Build System](https://embeddedartistry.com/fieldatlas/embedded-artistrys-standardized-meson-build-system/) on our website.**
**[Back to top](#table-of-contents)**
### Enabling Link-time Optimization
Link-time Optimization (LTO) can be enabled during the meson configuration stage by setting the built-in option `b_lto` to `true`:
```
meson buildresults -Db_lto=true
```
This can be combined with other build options.
**[Back to top](#table-of-contents)**
### Testing
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 in `buildresults/test/`.
**[Back to top](#table-of-contents)**
## Configuration Options
The following meson project options can be set for this library when creating the build results directory with `meson`, or by using `meson 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 on `pedantic` warnings
* `enable-pedantic-error`: Turn on `pedantic` 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 configure `libc++` 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 with `meson configure`:
```
cd buildresults
meson configure -Ddisable-builtins=false
```
**[Back to top](#table-of-contents)**
## Documentation
Documentation can be built locally by running the following command:
```
make docs
```
Documentation can be found in `buildresults/docs`, and the root page is `index.html`.
**[Back to top](#table-of-contents)**
## 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](http://embeddedartistry.com/contact).
You can also [reach out on Twitter: mbeddedartistry](https://twitter.com/mbeddedartistry/).
## Contributing
If you are interested in contributing to this project, please read our [contributing guidelines](docs/CONTRIBUTING.md).
## Authors
* **[Phillip Johnston](https://github.com/phillipjohnston)**
## License
Copyright © 2020 Embedded Artistry LLC
See the [LICENSE](LICENSE) file for licensing details.
For other open-source licenses, please see the [Software Inventory](docs/software_inventory.xlsx).
## Acknowledgments
Make any public acknowledgments here
**[Back to top](#table-of-contents)**