[About] [News] [Documentation] [Screenshots]

Chapter 2. Installing Bugle

2.1. Requirements

Bugle is intended to work on any POSIX-compliant operating system that use the X Windowing System, dynamic linking, and LD_PRELOAD for library interposition. If it fails to work on such an operating system, please let me know (I only use it on GNU/Linux). It is also supported on Windows, although this support is less complete. It also supports OpenGL ES (1.1 and 2.0), although again, support is less complete and less tested.

The following packages are required to compile bugle:

  • GCC 4.1 or higher (see the FAQ for an explanation of why). It is currently only tested with 4.6.

  • A C++ compiler with the POSIX regular expression functions (generally g++).

  • OpenGL header files, including a recent version of glext.h. A version supporting at least OpenGL 2.0 is required. For OpenGL ES, the OpenGL ES and EGL header files are required.

  • Perl 5

  • Python 2.7

  • SCons (only 2.0 is tested, other versions may work)

The following packages are not required, but if present, will enable extra functionality:


This is needed for the GUI debugger.

gtkglext, GLEW (1.6 or later)

These are needed for the texture and framebuffer viewers in the GUI debugger.


GLUT is required by the test suite.


If FFmpeg is available, the included libavcodec is used for video capture.

2.2. SCons

Bugle uses SCons rather than make as its build system. To build bugle, simply run scons in the top-level directory, and the targets will be built in the build directory. The generic SCons options can be found by running scons -H and bugle-specific options can be found by running scons --help. The options are you most likely to need are:


Remove built files (for a more thorough clean, remove the build directory).


Save the command-line variables to config.py, from where they will automatically be loaded next time. To reset variables to automatic selection, remove or edit this file.


Select the variant of OpenGL to build for. Bugle only supports one variant at a time.


Select a subset of the parts of bugle to build (useful if you are missing tools).


Select an installation prefix (similar to autoconf).

Once you have successfully built bugle, you can run scons install to install it.

2.3. Cross-compilation

Bugle supports cross-compilation with GCC. Other compilers are not yet supported but should be relatively easy to add.

First, a note about terminology. Bugle follows the autoconf conventions: the machine that you perform the compilation on is the build machine. The machine where you run the resulting interceptor is the host machine. autoconf also has the concept of a target machine, but that only applies to cross-toolchains and is not used in bugle.

The basic step required to use cross-compilation is to add the host=machine parameter to the scons command line. This causes the build to use, for example, machine-gcc in place of gcc, and similarly for other parts of the toolchain. For example, to cross-compile for ARM one could use host=arm-none-linux-gnueabi. Note that this requires the cross-compiler to be on the PATH.

Cross-compilation hosts are often a little different to the build machine, which can cause additional problems during building. Firstly, the build system uses pkg-config to detect optional packages such as GTK+, but pkg-config is likely to report information about the build machine rather than the host machine. If you know that these packages are not available on the host machine anyway, you can override the detection by specifying without-pkg=yes on the scons command line. Use scons -h to see a list of packages that can be suppressed.

In addition, a common cross-compilation host is Linux without the X Windowing System. The code to intercept X events can be disabled by specifying winsys=none.

2.4. Compiling on Windows

Installing from source on Windows is supported, but it is significantly trickier than on UNIX-like systems, and currently only recommended for experts. The intended target is MinGW; you can try using Cygwin as well, but it is not tested. You can also build using Microsoft Visual C++, but MinGW is still needed as it provides a number of the supporting tools such as gcc.

Here is the list of steps I used to install on 64-bit Windows, including support for the debugger. Except where noted, the versions numbers were the latest available at the time, but newer versions may work too. Similarly, I've listed the directory names I used, but there is no reason you can't change them, and in some cases install several packages to one directory. However, installing packages like GTK+ on top of MinGW's directory structure is not recommended, because it makes it impossible to use those packages from a different compiler (such as MSVC).

For each package you install, you will need to set PATH to include the bin directory. If there is a lib/pkgconfig directory, it should be added to PKG_CONFIG_PATH; if not, then the include directory should be added to CPATH (or INCLUDES for MSVC) and the lib directory should be added to LIBRARY_PATH.

  1. Install MinGW w64. I used the installer from mingw-builds.

  2. Install MSYS. Again, I used the binaries provided by mingw-builds. Further steps are run from inside the MSYS shell.

  3. Download the source for mingw-libgnurx from the Mingw user contributed files folder. Configure it with

    $ ./configure --prefix=/c/mingw/mingw64/x86_64-w64-mingw32

    Then run make && make install.

  4. Download and install Python 2.7 for Windows x86. Do not use Python 3.x, as some of the code in bugle is not Python 3 compatible. Also do not use the x86-64 version of Python, as the SCons installer will not detect it (this has not been tested for a while: it might be fine now).

    Also add C:\python27 and c:\python27\scripts to PATH.

  5. Download and install SCons 2.1.

  6. Download the GTK+ 2.22 binary bundle and unpack it into c:\devel\gtk+. Note: do not use GTK+ 3.

  7. Get the sources for gtkglext (1.2.0) from http://projects.gnome.org/gtkglext/download.html, and unpack them into a temporary directory. The sources contain a bug, which you should fix by running

    $ sed -i -e 's/pangox/pangowin32/g' configure

    Additionally, you need to edit Makefile.am and Makefile.in to remove -DGTK_REMOVE_DEPRECATED (remember to remove the trailing backslash from the previous line too).

    Then, run ./configure --prefix=/c/devel/gtkglext, make and make install.

  8. Download the source for GLEW 1.10 and unpack it into a temporary location and build it using make, then install it with the command make GLEW_DEST=/c/devel/glew install.

  9. Download freeglut source. Unpack it, and run ./configure --prefix=/c/devel/freeglut, make and make install.

  10. Grab the latest glext.h and wglext.h headers, and put them in /mingw/include/GL.

This should give you all the tools needed to build bugle from either a tarballed package or from subversion, with the exception that you will not be able to build the documentation. You should pass a subset of the parts parameter to the scons command-line.

If you've just done a fresh install, you should have at least GCC 4.6, but if you have an older installation you may have a bug in GCC 4.5: without -static-libstdc++ it will fail. You can fix this by adding CXX='g++ -static-libstdc++' to the scons command line.

To build with MSVC instead of MinGW, pass host-compiler=msvc on the command line.

After installation, you will have a opengl32.dll file installed. When debugging a program, you need to place this on the path ahead of the real one. This can be achieved by copying it to the same directory as the program you intend to debug.


Windows looks in its system directories before looking at PATH, so it will usually not be sufficient to add the directory to PATH.

Get BuGLe at SourceForge.net. Fast, secure and Free Open Source software downloads