Deimos git branch structure

This page explains how to setup a git repository for deimos, so that changes to the C headers can be merged into the D interface files automatically or with minimal human intervention. As an example, we'll create a binding to the simple systemd reference-implementation api.

Initial setup

Create the git repository

As the first step, we have to create an empty git repository. Create a directory for your project (in this case we'll call it systemd):

mkdir systemd

then change into that directory:

cd systemd

Now we can create the repository using

git init

As git doesn't allow us to create a new branch as long as there is no commit on the master branch, we have to add a file to the git repository and commit it. I choose to commit an empty .gitignore file:

touch .gitignore
git add .gitignore
git commit -m "Create repository"

Add the C headers

We'll now create a branch where we'll place the unmodified c headers and then change to that branch:

git branch c_headers
git checkout c_headers

Now it's time to add the c headers, but do not modify them in any way and keep the original filenames and folder structure!

mkdir deimos
cp /some/path/sd-daemon.h deimos/sd-daemon.h
cp /some/path/sd-readahead.h deimos/sd-readahead.h

Commit the C headers. Try to use a descriptive commit message:

git add deimos/sd-daemon.h
git add deimos/sd-readahead.h
git commit -m "Add C headers for version systemd-37"

Create the D directory structure

We now change back to the master branch, where we'll place our translated C import files:

git checkout master

The next step is merging the C headers branch into our master branch:

git merge c_headers

We'll now fix the directory structure and filenames to match D conventions. Make sure to use git mv and not the mv command!

git mv deimos/sd-daemon.h deimos/sd_daemon.d
git mv deimos/sd-daemon.h deimos/sd_daemon.d

Add those changes and commit them:

git add --all
git commit -m "Rename C headers to match D naming conventions"

Translate the C headers into D import files

It's now time to translate the C headers into D files. When you're finished simply add and commit.

git add deimos/sd_daemon.d
git add deimos/sd_readahead.d
git commit -m "Initial D bindings"

The initial repository setup is now complete. #Update the D files The following part shows how this special setup will help us to merge changes from the C headers. Consider a new version of systemd has been released and we want to update the D import files.

##Add the new C headers First checkout the C branch, simply copy the new headers into the correct place, replacing the old ones. Once you're finished, commit:

git checkout c_headers
rm deimos/sd-daemon.h
cp /some/path/sd-daemon.h deimos/sd-daemon.h
git add deimos/sd-daemon.h
git commit -m "Update C headers to systemd-38"

##Merge the changes into the D files Merging the changes into the D files is now very simple: Change to the master branch, and merge the c_headers branch. Make sure you've set up your diff/merge tools correctly.

git checkout master
git merge c_headers

For simple changes, the merge will often work automatically. But remember: git only merges the new parts from the C headers into the correct place in your D headers, but those parts are still C code! They could still contain #ifdefs and other C specific stuff. You'll now have to review those merged code snippets and translate them to D. Note: If you can find a way to convince git to invoke your merge tool although the code seems to merge automatically, that's the best solution. If git did an automatic merge and you want to find the C code parts introduced by this merge, a graphical diff tool like giggle is very useful.