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.
SCons (only 2.0 is tested, other versions may work)
The following packages are not required, but if present, will enable extra functionality:
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
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.
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
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
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
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
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
INCLUDES for MSVC) and
lib directory should be
Install MinGW w64. I used the installer from mingw-builds.
Install MSYS. Again, I used the binaries provided by mingw-builds. Further steps are run from inside the MSYS shell.
Download the source for mingw-libgnurx from the Mingw user contributed files folder. Configure it with
make && make install.
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).
Download and install SCons 2.1.
Download the GTK+ 2.22 binary bundle and unpack it into
c:\devel\gtk+. Note: do not use GTK+ 3.
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
-DGTK_REMOVE_DEPRECATED(remember to remove the trailing backslash from the previous line too).
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.
Download freeglut source. Unpack it, and run
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:
-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
so it will usually not be sufficient to add the directory to