Platform Builder is one of those environments that really resist being put under version control. Especially if you’re new to Platform Builder, it can be a very frustrating and time consuming experience to put the environment under version control. It’s not just the cheer number of files that a Windows CE image is built from that can be hard to cope with, but also the fact that some of the Platform Builder tools don’t cope well with some version control systems.

What this article aims for is not to describe some sort of divine methodology that will work for all situations, because I don't beleave such methodologies exist. Instead, I'll try to give you a starting point; I’ll describe what I consider the minimum amount of ceremony needed to effectively version control a Platform Builder environment –the least amount of complexity that still floats the boat, so to speak. Also, I’ll cover the most usual workarounds that are needed to get a version controlled Platform Builder Environment up and running.

This article targets Windows CE 5, but I believe that the general principles discussed here apply to most versions of the Windows CE source tree.

Some Definitions

Generally I’ve tried to use the definitions from this wikipeda article about revision control. I use the term “version control” throughout the article, because I think it is a bit more general than “source control”, and a bit more self-explaining than “revision control”.

When I talk about Platform Builder in a version control context, I am refering to the source tree, “…\WINCE500\...”, that Platform Builder uses as base for creating an OS image, not the IDE itself. Also, as you may notice, I use “VC” as an acronym for “Version Control” every now and then.

Why version control?

I want to know what’s being shipped, and I want to endorse productivity through concurrency. I want to know what’s being shipped in a certain version of the product because it’s usually my butt that ends up in the frying pan when the bug reports starts to drop in. I want productivity and concurrency because I hate having my butt in the frying pan longer than necessary. With proper verison control, I have a better chanse of succeeding with my projects since it:

• enables collaborative editing and sharing of data among developers
• enables tracking what artefacts where used to produce a specific version of the product under development

A few words about choosing a version control system

So before actually explaining how I would go about version controlling Windows CE platform, just let me share with you what I find important in a good version control system. Basically, my two most important criteria for a version control system are:

• Decent branch and merge support
• Atomic commits

The ability to branch and merge efficiently is crucial for handling updates and releases the way I want. Atomic commits allows developers to construct and commit changes to multiple files as one logical change, rather than treating each file as a separate commit. With atomic commits, you’ll be able to track exactly what files where affected by a specific bugfix, feature request etc. I find this very useful.

With these two criteria I effectively disqualify for example Microsoft Source Safe, (and possibly also CVS) as a version control system suitable for Platform Builder. While it implements rudimentary branch and merge support, it is just not good enough for the kind of version control I think is needed for PB. Source Safe also lacks atomic commits, and with the massive amount of files, it’s next to impossible to figure out exactly what files where changed to fix that bug, or implement that feature. Sorry Microsoft, it’s just not good enough.

However, there are myriads of other commercial version control systems out there that will do the job just fine. If you don’t feel like spending megabucks on a commercial alternative, Subversion and TortoiseSVN is a great open source version control system and UI combo that is worth checking out.

The big picture

The CE build tree is huge.  A full install puts of well over 100000 files, and takes nearly 13 Gb of space on your hard drive. It never stops amazing me how huge this tool is.

But, from a VC point of view, the Platform Builder tree can be divided into two parts:

• Their Content
• Your Content

Basically, I define “Their Content” as made up of all the files that where put into the tree at install. It is considered bad practice to change any files provided by Microsoft. Rather than change files directly, you are advised to clone (copy) the parts of the tree that needs to be modified to a different location and modify the cloned files instead.

“Your Content” is *drum roll* the parts of the tree that you add and make changes to. Usually, you’ll need to adapt a BSP, and you’re using that BSP in a platform project. The BSP and any platform projects are “Your Content”. Also, everything else you clone or create falls under this category.

Why I like to divide the build tree into “Theirs” and “Yours” is that although it's part of the same tree, they differ in the way they evolve over time, and who evolves them, and that has implications on how to version control them. We’ll get to that soon.

Just to sort out where “Your content” usually ends up, physically, BSP:s are located under ”WINCE500\PLATFORM\<some bsp>”. A project on the other hand may or may not be located under the root build tree (“WINCE500” or whatever version or CE you’re working with). The default location for a project is under ”…\WINCE500\PBWorkspaces\<a project>”, but you can put your projects pretty much anywhere you like. Usually I recommend sticking to the standard locations if you don’t have a good reason not to.

So, to summarize, files provided by Microsoft equals stuff that you as a developer should not change. Stuff that you need to change you either clone from Microsoft’s files, create from scratch, or get from 3:rd party vendors. One typical use-case for cloning files is when modifying or creating a BSP for your hardware. Usually, you use an existing BSP as base, and modify it to fit your needs. Rather than modify the files directly (bad practice, remember?), you clone the BSP to a new BSP sub-tree and modify those files instead, keeping the original intact.