NAME
    ocaml.m4 - Autoconf macros for OCaml

SUMMARY
     AC_PROG_OCAML
     AC_PROG_FINDLIB
     AC_PROG_OCAMLLEX
     AC_PROG_OCAMLYACC
     AC_PROG_CAMLP4
     AC_CHECK_OCAML_PKG([name])
     AC_CHECK_OCAML_MODULE(VARIABLE,NAME,MODULE,INCLUDE-PATHS)
     AC_CHECK_OCAML_WORD_SIZE

DESCRIPTION
    ocaml.m4 is a file containing standard, useful autoconf macros for
    detecting the OCaml, findlib, OCaml packages, and so on in your
    autoconf-generated ./configure scripts.

    To begin using these macros, you will need to copy the "ocaml.m4" file
    (usually located at "/usr/share/aclocal/ocaml.m4") to the autoconf
    macros directory in your project. Normally this is the "m4/" directory
    in your project, but the directory can be changed using the
    "AC_CONFIG_MACRO_DIR(DIR)" directive. If you have just created the "m4/"
    directory, then you may also need to do:

     aclocal -I m4

    You can then add any of the macros described below to your
    "configure.ac" (or "configure.in"). Almost every OCaml project should
    use "AC_PROG_OCAML" first and probably "AC_PROG_FINDLIB" right after it.

    This manual page does not describe how to use autoconf. For that you
    should read the detailed autoconf info file ("info autoconf").

AC_PROG_OCAML
    This macro detects which tools of the usual OCaml toolchain are
    available. It defines and substitutes the following variables:

     OCAMLC          set to the name of the bytecode compiler
                       (eg. "ocamlc" or "ocamlc.opt"), or "no" if
                       no OCaml installation was found
     OCAMLOPT        the name of the native-code compiler, eg. "ocamlopt",
                       "ocamlopt.opt" or "no"
     OCAMLBEST       "byte" (if only the bytecode compiler is available)
                       or "opt" (if both bytecode and native code compilers
                       are available)
     OCAMLDEP        the name of the dependency resolver, eg. "ocamldep"
     OCAMLMKTOP      the name of ocamlmktop
     OCAMLMKLIB      the name of ocamlmklib
     OCAMLDOC        the name of ocamldoc
     OCAMLBUILD      the name of ocamlbuild
     OCAMLLIB        the OCaml library path (eg. C</usr/lib/ocaml/>)
     OCAMLVERSION    the compiler version (eg. C<3.11.0>)

  Detecting if OCaml is installed
    Unlike old versions of these macros, "AC_PROG_OCAML" does *not* exit if
    no OCaml installation is detected. Therefore if you want to detect if
    OCaml is installed you have to do something like this:

     AC_PROG_OCAML
     if test "$OCAMLC" = "no"; then
       AC_MSG_ERROR([You must install the OCaml compiler])
     fi

    This behaviour and usage pattern are consistent with other macros of the
    "AC_PROG_*") family.

  Cross-compiling
    If the configure script is invoked for cross-compiling then
    "AC_PROG_OCAML" will detect the cross-compiler versions of the OCaml
    compiler, eg. "OCAMLC=i686-pc-mingw32-ocamlc" etc. This happens
    automatically, and for most purposes you don't need to worry about it.

AC_PROG_FINDLIB
    This macro checks for the presence of the ocamlfind program (part of
    findlib). It defines and substitutes "OCAMLFIND" to the name of the
    ocamlfind program, or "no" if not found.

    Note that this macro does not fail if ocamlfind is not found. If you
    want to force the user to install findlib, you should do:

     AC_PROG_FINDLIB
     if test "$OCAMLFIND" = "no"; then
       AC_MSG_ERROR([You must install OCaml findlib (the ocamlfind command)])
     fi

    See also "AC_CHECK_OCAML_PKG".

AC_PROG_OCAMLLEX
    This checks for the ocamllex program and sets "OCAMLLEX" to the name of
    the program (eg. "ocamllex" or "ocamllex.opt"), or "no" if not found.

AC_PROG_OCAMLYACC
    This checks for the ocamlyacc program and sets "OCAMLYACC" to the name
    of the program, or "no" if not found.

AC_PROG_CAMLP4
    This checks for camlp4, and checks that the version matches the compiler
    version found previously. It sets "CAMLP4" to the name of the basic
    camlp4 program, or "no" if not found.

    The macro also checks for other tools of the camlp4 suite like camlp4o,
    camlp4orf, etc. For each of them, a fully capitalized variable is set to
    the tool name (or "no" if not found); all variable are substituted for
    when filling .in files. The full list of tools and respective variable
    names is as follows:

     camlp4        CAMLP4
     camlp4boot    CAMLP4BOOT
     camlp4o       CAMLP4O
     camlp4of      CAMLP4OF
     camlp4oof     CAMLP4OOF
     camlp4orf     CAMLP4ORF
     camlp4prof    CAMLP4PROF
     camlp4r       CAMLP4R
     camlp4rf      CAMLP4RF

AC_CHECK_OCAML_PKG
    This is the main macro that can be used to detect the presence of OCaml
    findlib packages. This macro uses ocamlfind to look up findlib packages
    (and thus requires that findlib itself has been installed, and that the
    package has been properly packaged with a META file etc.) If you want to
    find an OCaml findlib package which hasn't been installed with findlib
    then you should try using "AC_CHECK_OCAML_MODULE" instead.

     AC_CHECK_OCAML_PKG([name])

    checks for an OCaml findlib package with the given name. If found, it
    defines and substitutes the variable "OCAML_PKG_name" where the "name"
    part is substituted for the package name by replacing all dashes with
    underscores.

    For example,

     AC_CHECK_OCAML_PKG([xml-light])

    will set "OCAML_PKG_xml_light" to either "xml-light" or "no".

    To have the configure script fail if a package is not installed, do:

     AC_CHECK_OCAML_PKG([foo])
     if test "$OCAML_PKG_foo" = "no"; then
       AC_MSG_ERROR([Please install OCaml findlib module 'foo'.])
     fi

    In your Makefile.in, use the substitution variable in conjunction with
    ocamlfind, eg:

     .ml.cmo:
       $(OCAMLFIND) ocamlc -package @OCAML_PKG_foo@ -c $< -o $@

    Note that also in the substitution variable dashes are replaced with
    underscores.

  Checking for alternative findlib package names
    In the (unlikely) case where the same library corresponds to different
    findlib package names on different systems, you can improve portability
    by checking for the alternative names passing a second argument to
    "AC_CHECK_OCAML_PKG":

     AC_CHECK_OCAML_PKG(PKGNAME,ALTERNATIVE-NAMES)

    The behaviour is the same as before if "PKGNAME" is found. Otherwise all
    names in "ALTERNATIVE-NAMES" are tested in turn as findlib package
    names. If one is found, it is set as the value set by the macro and
    substituted in .in files; otherwise "no" is set.

    Note that the variable name is determined by "PKGNAME", while the value
    depends on the actual alternative name found.

    For example, to detect the camlzip findlib package, either called "zip"
    or "camlzip", and to store the found value in the "OCAML_PKG_zip"
    variable you can do in your configure.ac:

     AC_CHECK_OCAML_PKG(zip,camlzip)

    and have a portable Makefile.in build line such as:

     .ml.cmo:
       $(OCAMLFIND) ocamlc -package @OCAML_PKG_zip@ -c $< -o $@

AC_CHECK_OCAML_MODULE(VARIABLE,NAME,MODULE,INCLUDE-PATHS)
    "AC_CHECK_OCAML_MODULE" is the hairier alternative to
    "AC_CHECK_OCAML_PKG". You should always use "AC_CHECK_OCAML_PKG" and
    ocamlfind/findlib if possible.

    The parameters are:

    VARIABLE
        This is the environment variable that is set. It will either be set
        to the include path, or to "no" if the module was not found.

    NAME
        This is the name of the module we are looking for. This parameter is
        just used for printing messages, and does not affect how the module
        is found.

    MODULE
        This should be an OCaml module name, representing the module name
        being looked up. You can put sub-modules here, eg.
        "CalendarLib.Date"

    INCLUDE-PATHS
        This is the default list of include directories to search, eg.
        "+calendar"

    For example, the following code will check for the OCaml Calendar
    module, and will distinguish between version 1 and version 2 of this
    module (which have incompatible APIs).

     AC_CHECK_OCAML_PKG(calendar)
     AC_CHECK_OCAML_MODULE(is_calendar2,calendar,[CalendarLib.Date],[+calendar])

    After the above code has run, variables "OCAML_PKG_calendar" and
    "is_calendar2" will be set as follows:

     OCAML_PKG_calendar  is_calendar2  Result
 
     yes                 +calendar     Calendar v2 is installed
     yes                 no            Calendar v1 is installed
     no                  no            No Calendar module installed

AC_CHECK_OCAML_WORD_SIZE
    This checks the word size of the OCaml compiler, and sets
    "OCAML_WORD_SIZE" to either 32 or 64.

SEE ALSO
    autoconf(1), <http://ocaml-autoconf.forge.ocamlcore.org>,
    <http://caml.inria.fr/>

FILES
    *   /usr/share/aclocal/ocaml.m4

AUTHORS
    Various people have contributed to these macros over many years:

    *   Olivier Andrieu

    *   Jean-Christophe Filliâtre

    *   Richard W.M. Jones

    *   Georges Mariano

    *   Jim Meyering

    *   Stefano Zacchiroli

LICENSE
     Copyright © 2009      Richard W.M. Jones
     Copyright © 2009      Stefano Zacchiroli
     Copyright © 2000-2005 Olivier Andrieu
     Copyright © 2000-2005 Jean-Christophe Filliâtre
     Copyright © 2000-2005 Georges Mariano
 
     All rights reserved.
 
     Redistribution and use in source and binary forms, with or without modification,
     are permitted provided that the following conditions are met:
 
     * Redistributions of source code must retain the above copyright notice, this
     list of conditions and the following disclaimer.
     * Redistributions in binary form must reproduce the above copyright notice,
     this list of conditions and the following disclaimer in the documentation
     and/or other materials provided with the distribution.
     * The names of the contributors may not be used to endorse or promote
     products derived from this software without specific prior written
     permission.
 
     THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ''AS IS'' AND ANY
     EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY
     DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
     LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
     ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

REPORTING BUGS
    Please report bugs to the authors at the project page:
    <http://forge.ocamlcore.org/projects/ocaml-autoconf/>, using the forge
    bug tracker <http://forge.ocamlcore.org/tracker/?group_id=69>.

