Mercurial

There are two ways you can get hold of the OGRE source: download a stable release, or retrieve a development version through Mercurial.

The source code to OGRE is held in a central repository hosted by BitBucket, which is accessible by anyone with a Mercurial compatible tool (although only registered developers can push changesets to it). If you don’t know what Mercurial is, you should visit their website for more information, but it’s a Distributed Version Control System (DVCS), which means it’s a place where a versioned history of source code can be held, and downloaded by others. You can download the command line tool (’hg’) for your platform, or if you prefer there are graphical tools like TortoiseHg. You can even browse the repository without downloading it if you wish, or see the latest commits at CIA.vc.

The advantage of getting OGRE from our Mercurial repository rather than getting a source snapshot is that you get the very latest available version, and the updates are incremental meaning you don’t download anything that has not changed. You can choose to track either our very latest changes (the ‘default’ branch), which has the potential of being unstable but gets you the absolute cutting edge, or you can choose to track the current stable branch (for example ‘v1-8′) which includes the latest bugfixes but no breaking changes.

We test our changes before submitting them to the repository, so the code you get from Mercurial should work. However, we can’t 100% guarantee that it will be stable on all platforms at all times – temporary issues may be present.

The other significant benefit of obtaining the code from Mercurial is that you can track your own modifications to it much more easily, since you are able to make local commits. You can also choose to submit those changes to us (‘upstream’) later on as a patch. Finally, you can exchange & collaborate on your own modifications to OGRE with other users if you wish, by creating a fork on BitBucket (essentially creating your own public modified version of OGRE). This is a great way to do experimental work with others outside of the core team, so that you can polish a potential future patch together or just generally play around.

Note: In order to compile the OGRE source, you will need to compile the OGRE dependencies first. Those will then later get picked up by CMake when building OGRE itself.

Development vs. Maintenance Branches

There are always two ‘branches’ of OGRE:

  1. Development (default) branch: this is the latest development version where all the new features are being added. This is fine if you want to see the very latest features, but it is inherently the least stable version, and there may be interface-breaking changes going on here. Only use the trunk if you are confident in your ability to handle the odd problem.
  2. Maintenance branches: these are branches where the API is stable within a major version. Only bugfixes are applied to these branches, and no interface-breaking changes. Only one maintenance branch is actively maintained, representing the current stable version, but others may be present from previous stables. The maintenance branches are named after the stable major version, such as ‘v1-6′ or ‘v1-7′.  The latest of these is the best branch to use if you want to keep up with the latest fixes, but need a stable development platform.

Using Mercurial

We recommend that you familiarise yourselves with the principles of Mercurial and read our developer notes.

Cloning the repository:

hg clone http://bitbucket.org/sinbad/ogre/

You will clone the whole repository, by default into a folder called ‘ogre’, but by default your working copy will be on the unstable version. To clone directly to the stable version, do this:

hg clone http://bitbucket.org/sinbad/ogre/ -u v1-9

Or alternatively just switch branches after you have cloned using the original command, by doing this in the working directory:

hg update v1-9

Once you have the repository you can switch to the different branches using that command whenever you like.

To retrieve the latest code when you already have a clone:

hg pull --rebase

This assumes you have the Rebase extension enabled, which is strongly advised if you intend on modifying OGRE. If you don’t have Rebase enabled, do this instead:

hg pull --update