PORTING

PORTING guide for bzflag

Follow these steps to port bzflag to a new platform.  Say the
new platform is named `foo'.

  * in src/platform/:
    * this step may be skipped if the platform you're porting to
      supports SDL and you do not want to have native graphics/audio,
      as there are preexisiting SDL* platform files.
    * implement the following files, as necessary, using an appropriate
      prefix instead of Foo.  it may be possible to use existing files
      as is, or to reuse existing code (by copying).
      * FooPlatformFactory
      * FooDisplay
      * FooMedia
      * FooVisual
      * FooWindow
    * add the platform dependent files to Makefile.am with appropriate
      'if' guards.

  * try building
    * modify configure.in for your platform - particularly
      to set the proper CFLAGS/CXXFLAGS and to insure that needed
      libraries (e.g. OpenGL, curses) can be found.
    * fix errors.  errors are typically caused by missing include
      files and a missing/different BSD sockets API.  make as few
      changes as possible to avoid breaking other platforms.
      avoid #if/#endif when you can.
    * fix warnings.  (most) warnings are there for a reason.
      listen to what they're saying and fix the code.  bzflag
      should compile cleanly (zero warnings).

  * in package:
    * create a makefile to build a package for your platform.
      a package includes all the files necessary for installing
      bzflag on the platform.  some platforms provide a standard
      software management tool (e.g. RPM on RedHat Linux and
      swmgr on Irix);  ideally, the package is built for that
      tool.  On UNIX, a gzipped tar file with an install shell
      script may be sufficient.  The Win32 package is a self
      extracting executable with a GUI front end.

Most of the bzflag code is portable C++, but there are two API's
that are not encapsulated:  OpenGL and BSD sockets.  The OpenGL
API should not present a problem, unless you intend to port to
some other graphics API for some reason, since it's identical
on all platforms.  GL/gl.h provides a #define to identify the
version of OpenGL.  All OpenGL code that's not version 1.0
compatible should be #ifdef/#endif guarded and, if possible,
also implemented with version 1.0 code for platforms that don't
support the later versions.

The BSD socket API may cause some trouble if you're not porting
to some flavor of UNIX.  Encapsulating network code is on the
to do list.

Some platform differences are handled using #ifdef/#endif
directives.  These are to be avoided when possible as they make
the code harder to read and can lead to platform differences
when code is updated for some, but not all, platforms.  Please
make use of autoconf's HAVE_* defines rather than
platform-specific predefines...code for features, not for
platforms.

Inherently non-portable code is under src/platform.  It
encapsulates windowing and audio subsystems.  (It also includes
code to read image and audio files, for historical reasons.)