AESOP Multiplayer Game Framework: AESOP Build Instructions

These are notes on how to build the set of AESOP binaries. More...

Collaboration diagram for AESOP Build Instructions:

These are notes on how to build the set of AESOP binaries.

Table of Contents

AESOP Build + Development General Overview

Welcome to the AESOP codebase! This codebase was meant to be as extensible and usable as possible, but it does have its quirks.

The code is spread into multiple different source repositories. Why have I split the codebase into multiple repositories? In a word: dependencies. I want to make sure that core libraries are usable across a wide range of applications, not just AESOP. And even within the AESOP project, I need to make sure that code intended to run on the server does not pick up any dependencies on UI or input libraries, for instance.

In general, code is broken up into small, modular libraries. Those libraries are factored to be as general as possible, and pushed downward in the stack as far as they can go (by minimizing their dependencies). Once a code library has the minimal set of dependencies, which repository it resides in depends on what dependencies are left.

Over time, I often refactor high-level code libraries to pull out general functionality and push it down into repositories with less dependencies. This is an attempt to keep libraries decoupled and as reusable as possible.

Relevent Source Repositories

First, Don't Panic. You usually don't need to deal with all of these repositories directly. The build system should make most of this transparent. But this is here for your information.

The main repositories, and their dependencies, are:

wave-build (http://wave-build.sourceforge.net/). This contains the basic build system. Has dependencies on Perl and build frameworks such as g++ and make.
wavepacket-lib (http://wavepacket-lib.sourceforge.net/). This is a general set of libraries that can be used across many projects, not just AESOP. Depends on wave-build, and a few general libraries such as libjpeg and libpng. This is the most basic repository and the largest, since the goal is to abstract all libraries enough that they can live here.
wave-glut (http://wave-glut.sourceforge.net/). This is the GLUT/OpenGL library. Depends on OpenGL, glut, GLU, GLEW, and a few open source third-party libraries such as libmini and md3 rendering. Also depends on wavepacket-lib.
gamepad (http://gamepad.sourceforge.net/). This abstracts gamepad objects. Has no UI dependencies. Depends on wavepacket-lib.
gamepad-opengl (http://gamepad-opengl.sourceforge.net/). A small library that uses the gamepad library and OpenGL to provide graphical utilties and example programs for OpenGL. Depends on gamepad and wave-glut.
wave-audio (http://wave-audio.sourceforge.net/). A small library that uses audiere to provide 3D sound APIs. Depends on wavepacket-lib and audiere.
aesop-core (http://aesop-core.sourceforge.net/). This is the largest block of code specific to the AESOP project, including the server code, common client logic, physics engines, etc. Everything in aesop-core must be runnable on a headless server, so no UI or input dependencies are allowed.
aesop-server (http://aesop-server.sourceforge.net/). This is a very small library that exists just to provide the server binary. Depends on aesop-core.
aesop-client (http://aesop-client.sourceforge.net/). This is a reference client, available for people to tweak or use as an example to build their own. A lot of interesting client logic is actually kept in aesop-core. aesop-client contains all rendering-, audio-, or input- dependent libraries (for instance, libraries that depend on OpenGL or audio). This library depends on aesop-core, wave-glut, gamepad, and wave-audio.
aesop-mgf (http://aesop-mgf.sourceforge.net/). This is a mostly empty library that exists only to provide a single parent project that makes it easy to build the full suite of AESOP libraries. This library contains no real code, just a lot of documentation. Depends on aesop-client and aesop-server.

Library Philosophy

As noted above, code is refactored as much as possible to stay in very small, modular libraries. Many libraries consist of only a single header and cpp file! That's fine. Only a few libraries contain multiple cpp files, and if a library contains too many, that is a sign that more refactoring is required.

The goal is to keep complexity tightly contained within small modules. Header files should be very simple, with all implementation details hidden in the cpp file. I know this codebase takes some of these concepts to extremes but it is the only way I've found I can keep a large codebase maintainable given my short attention span.

Library Tests

Each library (may) contain its own set of unit tests and/or demo/example programs. These live in a test directory within the library directory. The test directory has special semantics: each cpp file is used to generate a stand-alone binary of the same name, unlike library directories where all cpp files are used to create a single archive file.

One of the goals of refactoring code into small libraries is that then it is easier to build test coverage.

The test infrastructure was built some time after many of the repositories were set up, so not all libraries have test subdirectories. But these are being added all the time.

At the moment, the build system does not provide support for running a bank of tests, such as by running "make check". But that will be added in the future. For now, the test subdirectories and binaries at least help to develop and test libraries in isolation.

The Setup Program

You can read below for more information about AESOP dependencies. In general, I've tried to make things as simple as possible by having the build system fetch as many dependencies automatically as it can.

In the wave-build set of build tools, there is a program (perl script) named Setup that knows how to fetch remote build instruction files and then automatically pull down repositories of the appropriate version.

The general rules are:

Use Setup to pull down and refresh local copies of repositories. It is safe to run Setup multiple times (it will refresh local copies but not damage local copies). Be aware, however, that this may result in merge conflicts or other usual complications due to re-syncing to a remote authoritative source repository.
Use make to make binaries locally. Make will only work with local copies of repositories and will never attempt to sync to remote repositories.

AESOP Build Dependencies.

If you want to build and run a local AESOP source tree, you'll have to get all of the dependencies lined up.

There are several dependencies of AESOP! Although I tried to keep this sort of dependency handling to a minimum, I also wanted to re-use as much code as possible. So there are dependencies.

These are the dependencies I'm aware of, and instructions (or at least pointers) for installing them. I think it is safest to install them in this order ("safe" in the sense that some of these depend on others). [This is the order for installation if you build aesop-server first, then aesop-client.]

Wavepacket Libraries

wavepacket-lib is a library repository, written by me. It is a separate repository because it contains low-level libraries used by multiple other repositories/projects.

NOTE: you must keep your svn repositories as child folders within a single parent folder. For instance, I keep all of my svn repositories in a parent folder named "svn", off my personal home directory. But the point is that all svn local directories are peers of each other in the local filesystem.

You can retrieve wavepacket-lib from sourceforge by running this from within your parent directory:

 %  svn co https://wavepacket-lib.svn.sourceforge.net/svnroot/wavepacket-lib wavepacket-lib

That will check out a local version of the wavepacket-lib repository, and put it in a local subdirectory named "wavepacket-lib". Again, that should be a peer to your "aesop" directory.

glut: the OpenGL Utility Toolkit

A very easy dependency to obtain and install! Installs via yum. As root:

 % yum install freeglut-devel

(This assumes you've already got OpenGL installed on your machine)

Bullet Physics Library

See http://www.bulletphysics.com/Bullet/wordpress/

Sadly, Bullet does not have a simple (yum) install at this point. This is what I did to install (Fedora 10):

Go to that site, click on the "Bullet Download" link.
Click on the "bullet-2.73-sp1.tgz" link (because I'm on Linux)
Download and save the file locally
Personally, I create a "/usr/share/bullet" directory, and install there
Note that I build + install bullet as root! That is overkill. You can build as another user, and only install as root.
To install:
- Go to the build directory ("/usr/share/bullet" in my case)
- Copy the bullet.tgz file there if necessary
- Unzip running % gunzip bullet-2.73-sp1.tgz
- De-archive running % tar -xf bullet-2.73-sp1.tar
- Go into the new bullet-2.73 directory
- Read the INSTALL file! Avoid jam
- Build and install bullet:
```
        % ./autogen.sh
        % ./configure
        % make              (takes a long time!)
        % make install      (run this as root)
```

Sadly, there is still more to do. First, add a symlink so the headers can be found:

        % cd /usr/local/include
        % ln -sf /usr/share/bullet/bullet-2.73/src bullet

tcsh Shell (needed by libMini)

Annoyingly, this is only needed by libmini's build script. But it isn't too hard to install:

  % yum install tcsh

squish compression library (used by libMini)

Squish is easy to get, but I found it didn't compile! To get it to work, I had to:

Download the .tar.gz file from http://code.google.com/p/libsquish/
unzip and untar (tar -xf) into a local directory
build by typing % make
if that fails, edit squish.h and add this to the top:
```
      #ifndef INT_MAX
      #define INT_MAX 0x7fffffff
      #endif    // INT_MAX
```
(or add a include to whatever file defines INT_MAX)
% make (should work now)
% make install (as root)

libMini terrain library

I'm not aware of a way to install using yum. The libmini package can be downloaded from http://www.stereofx.org/download/

I have used libmin-8.9 successfully.

To install:

download the .zip file
unzip in a local directory
build the configure script by running % ./build.sh
install with % make install

Building the AESOP Tools and Applications

Typically there are only two binaries you care about: the client and server. There are tools and tests you can build as well, but most of the time is spent working with the client and server. Fortunately, building is the same for everything.

AESOP uses the Wavepacket Build System, see http://wavepacket-lib.sourceforge.net/group__build.html

To build anything, go to the source directory and type

 % make

Directories containing anything buildable also have a Makefile, so you can type

 % make

pretty much anywhere and code should recursively build.

That should do it! If the target is an application or tool, the binary will be copied into the aesop/obj/bin directory. Libraries won't be copied, they will remain in their aesop/obj/lib directory for linking with apps and tools.

If make fails, that's a sign that the Wavepacket Libraries haven't been installed properly. See Wavepacket Libraries.

As an example, to build and run the server, you would:

 % cd aesop/app/aesop-server
 % make

(although if you ran make from the root of the svn tree, that would compile the server along with everything else).

That would build the server, which has the side-effect of "installing" the server binary into the aesop/obj/bin directory.

You can clean out a local project by typing:

 % make clean

That will clean out the current project, as well as all of its (recursive) dependencies.

So if you run

 % make clean

from the svn root, you'll recursively clean out all modules.

AESOP Build Instructions [AESOP Developer's Guide]