Chapter 2. Installing Bugle

Table of Contents

2.1. Requirements
2.2. Configuring
2.2.1. Configuring for cross-compilation
2.3. Compiling and installing
2.4. Compiling on Windows

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 includes highly experimental and incomplete support for OpenGL ES 2 on Windows.

The following packages are required to compile bugle:

  • GCC, at least version 3.2, and not 4.0 (see the FAQ for an explanation of why).

  • A C++ compiler (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 2, the OpenGL ES 2 and EGL header files are required.

  • Perl 5

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

readline

This will enable line editing in the console debugger. The GUI debugger is the preferred method of debugging.

GTK+

This is needed for the GUI debugger.

gtkglext

This is needed for the texture and framebuffer viewers in the GUI debugger.

GLEW

GLEW is also needed for texture and framebuffer viewers.

FFmpeg

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

2.2. Configuring

Bugle uses the standard configure command for compile-time configuration. Generic instructions may be found in INSTALL in the root of the source directory. In general, configure will auto-detect optional packages and use them only if present, but you can also prevent it from depending on certain packages with the following flags. FFmpeg (lavc) in particular is a moving target and if you get compilation failures, you should try disabling it.

  • --without-lavc

  • --without-readline

  • --without-gtk

  • --without-gtkglext

Bugle does not use threads itself, but applications that it debugs might, and bugle needs to use appropriate locking and thread-local storage libraries. The correct option should be auto-detected, but you can force it with --enable-threads=model. Valid models are posix and win32.

Finally, bugle intercepts events from X11 and Windows. While there are no known cases of this causing problems, it is difficult to make the interception completely transparent, and so the --disable-input option is available to disable it at compile time. It is also required when using EGL on a platform other than X11 or Windows.

2.2.1. Configuring for cross-compilation

If possible, the best way to do cross-compilation is to use scratchbox, where it should all work seamlessly. However, scratchbox only supports a limited set of cross-compilation targets. If you want to do cross-compilation, you will need to jump through some extra hoops.

First, run configure in the top-level directory, passing the appropriate --host option for your cross-compiler. Also make sure that the appropriate header files and libraries for the cross-compilation target are available. You might also need to pass extra options to configure to disable optional features that are incorrectly detected (see above).

Next, change into the budgie subdirectory and run the configure script there (if you are configuring in a different directory from the source, you will need to be in the budgie subdirectory of the build directory, running the configure script from the budgie subdirectory of the source. When doing this, configure for your native compiler. This is necessary because the program that is built in this directory is run on the build machine to produce source code, not on the host.

2.3. Compiling and installing

Compilation is as simple as running make. Before installing, you should remove any previous installation of bugle to avoid leaving old versions of files around. If you do not have your original installation tree to run make uninstall, you should at least remove the files in /usr/local/lib/bugle and /usr/local/lib/libbugle*. To install the new version, run make install as root.

Next, you need to install some files for the user that will run bugle. Create a directory $HOME/.bugle, and copy doc/examples/filters and doc/examples/statistics into it.

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.

Here is the list of steps I used to install on Windows, including support for the debugger. The versions numbers were the latest available at the time, but newer versions should work too.

  1. Install MinGW 5.1.4, including GCC and G++, but not make.

  2. Install MSYS 1.0.10.

  3. Install msysDTK 1.0.1. Alternatively, if you have Cygwin installed, add Cygwin's bin directory to the end of PATH.

  4. Downloaded mingw-libgnurx-2.5.1-bin.tar.gz and mingw-libgnurx-2.5.1-dev.tar.gz from the MinGW page, and unpacked both into /mingw (i.e., the directory in which MinGW is installed).

  5. Download the GTK+ bundle (2.12.11) from gtk.org, and unpack it into /mingw.

  6. Get the gtkglext installer from http://www.bonifazi.eu/appunti/, and install it into /mingw.

  7. Download the source for GLEW 1.5 and unpack it into a temporary location and built it using make, then install it with the command make GLEW_DEST=/mingw install.

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

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.