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

Appendix B. FAQ

B.1. Compiling

Q: How do I build a 32-bit version of bugle on an AMD64 system?
Q: Why is a recent (>4.0) version of GCC required?
Q: Why I am getting an error like Invalid option -fdump-translation-unit?
Q: I get an error trying to move gl.c.tu, saying that the file does not exist.
Q: When I compile with GCC 4.2, compilation seems to hang on src/lib.c.
Q: I am getting the error could not find GL/glext.h.
Q: I am using the NVIDIA header files, and I am getting errors about conflicting definitions.
Q: I am using Gentoo, and during compilation of bugle I get errors similar to this: /usr/lib/opengl/nvidia/lib/libGLcore.so.1: undefined reference to `_nv000016gl'.
Q: I am using Fedora 10, and when I run glxgears under bugle it exits with the message Error: couldn't get an RGB, Double-buffered visual.
Q: I am using ATI drivers and when I run configure, it does not find glBegin in -lGL.

Q:

How do I build a 32-bit version of bugle on an AMD64 system?

A:

The exact details will depend on your OS. Here is what I do on Gentoo:

$ scons CCFLAGS="-m32" LINKFLAGS="-m32" without_gtkglext=yes without_lavc=yes \
    libdir=/usr/local/lib32 bindir=/usr/local/bin32

The without_gtkglext and without_lavc options are there because I do not have 32-bit versions of those libraries installed, and pkg-config will provide information about the 64-bit installs instead.

Q:

Why is a recent (>4.0) version of GCC required?

A:

Bugle is driven by a number of tables that list all the information about the various types and functions in OpenGL. To capture this information, it is necessary to parse the OpenGL header files. It would be very difficult to write a parser to do this robustly, but GCC already knows how to do this. Unfortunately, the ability to extract a parse tree from GCC (the -fdump-translation-unit option) was only added sometime after 3.0, and is also broken in 4.0 (fixed in 4.1).

To avoid namespace pollution, bugle passes -fvisibility=hidden to GCC, which is only supported since GCC 4. If you need to build with GCC 3.x, you can try removing this option, but doing so is unsupported.

Q:

Why I am getting an error like Invalid option -fdump-translation-unit?

A:

You need to use a version of GCC that supports this flag. See the previous question for details.

Q:

I get an error trying to move gl.c.tu, saying that the file does not exist.

A:

You are probably using GCC 4.0, which has broken support for -fdump-translation-unit (GCC bug 18279). Use a newer GCC version.

Q:

When I compile with GCC 4.2, compilation seems to hang on src/lib.c.

A:

There is a performance bug in GCC 4.2.2, possibly #30052 but possibly not. Either downgrade to 4.1, upgrade to a version where the bug is fixed, or compile without optimisation (-O0).

Q:

I am getting the error could not find GL/glext.h.

A:

You need to have this file, as it defines extensions to OpenGL that an application might use. You can obtain the latest copy from http://www.opengl.org/registry. If you don't want to put it in your system include directories, you can create a GL subdirectory of the bugle source directory and put it there.

Q:

I am using the NVIDIA header files, and I am getting errors about conflicting definitions.

A:

Try upgrading to the latest NVIDIA drivers. The 60 series seem to fix many of the problems in older header files.

Alternatively, use the headers from Mesa. You can place them into a GL subdirectory of the source if you prefer not to overwrite the system headers.

Q:

I am using Gentoo, and during compilation of bugle I get errors similar to this: /usr/lib/opengl/nvidia/lib/libGLcore.so.1: undefined reference to `_nv000016gl'.

A:

This seems to be a problem with Gentoo's system for switching between OpenGL drivers, that causes part of the build process to use the X11 software drivers. A workaround is to switch to the X11 drivers for compilation and installation of bugle:

  1. Run eselect opengl set xorg-x11 (or opengl-update xorg-x11 on older systems) as root.

  2. Ensure that your environment is up to date e.g., source /etc/profile in the shell you will use to compile bugle.

  3. Unpack a fresh copy of bugle (do not use a previously configured copy), compile and install it.

  4. Switch back to the NVIDIA OpenGL driver (eselect opengl set nvidia).

Q:

I am using Fedora 10, and when I run glxgears under bugle it exits with the message Error: couldn't get an RGB, Double-buffered visual.

A:

This seems to be caused by having two different versions of libGL.so on your system, and bugle picking up symbols from the wrong one. Find out which one is correct (ldd should help), then move other ones out of the way.

Q:

I am using ATI drivers and when I run configure, it does not find glBegin in -lGL.

A:

I have had this reported by one Debian user, but didn't get further details on hardware or driver version. It appears that this version depended on but did not link to libpthread. While it is possible to hack this in configure.ac, the same user reported other problems with this driver, and it is probably best to upgrade to a newer driver.

B.2. Running

Q: I just upgraded bugle and now it crashes. What's wrong?
Q: What is the performance penalty?
Q: I wrote LD_PRELOAD=libbugle.so program and it failed, what's up?
Q: How do I get a stack trace when my program crashes inside the OpenGL driver?
Q: Do I need to always set BUGLE_CHAIN?
Q: Can I avoid using LD_PRELOAD?
Q: How do you get SDL-based apps to use BuGLe?
Q: How do you get Quake3 or Doom3 to use BuGLe?
Q: How do you get QT-based apps to use BuGLe?
Q: I am using GL_EXT_framebuffer_object to render to texture, but the results do not appear in the texture viewer of gldb-gui.
Q: How can I use bugle to debug WebGL applications?

Q:

I just upgraded bugle and now it crashes. What's wrong?

A:

You may have ended up with a mix of old and new versions that don't work together. Try removing all files related to the previous version of bugle (in particular, libbugle.so*, libbugleutils.so* and all the filter-set libraries (in /usr/local/lib/bugle for example). Also be sure to run ldconfig after installation.

Q:

What is the performance penalty?

A:

That depends on what you're doing with the library. If you only use filter-sets that intercept a few functions (like showstats), then all other functions suffer only a small penalty. Using filter-sets that check for error after every function (including showerror and the debugger) adds a much bigger penalty.

To give you an example, here are some rough numbers for Quake3 1.34_rc3 (64-bit build from source) on demo four:

without bugle351.5
none340.0
logfps337.0
showfps309.5
trace121.0
gldb-gui109.0

Tracing is particularly slow because it does file I/O, as well as a lot of text formatting. The overhead will also depend on the CPU/GPU balance. GPU-bound programs will be less affected by overheads.

Q:

I wrote LD_PRELOAD=libbugle.so program and it failed, what's up?

A:

You either need to specify a full path to libbugle.so, or else place it somewhere that the linker will find. On GNU systems, you can add the appropriate path to /etc/ld.so.conf.

Q:

How do I get a stack trace when my program crashes inside the OpenGL driver?

A:

Use the bugle-unwindstack(7) filter-set. See the manual page for more information.

A:

Use the bugle-log(7) filter-set, and turn on the flush option (see the example in doc/examples/filters). Then after your program crashes, the last entry in the log file will most likely be the one just before the crash.

Q:

Do I need to always set BUGLE_CHAIN?

A:

No, the first chain in the configuration file is the default.

Q:

Can I avoid using LD_PRELOAD?

A:

Yes, you can specify -lbugle in place of -lGL when you link your program. If it is not installed in a standard directory, you may need extra compiler flags, such as -L/path/to/bugle -Wl,-rpath -Wl,/path/to/bugle.

Q:

How do you get SDL-based apps to use BuGLe?

A:

On GNU systems, they should work as is. On some systems, it may be necessary to run them as

LD_PRELOAD=/path/to/libbugle.so SDL_VIDEO_GL_DRIVER=/path/to/libbugle.so program

Q:

How do you get Quake3 or Doom3 to use BuGLe?

A:

On GNU systems, they should work as is. On some systems, run it as

LD_PRELOAD=/path/to/libbugle.so quake3 +set r_glDriver /path/to/libbugle.so

Note that Quake3 and Doom3 are 32-bit binaries, so if you have an AMD64 system you will need to compile a 32-bit bugle.

Q:

How do you get QT-based apps to use BuGLe?

A:

On GNU systems, they should work as is. There is currently no known workaround for systems that don't support dlsym with the RTLD_NEXT flag.

Q:

I am using GL_EXT_framebuffer_object to render to texture, but the results do not appear in the texture viewer of gldb-gui.

A:

This is a known bug in NVIDIA's 76.76 driver. It is fixed in the 80 series drivers. The results should appear in the framebuffer viewer.

Q:

How can I use bugle to debug WebGL applications?

A:

This is a little tricky because of the way modern browsers use multiple processes, so your mileage might vary. It probably also depends on details of the WebGL implementation and also on whether the browser uses OpenGL for its rendering engine. I have been able to successfully attach the debugger to a WebGL application in Chromium under Ubuntu using a the section called “TCP/IP connection” and passing the --single-process parameter to Chromium.

On my system, chromium-browser is actually a shell script that launches the executable. Rather than setting LD_PRELOAD on the command line (which would just debug the shell), I edited a copy of the shell script to set it immediately before launching the executable.

B.3. Miscellaneous

Q: Why is there a mix of C and C++ code?

Q:

Why is there a mix of C and C++ code?

A:

The library itself is written entirely in C. This is mainly because a C++ library will drag libstdc++ in with it, and this has been found to create some problems when forcing linking to an application that already depends on a conflicting version of libstdc++. There is still a dependence on libc, but libc is less of a moving target. The code generator is written in C++, since it makes the coding easier and does not introduce the dependency issues above.


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