PORTING guide for bzflag

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

  * in Makefile:
    * add `@echo "  make foo"' to config-sys rule
    * add foo rule similar to other platform rules

  * in configs/
    * copy config-new to config-foo
    * edit config-foo as appropriate for the platform

  * in src/platform/:
    * 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
    * copy Make-new to Make-foo
    * add the platform dependent files to PCXXFILES

  * try building
    * 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.

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.)