This module is part of the GNOME C++ bindings effort <http://www.gtkmm.org/>.

The mm-common module provides the build infrastructure and utilities
shared among the GNOME C++ binding libraries.  It is only a required
dependency for building the C++ bindings from the gnome.org version
control repository.  An installation of mm-common is not required for
building tarball releases, unless configured to use maintainer-mode.

Release archives of mm-common include the Doxygen tag file for the
GNU C++ Library reference documentation.  It is covered by the same
licence as the source code it was extracted from.  More information
is available at <http://gcc.gnu.org/onlinedocs/libstdc++/>.

Skeleton C++ binding module
===========================

When creating a new C++ binding module based on mm-common, the easiest way
to get started is to copy the skeletonmm directory shipped with mm-common.
It contains the build support files required for a C++ binding module using
gmmproc and glibmm.

In order to create a new binding project from the copied skeleton directory,
any files which have "skeleton" in the filename must be renamed.  References
to the project name or author in the files need to be substituted with the
actual name and author of the new binding.

mm-common overview
==================

The following sections provide an overview of the various files shipped
with mm-common, and briefly explain their purpose.  Detailed documentation
and usage instructions can be found in the files themselves.

mm-common-prepare
-----------------

The mm-common-prepare shell script is installed in ${bindir} and must be
invoked from the bootstrap script of a binding module in order to set up
necessary support files in the project's source tree.  It should be run
before any of Autotools' own setup utilities.  The classic command line
options such as --copy and --force can be used to adjust the behavior of
mm-common-prepare.  A typical autogen.sh would look like this:

  #! /bin/sh -e
  test -n "$srcdir" || srcdir=`dirname "$0"`
  test -n "$srcdir" || srcdir=.

  mm-common-prepare --copy --force "$srcdir"
  autoreconf --force --install --verbose "$srcdir"
  test -n "$NOCONFIGURE" || "$srcdir/configure" --enable-maintainer-mode "$@"

Do not forget to set:

  ACLOCAL_AMFLAGS = -I build ${ACLOCAL_FLAGS}

in your project's top-level Makefile.am.  "build" should be changed to the
name of the Autoconf M4 macro subdirectory of your project's source tree.
Also note that mm-common-prepare inspects the project's configure.ac file
for the AC_CONFIG_AUX_DIR([...]) argument.  This is explained in further
detail below in the section on Automake include files.

Autoconf M4 macros
------------------

The Autoconf M4 macros are installed into the system-wide macro repository
in the ${datadir}/aclocal directory.  Since all used M4 macros are copied
into aclocal.m4, these macro files are required only in maintainer-mode.
For this reason, they are not copied into the source tree of a project by
mm-common-prepare.  If mm-common is installed to a different prefix than
Automake, it may be necessary to adjust ACLOCAL_FLAGS accordingly so that
aclocal can find the M4 files:

  export ACLOCAL_FLAGS="-I ${mm_common_prefix}/share/aclocal"

This step is not necessary when using jhbuild, as it takes care of setting
up the environment for using the locally built modules.

macros/mm-common.m4: (generated from macros/mm-common.m4.in)
  Provides MM_PREREQ() for requiring a minimum version of mm-common, and
  an internal initialization macro shared by the other mm-common macros.

macros/mm-warnings.m4:
  Implements the MM_ARG_ENABLE_WARNINGS() Autoconf macro for easy setup
  of compiler diagnostics through the --enable-warnings configure option.

macros/mm-doc.m4:
  Implements the MM_ARG_ENABLE_DOCUMENTATION() Autoconf macro to intialize
  the documentation support for a C++ binding package.  Among other things,
  it provides the --enable-documentation configure option, and checks for
  the required utilities.
  The other Autoconf macro defined here is MM_ARG_WITH_TAGFILE_DOC(), which
  ties all the ends together in order to make cross-referencing to external
  documentation work.  This macro should be called once for each external
  Doxygen tag file a binding package depends on.  It implements a configure
  option to override tag file locations, attempts automatic configuration
  if possible, and takes care of building the list of tag files and their
  default base paths for substitution into the configuration Doxyfile.  It
  also generates the command line options for doc-install.pl.

macros/mm-module.m4:
  The magic MM_INIT_MODULE() macro takes care of defining the various
  substitution variables and preprocessor macros to identify the name,
  version and API version of a C++ binding module.

macros/mm-pkg.m4:
  The helper macro MM_PKG_CONFIG_SUBST, which simplifies the retrieval of
  specific configuration values from pkg-config.  Checks for particular
  utility programs are also defined here, such as MM_CHECK_GNU_MAKE and
  MM_CHECK_PERL.

macros/mm-dietlib.m4:
  Implements Autoconf macros which provide options intended to reduce the
  binary size of the generated binding library, typically for embedded use.
  The MM_PROG_GCC_VISIBILITY macro is defined in this file as well.

Automake include files
----------------------

The Automake include files are located in the build/ directory.  The
installed mm-common-prepare program copies all of the .am files into
a project's source tree.  If AC_CONFIG_AUX_DIR([...]) is specified in
the configure.ac file, the .am files will be placed in the indicated
subdirectory.

build/generate-binding.am:
  Variables and rules for running the gmmproc code generate to produce
  the source code files for a C++ binding module.

build/compile-binding.am:
  Variables and rules for compiling and linking the shared library which
  implements a C++ binding module.

build/doc-reference.am:
  Variables and rules for building the API reference documentation using
  Doxygen, and to create a Devhelp book for the library.  The installation
  rules also take care of translating references to external documentation
  in the generated hypertext documents.

build/dist-changelog.am:
  A dist-hook rule to automatically generate a ChangeLog file when making
  a release, intended to be used by modules which use the version control
  log exclusively to document changes.

Documentation utilities
-----------------------

These are two Perl scripts, a style sheet, and one XSL transformation
which assist with the task of generating and installing the Doxygen
reference documentation.  At least doc-install.pl is also required for
tarball builds.
To avoid copying these files into all binding modules, they are also
distributed and installed with the glibmm module.  Those binding modules
which cannot depend on glibmm must call MM_CONFIG_DOCTOOL_DIR([...]) in
configure.ac to indicate to mm-common-prepare that it should copy the
documentation utilities into the project's source tree.  Otherwise the
files installed with glibmm will be used automatically.

util/doc-postprocess.pl:
  A simple script to post-process the HTML files generated by Doxygen.
  It replaces various code constructs that do not match the coding style
  used throughout the C++ bindings.  For instance, it rewrites function
  prototypes in order to place the reference symbol (&) next to the type
  instead of the name of the argument.

util/doc-install.pl:
  A replacement for the installdox script generated by Doxygen.  Its
  purpose is to translate references to external documentation at the
  time the documentation is installed.  This step is necessary because
  the documentation is included in the tarballs, and the location of
  external documentation on the installation system is not known at the
  time the documentation is generated.
  Apart from replacing the functionality of installdox, doc-install.pl
  also acts as a drop-in replacement for the classic BSD install command
  for easy integration with Automake.  It also translates Devhelp books
  as well, and will happily pass through unrecognized files without any
  alterations.

util/doxygen.css:
  A Cascading Style Sheet to unify the appearance of the HTML reference
  documentation generated by Doxygen for each C++ binding module.

util/tagfile-to-devhelp2.xsl:
  An XSLT script to generate a Devhelp2 book for the Doxygen reference
  documentation.  The generated Doxygen tag file serves as the input of
  the translation.

GNU C++ Library tag file
------------------------

All modules in the GNOME C++ bindings set make use of the C++ standard
library in the API.  As the GNU C++ Library shipped with GCC also uses
Doxygen for its reference documentation, its tag file is made available
by mm-common at a shared location for use by all C++ binding modules.

doctags/libstdc++.tag:
  The Doxygen tag file for the GNU libstdc++ reference documentation
  hosted at <http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/>.
  This file is distributed with release archives of mm-common, but not
  checked into version control on gnome.org.  If mm-common is built in
  maintainer-mode, the file will be downloaded automatically from the
  gcc.gnu.org web server.
  The file libstdc++.tag is installed into the package data directory
  of mm-common.  The mm-common-libstdc++ pkg-config module defines the
  variables ${doxytagfile} and ${htmlrefpub}, which can be queried for
  the location of the tag file and the URL of the online documentation.