Miosix and git workflow

The Miosix git repository

As you should already know, 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. As the kernel is under active development, users are advised to periodically 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.

• The master branch is the most stable branch, but is also updated infrequently
• The testing branch is more up to date with the current development changes, while striving to remain production grade
• The unstable branch is where experimental changes are made. This branch may not compile and may crash unexpectedly

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

git checkout -b testing origin/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, forking the Miosix kernel git repository and developing your application there, or setting up out an out of git tree project.

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.

Setting up an out of git tree project

Out of git tree projects allow to write your application outside the Miosix top-level directory, without the need to make changes to files within the Miosix git repo at all. This allows to separate your application from Miosix, and was designed to have the miosix git repository as a git submodule of your application's git repository. This also allows to not have the source files of your application under any version control system, even though these days if you're writing code without a version control system you are really missing something.

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.

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.