Miosix and git workflow

The Miosix git repository

Miosix uses the git version control system to manage the kernel source code. To download and use the kernel you have to clone its git repository. The main Miosix git repository is hosted on this website, miosix.org, but we have no web page where you can browse the kernel sources. For this, we use a github mirror and the two repositories will be always kept in sync.

As the kernel is under active development, users are advised to periodically git fetch or check the kernel page on github to look for new features and bug fixes, and pull the changes if required.

By default, when cloning a repository, git will download the master branch. Miosix offers two additional branches, testing and unstable, and you should be aware of the conventions we use for how we manage branches:

• The master branch contains the stable kernel, it is updated infrequently, usually once a year when a new release is made. Sometimes, a few minor releases are updated in short order.
• The testing branch contains the in-development code that we consider almost ready. Use this branch to get more bleeding edge features.
• The unstable branch is where the Miosix development team is working. It's meant to be used only by people in contact with the development team, as we occasionally rebase and force-push changes, so you may have a hard time keeping your git repository in sync with ours (the commit you downloaded today may no longer exist after a force push). If you're writing applications, it's best to ignore this branch and wait for the desired change to trickle to testing.

Cloning the kernel repository from miosix.org can be done with:

git clone https://miosix.org/git-public/miosix-kernel.git
cd miosix-kernel

While cloning the github mirror with:

git clone https://github.com/fedetft/miosix-kernel.git
cd miosix-kernel

To checkout a specific branch, once you have cloned the git repository, use the following command

git checkout testing

The rest of this page explains how to set up a software project making use of the Miosix kernel, that can later allow updating the kernel through git without creating problems. There are basically two ways to do so:

• Setting up out an out of git tree project: this is the suggested workflow for developing applications using Miosix. Your application directory and git repo stay separate from the kernel directory and git repo. The kernel can be a git submodule of your project.
• Forking the Miosix kernel git repository. This is the suggested workflow for extending the kernel, such as adding new board support packages (BSPs).

The two workflows can be combined, for example you may want to fork the kernel to add your BSPs, and then use the forked kernel as submodule for developing your applications.

Setting up an out of git tree project

Out of git tree projects allow you to write applications in a directory that stays separate from the Miosix kernel directory. Additionally, they allow to perform the kernel configuration (that requires editing configuration files) without the need to make changes to files within the Miosix git repo at all. This last point is important both to have the Miosix git repository as a git submodule of your application's git repository, and to allow sharing the same downloaded copy of the Miosix kernel across different applications, each with its own configuration. The kernel source code size on the hard drive has grown bigger in recent years due to the inclusion of headers with peripheral registers definitions in the CMSIS directory, so you may want to share a single downloaded copy of the kernel across several projects.

Note that the ability to develop applications without making changes to the kernel directory is currently limited to the use case of configuring the kernel for one of the available BSPs. If you need to add BSPs to the kernel, then you'll most likely also have to fork the kernel repository. The most likely is due to generic BSPs in the kernel, which can be identified in the list of boards in Makefile.inc as <chip name>_generic such as stm32f103xb_generic. If you're writing an application for a board that has a chip with a generic BSP in the kernel, you can (unless you really need to run some custom code during boot) get away with selecting the generic BSP without forking the kernel. If there's no generic BSP for your chip, or need to add support for an entirely new chip, then you'll have to fork the kernel to add it.

Suppose you have a git repository called test, which is the repo of your application, and you would like to download the miosix-kernel repository as a git submodule. Then open a shell in the test repository and type

git submodule init
git submodule add https://miosix.org/git-public/miosix-kernel.git miosix-kernel
cd miosix-kernel
git fetch origin
cd ..
git commit -a -m "Added miosix-kernel as a git submodule"

This solves the problem from the git side, now let's solve the problem from the Miosix side. As you may know, git submodules work well if you never make changes in the submodule directory, otherwise you will have to basically fork the submodule, or you will find yourself making changes to a repository in a detached head state and risk losing them at the next git pull.

However, the Makefile for Miosix, as well as configuration files such as miosix/config/Makefile.inc and miosix/config/miosix_settings.h are within the submodule directory, so how are you going to make use of the kernel without touching files in the submodule directory?

The solution is out of git tree projects, a new feature added in Miosix 2.0 that basically moves the main.cpp, Makefile, config directory, and the Netbeans IDE project directory outside of the git repository, using tweaks to the Makefile paths so that the kernel will find the config directory outside of the kernel, not the one inside it.

To get started with out of git tree projects, there is a perl script that is used to easily set everything up. For example, suppose you are in the directory of your git repository where you have added the miosix-kernel submodule, and want to set up an out of git tree project there, open a shell and type

perl miosix-kernel/miosix/_tools/init_project_out_of_git_tree.pl

The script will create a Miosix out of git tree project in the directory it is called, basically creating a config directory with a copy of the configuration files you can edit, a Makefile and a main.cpp as usual, as well as a new miosix_np_2 directory with a Netbeans IDE project.

The main advantage of this solution is that it keeps your application and the kernel in two separate git repositories. The disadvantage is that if you need to make changes to the kernel other than to configuration files, you will need to clone the miosix-kernel repository anyway, as well as having to manage the complexity of having two git repositories.

Forking the Miosix git repository

Forking the Miosix git repository simply means cloning the kernel repository and starting to write your application there. To clone the git repository you simply type the following commands:

git clone https://miosix.org/git-public/miosix-kernel.git
cd miosix-kernel
git fetch origin

This will create a directory, miosix-kernel on your filesystem. Within that directory, which is also called the Miosix top-level directory there are two more directories, miosix which contains the kernel sources, and miosix_np_2 with the Netbeans IDE project files. Lastly, there are two files, main.cpp, where it is possible to start writing your application, and a Makefile where you can add other C or C++ source files to be compiled.

The top-level directory has been kept free of clutter, so as to invite users to write applications directly there.

Making changes

Once you start making changes you can simply commit in the cloned git repository. If you need to share your changes, perhaps because there are multiple developers, git allows to have multiple remotes for a repository, so you can leave the default remote to periodically pull updates and bugfixes from the upstream Miosix repository, as well as push and pull from your personal remote repository.

The main advantage of this approach is that everything, both the kernel and your code are under a single git repository, so you don't have to manage multiple repositories.

Contributing to Miosix

If you make changes to the kernel and want to contribute them back to mainline Miosix, you can get in contact via email with fede.tft&&miosix.org (s/&&/@/). You will be required to make a format-patch with the changes you want to be pushed upstream.

If you plan to make significant contributions, please get in touch to discuss how to best integrate changes and streamline the process.

Contributions guidelines

When submitting patches for inclusion, please make sure that commits are small and self-contained, in order to simplify the integration process.

Make sure that commits that you propose for upstream inclusion do not contain changes to the following files and directories:

• The top-level main.cpp and Makefile. If you add example code to test a new feature and want to contribute it back, consider adding it to _miosix/examples or _miosix/tools instead.
• The miosix_np_2 directory. If you work on Miosix using Netbeans, the IDE will make changes to files in this directory. These are local changes that only matter to you, and should not be included in patches.
• The configuration options in miosix/config/Makefile.inc and miosix/config/miosix_settings.h. In detail, when compiling the kernel, you will have to make changes to select a board and tweak some options. These changes only matter to you, and should not be included in patches. If on the other hand you are adding configuration options, perhaps because you are porting Miosix to another board, then it is ok to include those changes in commits to be sent upstream.

If you don't want to have changes to those files show up on each git status, together with the burden of remembering not to accidentally git add those, you can exclude those files from git by running the following commands

git update-index --skip-worktree main.cpp   
git update-index --skip-worktree Makefile   
git update-index --skip-worktree miosix_np_2/
# These two only if you are sure that you will not make additions to those files that need to be pushed upstream
git update-index --skip-worktree miosix/config/Makefile.inc
git update-index --skip-worktree miosix/config/miosix_settings.h

Keep in mind that doing so makes it more difficult to switch between branches, as changes to skipped files won't show up on git status but will prevent switching to another branch.

Another way to enforce those rules is to use the out of git tree project feature that replicates all those files out of the git repository. If you are also using submodules, it is recommended to read the git documentation regarding submodules [1] in order to understand how to make changes to submodules.