The GGZ Gaming Zone Build System
--------------------------------

GGZ uses the GNU autotools to guarantee maximum availability on all system
which provide interfaces compliant to or similar to POSIX.

This includes:
- autoconf (with autoheader)
- automake (with aclocal)
- libtool (with libtoolize)

Other components which are almost always needed are:
- perl
- gettext

To ease the life for the GGZ developers, the file ggz.m4 (formerly
acinclude.ggz) has been written which checks for a proper environment for both
GGZ programs and external programs using GGZ libraries.

Also, other checks such as for POSIX compatibility, debugging options,
package-specific checks (like ggzd databases) should be written as
additional *.m4 files. This helps keeping configure.ac clean.
M4 files are distributed automatically because aclocal recognises the files.

Platforms
---------

To avoid configuring for the most obscure platforms, while still supporting
the majority of systems in existence, the files platform.m4 and system.m4
have been introduced.
In platform.4, the minimum requirements (a decent POSIX API) are checked
for. In particular, certain headers must exist, socket functions must be
in libc or libsocket, and several functions must either exist or the
corresponding libggz functionality is disabled. Depending on the compiler,
global compilation flags might be set.
In system.m4, advanced libraries beyond the bare minimum are checked for.
If they are missing, some comfort is lost but otherwise everything is
ok. No headers, functions, compiler flags or similar are touched in here.

Paths
-----

See AC_GGZ_INIT for information about which paths are searched for in order
to find GGZ. Most importantly, all macros can be fine-tuned by adding
--with-libfoo-dir or similar options. A global switch, --with-ggz-dir,
can be given to save the work to configure all macros this way. This is useful
if a GGZ-enabled game is installed into a prefix different from the one
GGZ is installed to. Note that the game registry (ggz.modules) will then not
be touched, so that a manual integration is necessary.
See the 'packagers' file for details.

Path information within the configure script might include multi-expanding
variables. The macro AC_GGZ_UNQUOTEDPATH must be used in case a hardcoded
absolute path is needed from it (e.g. for inclusion with C sources).

Macro schema
------------

Macros are named AC_GGZ_FOO. They take either zero, one or two arguments.
In the latter case, for most it's the action to be executed if the check
succeeds and the action if it doesn't.

The following macros are relevant:
----------------------------------

AC_GGZ_INIT
  Initializes the build system. This is not strictly necessary, but includes
  some search directories by default which would otherwise have to be specified
  by the user.
  It takes no arguments by default, but understands two of them:
  * defaults
    Adds a bunch standard paths for headers, libraries and binaries to the
    search path. Currently, these are /usr and /usr/local.
    In addition, if a dedicated GGZ prefix has been given, this one is added
    also.
  * export
    The default search path is made available to external checks.

AC_GGZ_LIBGGZ
AC_GGZ_GGZCORE
AC_GGZ_GGZMOD
AC_GGZ_GGZDMOD
  Searches the GGZ libraries. Both header file and shared library must be
  present in order to be accepted.
  Those values are cached, so config.cache must be removed upon recheck.
  It takes no arguments by default, but will bail out if a library is not
  found. This can be prevented by giving two arguments:
  * "true" (1st arg)
  * ignore (2nd arg)
    Tells about the error, and leaves it to the configure.in check to further
    decide what to do.

AC_GGZ_INTL
  Sets up standard tools for internationalization.
  Takes either no or two arguments:
  * "true" (1st arg)
  * ignore (2nd arg)
    Tells about missing i18n tools but does not abort.
Note: This macro was moved out of ggz.m4 because it is not GGZ specific.

AC_GGZ_SERVER
  Searches location where to install game server room and game files to.
  Again, two arguments are possible:
  * "true" (1st arg)
  * ignore (2nd arg)
    Gives only a warning if no ggzd installation is found.

AC_GGZ_CONFIG
  Looks up the tool ggz-config which is used to install game client information
  files. Zero or two arguments are possible:
  * "true" (1st arg)
  * ignore (2nd arg)
    Ignores missing ggz-config. In this case, no *.dsc files are installed.
	This is useful for binary package creation which register the games
	after the package has been installed.

AC_GGZ_GTK, AC_GGZ_CHECK, AC_GGZ_VERSION: TODO

How to use conditional macros:
------------------------------

When using the 'ignore' keyword, it is up to configure.in to act accordingly.
At a minimum, the "lowercase" variables must be checked.
Example for libggz:
LIBGGZ_INCLUDES, LIBGGZ_LDFLAGS, LIB_GGZ
  -> "uppercase" variables intended to be used in Makefile.am.
     They are empty if the associated check failed.
libggz_includes, libggz_libraries
  -> "lowercase" variables intended to be used in configure.in.
     They're also empty when a check failed, but can be catched thereafter.

Makefile options
----------------

CFLAGS/CXXFLAGS, CPPFLAGS and LDFLAGS:
  If set before configure is run, they're picked up automatically.

  For both CPPFLAGS and LDFLAGS, the appropriate variables from the configure
  run should be used, which are named $(FOO_INCLUDES) and $(FOO_LDFLAGS).
  The CFLAGS and CXXFLAGS variables should not be used in the makefiles for
  externally determined options - use config.h instead.

LDADD/LIBADD:
  If set before configure is run, they're read in, but NOT used automatically.
  Instead, $(LDADD) must be used in the appropriate lines.
  There are 3 ways to accomplish this:
  - for libraries, use libfoo_LIBADD = $(LDADD) ...
  - for single binaries, use foo_LDADD = $(LDADD) ...
  - for multiple binaries, use LDADD += ... (as using $(LDADD) would recurse)
  Modifications in configure.ac are done by appending to this variable and
  substituting it via AC_SUBST again.

  Note that only platform-specific libraries should be added here,
  if they're not part of libc, like -liconv, -lgettext, -lnsl or -lmath.
  They're all supposed to reside in the default search path for the linker,
  so that no additional CFLAGS, LDFLAGS etc. should be needed.
  Only platform.m4 and system.m4 should handle those libraries.
  All other libraries should be given explicitely in $(LIB_FOO) notation.

It is generally discouraged to use autoconf-style variables (@VAR@).
Instead, automake-style variables ($(VAR)) are recommended.

The automake variables for the flags are prog_XXFLAGS, or AM_XXFLAGS for global
scope. The variables for the libraries are prog_LDADD, or LD_ADD (without the
AM!) for global scope.

Notes
-----

On Linux, a full shared library install takes place, meaning .so and .la files.
On FreeBSD, libtool information is omitted. Only .so files are installed.
On Windows, static libraries are built. Only .a and .la files are installed.

Josef, 25.09.2002
Update: 04.02.2005
Update: 14.09.2005
Update: 08.04.2006
Update: 06.08.2006

