build-notes.h

Go to the documentation of this file.

/*
 * build-notes.h
 *
 * Bogus header for doxygen.  Don't use this file!
 */

/// \ingroup dev_guide
/// \defgroup aesop_build AESOP Build Instructions
///
/// These are notes on how to build the set of AESOP binaries.
///
/// \n
/// <b>Table of Contents</b>\n
/// - \ref dev_general
///  - \ref dev_gen_repo
///  - \ref dev_gen_lib
///  - \ref dev_gen_test
///  - \ref dev_gen_setup
/// - \ref dev_dep
///  - \ref dev_dep_wave
///  - \ref dev_dep_glut
///  - \ref dev_dep_bullet
///  - \ref dev_dep_tcsh
///  - \ref dev_dep_squish
///  - \ref dev_dep_mini
/// - \ref dev_build
///
/// \n
/// \section dev_general 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. <b>Why
/// have I split the codebase into multiple repositories?</b>  In a word:
/// <i>dependencies</i>.  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.
///
/// \n
/// \subsection dev_gen_repo Relevent Source Repositories
///
/// First, <b>Don't Panic</b>.  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.
///
/// \n
/// \subsection dev_gen_lib 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.
/// 
///
/// \n
/// \subsection dev_gen_test Library Tests
///
/// Each library (may) contain its own set of unit tests and/or demo/example
/// programs.  These live in a <b>test</b> directory within the library
/// directory.  The <b>test</b> 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.
///
/// \n
/// \subsection dev_gen_setup 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 <b>Setup</b> 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 <b>make</b> to make binaries locally.  Make will only work with
///     local copies of repositories and will never attempt to sync to remote
///     repositories.
///
/// \n
/// \section dev_dep 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.]
///
/// \n
/// \subsection dev_dep_wave 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.
///
/// \b 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:
/// \code
/// %  svn co https://wavepacket-lib.svn.sourceforge.net/svnroot/wavepacket-lib wavepacket-lib
/// \endcode
/// 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.
///
/// \n
/// \subsection dev_dep_glut glut: the OpenGL Utility Toolkit
///
/// A very easy dependency to obtain and install!  Installs via yum.  As root:
/// \code
/// % yum install freeglut-devel
/// \endcode
///
/// (This assumes you've already got OpenGL installed on your machine)
///
/// \n
/// \subsection dev_dep_bullet  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:
/// \code
///        % ./autogen.sh
///        % ./configure
///        % make              (takes a long time!)
///        % make install      (run this as root)
/// \endcode
/// - Sadly, there is still more to do.  First, add a symlink so the
///    headers can be found:
/// \code
///     % cd /usr/local/include
///     % ln -sf /usr/share/bullet/bullet-2.73/src bullet
/// \endcode
///
/// \n
/// \subsection dev_dep_tcsh  tcsh Shell (needed by libMini)
///
/// Annoyingly, this is only needed by libmini's build script.  But it isn't too
/// hard to install:
/// \code
///  % yum install tcsh
/// \endcode
///
/// \n
/// \subsection dev_dep_squish 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:
/// \code
///      #ifndef INT_MAX
///      #define INT_MAX 0x7fffffff
///      #endif // INT_MAX
/// \endcode
///   (or add a #include to whatever file defines INT_MAX)
/// - % make            (should work now)
/// - % make install    (as root)
///
/// \n
/// \subsection dev_dep_mini 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
///
///
/// \n
/// \section dev_build 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
/// \code
/// % make
/// \endcode
///
/// Directories containing anything buildable also have a Makefile, so you
/// can type
/// \code
/// % make
/// \endcode
/// 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 \p make fails, that's a sign that the Wavepacket Libraries haven't
/// been installed properly.  See \ref dev_dep_wave.
///
/// As an example, to build and run the server, you would:
/// \code
/// % cd aesop/app/aesop-server
/// % make
/// \endcode
/// (although if you ran \p 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:
/// \code
/// % make clean
/// \endcode
/// That will clean out the current project, as well as all of its (recursive)
/// dependencies.
///
/// So if you run
/// \code
/// % make clean
/// \endcode
/// from the svn root, you'll recursively clean out all modules.
///