Manual Contents | User Forum | CVS | Topic Index | Frequently Used

Building G3D

This document describes the structure of the source distribution for the G3D C++ library. It is for programmers who need to modify the library itself.

For Win32 and Linux, you do not need to build the library to use it! Precompiled Win32 and Linux binaries are provided at http://g3d-cpp.sf.net. For Mac OS X, you do need to build it, but it's relatively easy to build.

This distribution contains two CVS modules: cpp and data. Together these have all of the files you need to build and install the library on Windows or Linux. They also contain some files for building on OS/X. OS/X is not a supported platform, however.

It is assumed that you obtained this source by checking it out of SourceForge.net CVS for the "g3d-cpp" project (http://sf.net/projects/g3d-cpp) or downloading a release zipfile. To check out via anonymous CVS:

cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/g3d-cpp login 
cvs -z3 -d:pserver:anonymous@cvs.sf.net:/cvsroot/g3d-cpp co cpp
cvs -z3 -d:pserver:anonymous@cvs.sf.net:/cvsroot/g3d-cpp co data

Windows 2000 or XP

The Cygwin versions of doxygen and python do not execute correctly from a Windows command prompt, so you will have to download and install them separately if you have Cygwin.

Install Microsoft Visual Studio 6.0.
Install the Visual Studio 6.0 Service Pack 5.
Install the Visual Studio 6.0 Processor Pack for Service Pack 5.
Install the Python 2.2.3 tool.
Install the Doxygen 1.3.2 tool.
Install the SDL 1.2.7 Development Library (G3D is not compatible with SDL 1.2.6).
Add the paths for these tools to your PATH environment variable (Control Panel -> System -> Advanced -> Environment Variables). These are usually C:\Program Files\Microsoft Visual Studio\Common\MSDev98\Bin\;c:\doxygen;c:\python\bin.
Log out so all changes can take effect.
Run "build install libdir" in the cpp directory, where libdir is the parent directory you want to install into (e.g. "c:\libraries")

Linux

Install gcc 3.3.
Install the Python 2.2.3 tool.
Install the Doxygen 1.3.2 tool.
Install the SDL 1.2.7 Development Library.
Install the automake 1.7.5 tool (and the corresponding aclocal version).
Install the autoconf 2.57 tool.
Add the paths for these tools to your PATH environment variable (usually in your .cshrc, .tcshrc, or .bashrc file).
TODO: set up LD_LIBRARY_PATH
Log out so all changes can take effect.
Run "chmod u+x build" in the cpp directory.
Run "./build install libdir" in the cpp directory, where libdir is the parent directory you want to install into (e.g. "/u/$USER/lib")

Mac OS X

We recommend using Xcode 2.1 or 2.2 to build G3D, and then using the same version of Xcode to build your G3D programs, both using Xcode project files included in the source distribution, and from the command line. Here, we first give instructions to get prerequisites required to build either way, then directions to build with Xcode, then include the instructions for a more traditional, unix/command-line style build.

Common Setup

Install Apple's Xcode Development Environment 2.2, from Apple's Developer Site. (It may seem like you have to pay for the privilege of joining the Apple Developer Connection (ADC), but in fact you can get a web-only membership for free.)
Install the SDL 1.2.9 Development Library.

Building G3D with Xcode

Get a copy of the source tree, either via cvs or via the src zip, available on the downloads page. Expand the zip.
Double-click on G3D/cpp/G3DOSX/G3DOSX.xcodeproj. This will launch Xcode.
In Xcode, locate the main toolbar. At the far left of the toolbar, set the active target to G3DTest. Hit "Build."
Command-Shift-B brings up the "Build Results" window. The last line in the output in that window should be "Build succeeded."
With the active target set to G3DTest, hit the "Run" button. The console should come up and give you lots of interesting information about G3D's performance on your machine. Congratulations, you have built G3D on Mac OS X.
Having built G3D, you will probably want to run a demo. We recommend taking advantage of the *.xcodeproj files included in some of the demo directories. They work, if you leave them in their current directory. Open G3D/cpp/source/demos/VAR_Demo/VAR_Demo.xcodeproj. Hit "Build and Go", and you should see little purple and orange planes flying around in a circle.

Building G3D from the command line

Install Doxygen
Add the path for Doxygen to your PATH environment variable (by adding PATH=/Applications/Doxygen.app/Contents/Resources/:$PATH to your ~/.bashrc file).
TODO: set up LD_LIBRARY_PATH
Type source ~/.bashrc or log out so all changes can take effect.
Execute chmod u+x build in the cpp directory.
Run ./build install targetdir in the cpp directory
The library and demos will compile into targetdir

Directories

You are at the root of the directory tree for G3D (which is referred to as "cpp" in this document). This is a CVS checkout of the cpp module. The ../data directory contains a checkout of the data directory. The subdirectories have the following structure:

|-cpp                              The cpp module
|  |-source
|  |  |-data                    
|  |  |-demos                      A duplicate of some essential files from the data module
|  |  |  |-font
|  |  |  ...
|  |  |-G3Dcpp
|  |  |-GLG3Dcpp
|  |  |-IJG
|  |  |-html
|  |  |-include
|  |  |  |-G3D
|  |  |  |-GLG3D
|  |  |  |-glh                     The latest GL extensions.  G3D doesn't use the system GL headers.
|  |  |  |  |-extgen
|  |  |  |  '-GL
|  |  |  '-zlib
|  |  |-lib
|  |  '-test
|  |-install                       The library ready for use (copy to the location of your choice)
|  |-release                       Official G3D release zipfiles (only Morgan needs these)
|  '-temp
'-data                             The data module
   |-font
   |-quake2
   ...

The red directories can be deleted; they are built from the source directory. Some subdirectories are not shown.

In the distribution, the cpp/data directory is stored in g3d-data-M_mm.zip and the other (built) files are in g3d-cpp-M_mm.zip. They are separated because the data is so large. Users who want source code can download it from CVS following the instructions at http://sourceforge.net/cvs/?group_id=76879

Meta-Build targets

build install

Builds a local installation for using the library. This is how Linux users generate the .so's to link against.

build release (Windows only)

Builds install, then zips g3d-cpp-M_mm.zip and g3d-data-M_mm.zip for uploading to Brown/G3D for users. To make a release, you must have already done 'build install' on Linux and copied the binaries over. Note that the demos go in the data zipfile, not the cpp zipfile. Also, note that the release process actually deletes the demos and data from the install directory.

build clean

Remove cpp/temp
Remove cpp/install
Remove cpp/release

Build Targets

The build script is a Python script that is executed from a shell script. It accepts a single argument which is the name of the build target. Specifications for the targets follow. The next section of this document describes the meta-targets for making a release.

lib

Build cpp/install/lib/G3D.lib, cpp/install/lib/G3D-debug.lib, cpp/install/lib/GLG3D.lib, cpp/install/lib/GLG3D-debug.lib (or corresponding .a/.so files on Linux)
Copy any out of date files from cpp/source/lib to cpp/install/lib

doc

Execute doxygen in cpp/source
Copy any out of date files from cpp/source/html to cpp/build/html

test

Compile cpp/source/test/*.cpp to cpp/temp/test/Debug/Test.exe
Execute cpp/temp/test/Debug/Test.exe
Complain if the exit code was non-zero

* "All files" refers to any file except those matching the following regular expressions:

'\.ncb$', '\.opt$', '\.ilk$', '\.pdb$', '\.bsc$', '\.o$', '\.obj$', '\.pyc$', '\.plg$', '^#.*#$', '~$', '^log.txt$', '^stderr.txt$', '^stdout.txt$', '\.log$', '^graveyard$', '^CVS$', '^Debug$', '^Release$'