Sunday, March 10, 2013

Running TrenchBroom Quake Editor on Linux

So after successfully managing to resist the urge to write any new posts during February (I heard it was no blogging month) I'm back with my first post about one of my longer running hobbies - Quake map editing.

Recently, Kristian Duske (aka SleepwalkR) released version 1.0 of his multi-platform open source Quake editor TrenchBroom. He had previously released a preview for Mac only about a year ago and I really wanted to try it out, but since I don't have a Mac, I couldn't. Now there is a Windows and Linux version available, and after having a play with the Windows version I decided to see if I could get it running on my old ThinkPad T61 laptop, which runs Linux Mint 14 Mate Edition.

After having quite a lot of trouble getting the required wxWidgets library set up correctly, I finally managed to get TrenchBroom built and working. There are a few bugs, but it mostly works fine. Here's how to compile and run TrenchBroom for yourself.

Get the TrenchBroom source code
TrenchBroom is an open source project and is online as a GitHub repository. To get the source, you can either download it as a zip without needing to have Git installed, or install Git and clone it to your computer. Cloning has the advantage of allowing you to easily update to the latest source code and recompile to get the latest version, so here's how to clone the TrenchBroom repository:
- Make sure you have Git installed
sudo apt-get install git
- Open a terminal window and navigate to the location you would like to put TrenchBroom.
- Clone the repository
git clone

Install all dependencies needed to build TrenchBroom
The TrenchBroom source contains instructions on how to build it for each platform. For Linux, this file can be found in TrenchBroom/Linux/Build.txt. The first section lists all the libraries that you need to have installed in order to build TrenchBroom. For convenience, here are the commands needed to install them:
sudo apt-get install g++
sudo apt-get install libgtk2.0-dev
sudo apt-get install freeglut3
sudo apt-get install freeglut3-dev
sudo apt-get install mesa-common-dev
sudo apt-get install libxxf86vm-dev
Hopefully, that should be all that is needed, but if you have problems, check out the link in Build.txt.

Build wxWidgets 2.9.4
wxWidgets is a cross-platform GUI toolkit that is used to handle TrenchBroom's GUI and allows it to work the same way with minimal hassle on all supported platforms. Unfortunately, you will need to build it from the source code, which takes a little time.
- Download the wxWidgets 2.9.4 source code from here: wxWidgets-2.9.4.tar.bz2
- Extract the source to a place you want to keep it.
- Create two folders inside the main wxWidgets-2.9.4 folder called build-release and build-debug
- Enter the build-release folder and enter:
../configure --disable-shared --with-opengl --with-gtk=2

- Enter the build-debug folder and enter:
../configure --enable-debug --disable-shared --with-gtk=2

Install and configure Code::Blocks IDE
Code::Blocks is a cross platform IDE mainly aimed at c/c++ projects. You can find it in the Software Manager or simply install via the terminal:
sudo apt-get install codeblocks
Once installed, you will need to run Code::Blocks and set up a global variable in order to use wxWidgets when compiling TrenchBroom.
- Open Code::Blocks and go into Settings > Global Variables...
- Create a new variable named WXWIN under the default set by clicking the second 'new' button. 
- Set the 'base' parameter of the new WXWIN variable to point to your wxWidgets-2.9.4 folder
The variable is now set and you can close the window.

Build the TrenchBroom project in Code::Blocks
In the TrenchBroom/Linux folder, there is a Code::Blocks project file named TrenchBroom.cbp. Open it. If you have set everything up correctly, you should be able to build the project successfully and run TrenchBroom for the first time.
Compiling TrenchBroom can takes a few minutes the first time you run, but after that, you can run it as many times as you like without compiling, and any updates you might get via Git shouldn't require a full rebuild, so compiling them will take much less time.
Note that you can either build a release build, or a debug build. If you know what you are doing and want to modify the source (in which case, it might be better to fork the project) then debug is fine, but if you just want to use the editor, it's best to compile a release build, as release will likely run a bit faster.
- Select Release as the build target from Build > Select target > Release
- In Code::Blocks select Build > Build or press ctrl + F9 to build the project
- If the project builds without any errors, you should now be able to run by selecting Build > Run or pressing ctrl + F10
You should now have TrenchBroom in front of you assuming everything went ok and your computer is capable of running it.

If you open up TrenchBroom/Linux/bin there should be a folder named Release (or Debug, if you compiled a debug build). You can safely copy this folder to some other location such as your home folder, rename it to TrenchBroom and then run the executeable when you want to run TrenchBroom in the future. Keep Code::Blocks installed for building new versions though!

Note that if you installed the TrenchBroom source via Git, you can update to the latest version by opening a terminal in the folder you cloned TrenchBroom and running:
git pull origin
This will pull in all the changes up to the current version, and whilst it means you will have absolutely the most bleeding edge code, it might be less stable than specific versions. Still, if you are going to use it regularly, best just get the latest version and report any problems you find.

That's it. Happy mapping!

If you encounter any problems, don't hesitate to contact me or check out the TrenchBroom thread over at func_msgboard.

Update - Possible Issues and Solutions
Since writing this post, I've tried compiling TrenchBroom again on Ubuntu 12.10, and whilst it was mostly pretty straightforward, I had a couple of issues. There are also some issues with TrenchBroom on Linux that can be fixed by manual editing of its settings file.

SIZEOF_LONG compiler error: This can be fixed simply by commenting out the line that defines SIZEOF_LONG in the file wxWidgets-2.9.4/build-<debug/release>/lib/wx/include/gtk2-unicode-static-2.9/wx/setup.h like this:
/* The number of bytes in a long.  */
//#define SIZEOF_LONG 8

Cannot select Quake Path in TrenchBroom preferences: I'm not sure what causes this problem, but it could be a problem with wxWidgets, as I had a similar problem occur in Code::Blocks - another wxWidgets based application. If you can't correctly set the path, you will need to manually edit it by opening the hidden file .TrenchBroom in your <user>/home folder. In there you will find a line in the [General] section that starts "Quake \Path=". Write the correct path after the equals and the next time you load TrenchBroom, it should detect your Quake folder correctly. Here's an example:
Quake\ path=/home/username/Games/Quake


  1. The world desperately needs a TrenchBroom PPA.

  2. More like an TrenchBroom PKGBUILD in AUR! :-)

    This help is very debian centric unfortunately and fails when trying the Arch equivalent. I'll keep trying.