Welcome! We love receiving contributions from the community, so thanks for stopping by! There are many ways to contribute, including submitting bug reports, improving documentation, submitting feature requests, reviewing new submissions, or contributing code that can be incorporated into the project.

This document describes the Embedded Artistry development process. Following these guidelines shows that you respect the time and effort of the developers managing this project. In return, you will be shown respect in addressing your issue, reviewing your changes, and incorporating your contributions.

We are actively looking for additional malloc/free implementations! Feel free to contribute!

Table of Contents:

Code of Conduct

By participating in this project, you agree to abide by the Embedded Artistry Code of Conduct. We expect all contributors to follow the Code of Conduct and to treat fellow humans with respect.

Important Resources

This project is managed on GitHub:

Embedded Artistry has a Slack team that you can join to ask questions. Please use this invite link to join.

Questions can also be submitted on the Embedded Artistry website

Useful Documentation:

Embedded Artistry blog posts related to this project:

Bringup Blog Category - contains multiple articles about libmemory and libc
Implementing Malloc: First-fit Free List
Implementing Malloc with ThreadX
Generating Aligned Memory

Questions

Please submit your questions in the following ways:

Filing a new GitHub Issue
Joining the Embedded Artistry Slack team
Submitting a question on the Embedded Artistry website
Asking a question on Twitter: @mbeddedartistry.

Feature Requests

We welcome feature requests!

For all requests, please file a new GitHub issue. Please provide the details about the feature/function you would like to see and why you need it. Please discuss your ideas and feedback before proceeding.

For new features or functions which have not been implemented, please label your request with the "Feature" label. If you are requesting an improvement on an existing function, please use the "Enhancement" label.

Small Changes can directly be crafted and submitted to the GitHub Repository as a Pull Request. See the section regarding Pull Request Submission Guidelines.

Reporting Bugs

Before you submit your issue, please search the issue archive - maybe your question or issue has already been identified or addressed.

If you find a bug in the source code, you can help us by submitting an issue to our GitHub issue tracker. Even better, you can submit a Pull Request with a fix!

This project uses an issue template, which GitHub will auto-populate when you create a new issue. Please make sure to follow the template and provide the necessary information. This will help us track down the bug as quickly as possible.

Improving Documentation

Should you have a suggestion for the documentation, you can open an issue and outline the problem or improvement you have - however, creating the doc fix yourself is much better! By creating a new issue (or commenting on a related existing one), you let others know what you're working on. If you're making a small change (typo, phrasing) don't worry about filing an issue first - just open a Pull Request.

For large fixes, please build and test the documentation before submitting the PR to be sure you haven't accidentally introduced any layout or formatting issues. To generate the Doxygen documentation, run:

make doc

You can find the resulting output in buildresults/doc folder.

Contributing Code

If you're interested in contributing code to this project, read on! Don't know where to start? Take a look at the Finding an Issue section for help finding beginner-friendly issues.

We are actively looking for additional malloc/free implementations! Feel free to contribute!

If you are working on your first open source project or pull request, here are some helpful tutorials:

Getting Started

Install these dependencies:

Doxygen must be installed to generate documentation
Meson is the build system
git-lfs is used to store binary files
make is required to use Makefile shims
A compiler should be installed in order to build the project (gcc + clang have been tested)

You will need to fork the main repository to work on your changes. Simply navigate to our GitHub page and click the "Fork" button at the top. Once you've forked the repository, you can clone your new repository and start making edits.

When using git, it is best to isolate each topic or feature into a “topic branch”. Branches are a great way to group commits related to one feature together, or to isolate different efforts when you might be working on multiple topics at the same time.

While it takes some experience to get the right feel about how to break up commits, a topic branch should be limited in scope to a single issue. If you are working on multiple issues, please create multiple branches and submit them for review separately.

# Checkout the master branch - you want your new branch to come from master
git checkout master
# Create a new branch named newfeature (give your branch its own simple informative name)
git branch newfeature
# Switch to your new branch
git checkout newfeature

For more information on the GitHub fork and pull-request processes, please see this helpful guide.

git-lfs

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.

Meson Build System

The [Meson][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.

Finding an Issue

The list of outstanding feature requests and bugs can be found on our on our GitHub issue tracker. Pick an unassigned issue that you think you can accomplish and add a comment that you are attempting to do it.

good first issue labeled issues are deemed to be good low-hanging fruit for newcomers to the project
help wanted labeled issues may be more difficult than good first issue and may include new feature development
Documentation labeled issues apply to new documents

Development Process

master contains the latest code, and new versions are tagged nightly.

Please branch from master for any new changes. Once you are ready to merge changes, open a pull request. The build server will test and analyze the branch to ensure it can be safely merged.

Building the Project

To run the build, simply call:

$ make

This will build the library and tests. You can build individual projects by navigating to buildresults and using the ninja interface.

If you area adding new files to the library that will apply across RTOSes, you will need to modify src/meson.build and add the new file to the common_files list.

common_files = [
    'aligned_malloc.c',
    'posix_memalign.c'
]

If you would like to create a malloc/free implementation for a new RTOS:

Copy the libmemory_threadx library target and dependency
Rename the build target and library output to match the RTOS
Add the relevant RTOS headers to the dependencies/rtos folder
Update include paths if necessary
Add your malloc_*rtos*.c file to that RTOS's build list

If you have any questions, please don't hesitate to ask for assistance.

Testing

If you add code you need to add tests! We’ve learned the hard way that code without tests is undependable. If your pull request reduces our test coverage because it lacks tests then it will be rejected.

This project uses CMocka as the testing framework.

Please follow these guidelines:

New tests should be added to the test/src/ directory tree
Each function should have its own tests in its own C file.
When adding a new test, add the following to the relevant test coordination file:
- Add an extern function declaration in main.c: extern int ctype_tests(void);
- Add a call to the test coordinator in main.c: overall_result |= ctype_tests();

Style Guidelines

This project does not currently have an explicit style guideline, other than the formatting that is specified below.

When making changes to existing files, please keep the style consistent.

Code 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.

Whitespace Cleanup

Don’t mix code changes with whitespace cleanup! If you are fixing whitespace, include those changes separately from your code changes. If your request is unreadable due to whitespace changes, it will be rejected.

Please submit any whitespace cleanups in a separate pull request.

Git Commit Guidelines

The first line of the commit log must be treated as as an email subject line. It must be strictly no greater than 50 characters long. The subject must stand on its own and not only make external references such as to relevant bug numbers.

The second line must be blank.

The third line begins the body of the commit message (one or more paragraphs) describing the details of the commit. Paragraphs are each separated by a blank line. Manual line breaks are not required.

The last part of the commit log should contain all "external references", such as which issues were fixed.

For further notes about git commit messages, please read this blog post.

Pull Request Process

When you are ready to generate a pull request for preliminary review or merging into the project, you must first push your local topic branch back up to GitHub:

git push origin newfeature

Once you've committed and pushed all of your changes to GitHub:

Go to the page for your fork on GitHub
Select your development branch
Click the pull request button

If you need to make any adjustments to your pull request, just push the updates to your branch. Your pull request will automatically track the changes on your development branch and update.

Please follow the Pull Request Template for this project. GitHub will automatically populate the pull request description with this template.

Review Process

Changes must build correctly on the Jenkins CI server, be free of formatting errors, and pass tests.

One the changes pass the CI process, I will review the source code and provide feedback. I work on a variety of projects, so please expect some delay in getting back to you with a code review. I will notify you as soon as I have seen the PR and provide insight into the expected review timeline.

Addressing Feedback

Once a PR has been submitted, your changes will be reviewed and constructive feedback may be provided. Feedback isn't meant as an attack, but to help make sure the highest-quality code makes it into our project. Changes will be approved once required feedback has been addressed.

If a maintainer asks you to "rebase" your PR, they're saying that a lot of code has changed, and that you need to update your fork so it's easier to merge.

To update your forked repository, follow these steps:

# Fetch upstream master and merge with your repo's master branch
git fetch upstream
git checkout master
git merge upstream/master
# If there were any new commits, rebase your development branch
git checkout newfeature
git rebase master

If too much code has changed for git to automatically apply your branches changes to the new master, you will need to manually resolve the merge conflicts yourself.

Once your new branch has no conflicts and works correctly, you can override your old branch using this command:

git push -f

Note that this will overwrite the old branch on the server, so make sure you are happy with your changes first!

If you have any questions about this process, please ask for help!

Community

Anyone interested in active conversation regarding this project should [join the Embedded Artistry Slack team]https://join.slack.com/t/embeddedartistry/shared_invite/enQtMjgyNzI2MDY4NjkyLTcyZTk2OGZjZTk2MGY3NzMyNGM4NDg0ZjYyNzEyNDI1MzA1ZjYzNTc2Y2EzMzM5N2IyZmViYWFhMGRjZDM3Zjk)).

You can also reach out on Twitter: @mbeddedartistry.