FireBreath Tips: Working with Source Control

November 19, 2010 4 Comments by Richard

FireBreath, Source Control, and You

Recently I have been asked repeatedly about how to properly use Source Control systems with FireBreath.  Everyone has their own idea of how this should work, and that’s fine — in fact, most of my suggestions you may decide to ignore.  However, I want to put forth what I consider to be the “4 Best Practices” for keeping your FireBreath plugin in source control.

1. Use Source Control

I prefer to use Git, myself, with bzr or mercurial as close seconds.  Whatever source control system you prefer, though, I really highly recommend using something.  This isn’t advice specific to FireBreath, of course; it’s just good sense.

2. Move your projects/ directory outside of the FireBreath root

Directory Structure

This was one of the most requested features for a long time, and in 1.2.0 we finally added it. After you use fbgen.py to create your plugin project, move the projects/ dir somewhere outside of the root.  I use the following structure:

  • code/
  • code/firebreath/ – check out Firebreath here, or extract archive from the downloads area
  • code/fbprojects/ – place your projects/ directory here, or wherever you want — it’s up to you
  • code/fbprojects/MyPluginProject/ – this is what fbgen created, originally in firebreath/projects/MyPluginProject/

Generating the project files

From the code/ folder, you can then generate your project for XCode on Mac like so:

./firebreath/prepmac.sh fbprojects fbbuild

or if you are on Windows:

firebreath\prep2010.cmd fbprojects fbbuild

Linux users can use prepmake.sh or one of the others.

Please note: The Prep scripts are not intended to be run just once.  They should be run on each computer you build on, and they should be run anytime you add new files to your project or change plugin configuration options.  This is how CMake works, and FireBreath plugins rely on CMake to build. You can ignore this advice, but you will regret doing so.

3. Don’t put your build directory in version control

The build directory should not be in version control.  As many have noted, the paths are all absolute and not relative, and even if you were to fix this it would just make it harder to update FireBreath or change your plugin configuration.

The project files (.vcproj, .xcodeproj, makefiles, etc) are not intended to ever be edited by you.  Resist the urge to do so; I know this is a change for many, but it will simplify your lives.  The only files you should ideally change for project configuration are the cmake files in your project directory.

4. Don’t put FireBreath in the same source control tree

Many people want to keep their own copy of FireBreath internally.  This is, of course, just fine — it’s licensed under the New BSD license, so you can do about whatever you want. I strongly recommend that if you decide to do this, keep in in a git clone/fork. That way you can easily submit patches back to the FireBreath project if you make any changes, which means many others will be testing your fixes, and you can also more easily get patches from the FireBreath project into your local copy.

If you decide not to do this, still at least keep FireBreath and your projects seperate, because then you can easily update FireBreath when needed.

Wrapping up

I hope that clears up some things on this tricky topic. If you have any suggestions on how things can be improved, please feel free to let us know!  Of course, if your suggestion is “Don’t use cmake”, please make sure you have taken the time to understand why we are using it and have solutions for all the many problems that it solves =] That particular dead horse has been beaten nearly to oblivion.

Enjoy!