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.
Python 2 (2.7 is tested, older versions may work)
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 Perl and gcc.
Here is the list of steps I used to install on 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.
Install MinGW. I used the command-line installer interface (mingw-get). See the Getting Started page for more details.
PATHappropriately, I ran
mingw-get install gcc g++ mingw-developer-toolkit gdb msys-zip msys-unzip
Then I launched msys.bat and ran /postinstall/pi.sh.
Download mingw-libgnurx from the user contributed files folder (both the dev and bin packages), and unpack them into
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.
Download and install SCons 2.1.
Download the GTK+ bundle (2.16.6) from gtk.org, and unpack it somewhere (e.g.
At the time of writing, the latest released version of gtkglext (1.2.0) does not work with GTK+ versions 2.18 or higher.
If you are planning to use a toolchain other than MinGW (e.g. MSVC), do not overlay GTK+ on the MinGW installation as it cause MinGW's system headers to be used when trying to build against GTK+.
You will also need to set (or add to) some environment variables to allow GTK+ to be detected. For example (the syntax assumes variables are being set from within MSYS):
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
make install. This will overlay gtkglext on your GTK+ installation; you could also choose to install it separately, but you will then need to add to
Download the source for GLEW 1.7 and unpack it into a temporary location and build it using make, then install it with the command
make GLEW_DEST=/mingw install.
This will overlay GLEW on your MinGW installation; the alternative is to install it elsewhere and set
If you are building bugle with MSVC, you should instead use the binary download for GLEW (the binary download will not work with MinGW).
Download the MinGW build of freeglut, and unpack it in a temporary directory. Then run
mv freeglut/lib/* /mingw/lib mv freeglut/include/GL/* /mingw/include/GL mv freeglut/*.dll /mingw/bin
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