Chapter 5. Hacking bugle

Table of Contents

5.1. Porting
5.1.1. Introduction
5.1.2. Binary format
5.1.3. Operating system API
5.1.4. Windowing system
5.1.5. GL-Windowing integration
5.1.6. Filesystem layout

5.1. Porting

5.1.1. Introduction

Wherever possible, autoconf, libtool and gnulib are used to hide the gory details of porting to different operating systems. However, because bugle interfaces directly into the host system in a number of ways, some work is required to port bugle to new systems.

While other projects may have simply a Windows port and a GNU port, for example, but it is not so simple for bugle. For example, one might run on Windows but using Cygwin with an X server, or on Linux but using EGL rather than GLX. Instead, a target system is based on a number of categories:

Binary format

The binary format determines the details of how dynamic linking is done and how it may be subverted. For example, the Windows PE format explicitly indicates which symbols come from which library, and hence require an entire library to be impersonated, while ELF files just list dependent libraries and dependent symbols, making it easy to replace certain symbols.

Operating system API

This determines how things like segfault handling and other low-level operations are performed. Examples are POSIX and Win32.

Windowing system

The main effect of the windowing system is to determine how keyboard and mouse events may be intercepted.

GL-Window system integration

This determines how GL interacts with the windowing system. Usually there is a one-to-one mapping (e.g., AGL, WGL, GLX), but EGL applies on any windowing system.

Filesystem layout

This determines where to look for files, namely bugle configuration files and system libraries, and potentially temporary files.

Rather than conditionally compiling code based on the particular system in use, each system is characterised by a set of defines that describe its essential properties. This makes it easier to port bugle to similar but not identical systems in future: new code is needed only for those parts either specific to the system in question, or where the new system behaves in an entirely novel way.

5.1.2. Binary format

The following properties are defined as either 0 or 1, meaning false or true; the descriptions indicate the meaning if true:

BUGLE_BINFMT_SYMBOL_BY_DSO

The binary format lists the external library that is to be used for each external symbol.

BUGLE_BINFMT_LDPRELOAD

Bugle is injected by LD_PRELOAD or an equivalent mechanism. If false, the bugle library is given the same name as the usual OpenGL library (e.g., opengl32.dll on Windows), and loads the original library with a full path.

At present the supported binary formats are PE (BUGLE_BINFMT_PE) and ELF (BUGLE_BINFMT_ELF), although other formats could well be similar enough to be put in the same category.

5.1.3. Operating system API

For the most part, code that needs to be OS API aware needs to have code implemented for each target OS. The only use of this in the API at present is the use of signal and siglongjmp to return useful information in the face of an access violation, and these functions may be detected via autoconf.

For this reason, no preprocessor symbols are currently defined to indicate the OS API. This is subject to change should a need arise.

5.1.4. Windowing system

As for OS porting, code that is windowing system specific needs to be written for each windowing system. The following window systems are defined:

  • BUGLE_WINSYS_X11

  • BUGLE_WINSYS_WINDOWS

5.1.5. GL-Windowing integration

The primary difference between GL-Windowing integration APIs is whether extension function pointers are context-dependent or constant. This is determined by BUGLE_GLWIN_CONTEXT_DEPENDENT. The only currently supported instance of this is WGL (BUGLE_GLWIN_WGL). EGL (BUGLE_GLWIN_EGL) and GLX (BUGLE_GLWIN_GLX) both require function pointers to be the same in any context.

5.1.6. Filesystem layout

Filesystem layout determines the conventional placement of files. Three variants are defined

BUGLE_FS_UNIX

Configuration files are stored in $HOME/.bugle and system libraries are searched for in /usr/lib.

BUGLE_FS_CYGMING

Configuration files are stored in $HOME/.bugle, but system libraries are searched for in GetSystemDir().