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.

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

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.

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

