[AD] ABI document update

[Peter Wang <tjaden@xxxxxxxxxx>]

We need to update abi._tx for the 4.2 release.  The main changes I've
made so far are:

- we won't be maintaining compatibility for BeOS any more
- we'll be maintaining compatibility for Linux/x86-64 and MacOS X

We need a Mac guy to write a short section for MacOS X.

We also need to decide if we will maintain both backwards and forwards
compatibility, or just backwards compatibility.  The former means we
can't add/change/remove any (public) symbols at all.  The latter means
we can add new symbols, but we can't change or remove any.

I've toned the document down as it was, frankly, embarrassing.

Peter

@html_text_substitution=readme.txt|<a href="readme.html">readme.txt</a>
@external-css=allegro.css
@document_title=ABI compatibility information
@<pre>
@!indent
     ______   ___    ___
    /\  _  \ /\_ \  /\_ \
    \ \ \L\ \\//\ \ \//\ \      __     __   _ __   ___ 
     \ \  __ \ \ \ \  \ \ \   /'__`\ /'_ `\/\`'__\/ __`\
      \ \ \/\ \ \_\ \_ \_\ \_/\  __//\ \L\ \ \ \//\ \L\ \
       \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
        \/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
                                       /\____/
                                       \_/__/


                ABI compatibility information.

         See readme.txt for a more general overview.
@indent
@</pre>



@heading
Introduction

   Once Allegro 4.2 is released, we plan to maintain backward compatibility
   at the Application Binary Interface level for the subsequent releases of
   the 4.2.x series. For example, that means you will be able to use an
   executable compiled using version 4.2.0 with version 4.2.5 or 4.2.41 of
   the dynamically linked library.

   However, there are some guidelines (rules) you should (must) follow,
   otherwise things will not work, and you will get angry emails from
   users and from us.

   Note: ABI compatibility will only be _actively_ maintained for:
<ul>
<li>Windows on x86
<li>Linux on x86
<li>Linux on x86-64
<li>MacOS X on PowerPC
</ul>

   XXX: something about backwards vs forwards compatibility



@heading
Windows notes

   If you don't need a modified version of Allegro then just link your
   program against an officially blessed non-WIP, non-CVS, non-dodgy
   version. Don't disable any features (eg. colour depths, drivers) in
   the DLL.

   If you require a modified version of Allegro, then please either
   statically link, or pick a non-standard name for the Allegro DLL.
   For example, don't distribute a modified version of Allegro under a
   name such as all42.dll or alleg42.dll. Instead, call it something
   like alcustom.dll. Even better, statically link.

   For the people who use vanilla Allegro, we will provide a set of
   "reference" DLLs. If your binary works with those then everything is
   fine. If you want to distribute Allegro DLLs with your program
   (usually a good idea), we recommend you distribute our DLLs instead
   of ones you compiled yourself.



@heading
Linux on x86 notes

   To make sure an Allegro binary compiled on your machine will work on
   another machine, do not disable any "features" with `configure'. Your
   copy of Allegro must have assembly routines, threads, modules, all
   colour depths and X11 support enabled, amongst other things. If in
   doubt, leave it at the default setting.

   When you are ready to distribute your binary, run "ldd &ltmybinary&gt".
   It should say something like:

      liballeg.so.4.2 =&gt /usr/local/lib/liballeg.so.4.2 (0xdeadbeaf)

   It should NOT say:

      liballeg.so.4.2.0 =&gt /usr/local/lib/liballeg.so.4.2.0 (0xdeadbeaf)

   If you see the latter, that would mean users with later versions of
   Allegro would not be able to run your binary.

   See also the Windows section if you need to use a modified version of
   Allegro.

   For people packaging Allegro for redistribution: Drivers that are
   built as dynamically loaded modules may be disabled or left out, but
   all others should be left in. Examples of drivers that are _not_
   dynamically loaded include: OSS digital sound and OSS MIDI. In
   short, if a program built against a copy of default-options Allegro
   will work with your final library it should be fine.



@heading
Linux on x86-64 notes

   The situation is basically the same as for Linux on x86, however
   your copy of Allegro must NOT have assembly routines enabled (it
   wouldn't work anyhow).



@heading
MacOS X notes

   XXX fill this in



@heading
Final notes

   Providing source is still better than not providing source. Binaries
   are good, however, if your code sucks and only you (with the help of
   witchcraft) can compile it.

   If you provided binaries in the past using WIP versions of Allegro,
   we politely request that you recompile your program using a stable
   version of Allegro.