Miosix and git workflow

As you should already know, Miosix uses the git version control system to manage the kernel source code. So, 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 gitorious to look for new features and bug fixes, and pull the changes if required.

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, which is a feature added in Miosix 2.0.

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. Once you start making changes you can simply commit in the 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.

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.

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. Also, it makes it easy to make changes within the kernel sources if required, and to push them upstream.

Setting up an out of git tree project

Out of git tree projects are a new feature added in Miosix 2.0 that allows 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.