lib/ocaml/README-OCamlMakefile

NOTE (bryanduxbury): OCamlMakefile is safe to include in the project after
https://issues.apache.org/jira/browse/LEGAL-58.

---------------------------------------------------------------------------

                        Distribution of "ocaml_make"
     Copyright (C) 1999 - 2006  Markus Mottl - free to copy and modify!
                           USE AT YOUR OWN RISK!

---------------------------------------------------------------------------

                            PREREQUISITES

             *** YOU WILL NEED GNU-MAKE VERSION >3.80 ***

---------------------------------------------------------------------------

                    Contents of this distribution

Changes        - guess what? ;-)

OCamlMakefile  - Makefile for easy handling of compilation of not so easy
                 OCaml-projects.  It generates dependencies of OCaml-files
                 automatically, is able to handle "ocamllex"-,
                 "ocamlyacc"-, IDL- and C-files, knows how to run
                 preprocessors and generates native- or byte-code, as
                 executable or as library - with thread-support if you
                 want! Profiling and debugging support can be added on
                 the fly!  There is also support for installing libraries.
                 Ah, yes, and you can also create toplevels from any
                 sources: this allows you immediate interactive testing.
                 Automatic generation of documentation is easy due to
                 integration of support for OCamldoc.

README         - this file

calc/          - Directory containing a quite fully-featured example
                 of what "OCamlMakefile" can do for you. This example
                 makes use of "ocamllex", "ocamlyacc", IDL + C and
                 threads.

camlp4/        - This simple example demonstrates how to automatically
                 preprocess files with the camlp4-preprocessor.

gtk/           - Demonstration of how to use OCamlMakefile with GTK
                 and threads. Courtesy of Tim Freeman <tim@fungible.com>.

idl/           - Contains a very small example of how to use
                 "camlidl" together with "OCamlMakefile". Also intended
                 to show, how easy it is to interface OCaml and C.

threads/       - Two examples of how to use threads (originally
                 posted by Xavier Leroy some time ago). Shows the use of
                 "OCamlMakefile" in an environment of multiple compilation
                 targets.

---------------------------------------------------------------------------

                      Why should you use it?

For several reasons:

  * It is well-tested (I use it in all of my projects).

  * In contrast to most other approaches it generates dependencies
    correctly by ensuring that all automatically generated OCaml-files
    exist before dependency calculation.  This is the only way to
    guarantee that "ocamldep" works correctly.

  * It is extremely convenient (at least I think so ;-).
    Even quite complex compilation processes (see example "calc.ml")
    need very little information to work correctly - actually just about
    the minimum (file names of sources).

---------------------------------------------------------------------------

                     When you shouldn't use it...

In projects where every compilation unit needs different flags - but
in such complicated cases you will be on your own anyway. Luckily,
this doesn't happen too frequently...

---------------------------------------------------------------------------

             How to use "OCamlMakefile" in your own project
         (Take a look at the examples for a quick introduction!)

Create your project-specific "Makefile" in the appropriate directory.

Now there are two ways of making use of "OCamlMakefile":

  1) Have a look at the default settings in "OCamlMakefile" and set
     them to the values that are vaild on your system - whether the
     path to the standard libraries is ok, what executables shall be
     used, etc...

  2) Copy it into the directory of the project to be compiled.
     Add "-include OCamlMakefile" as a last line of your "Makefile".

  3) Put it somewhere else on the system. In this case you will have to
     set a variable "OCAMLMAKEFILE" in your project-specific "Makefile".
     This is the way in which the examples are written: so you need
     only one version of "OCamlMakefile" to manage all your projects!
     See the examples for details.

You should usually specify two further variables for your project:

  * SOURCES  (default: foo.ml)
  * RESULT   (default: foo)

Put all the sources necessary for a target into variable "SOURCES".
Then set "RESULT" to the name of the target. If you want to generate
libraries, you should *not* specify the suffix (".cma", ".cmxa", ".a")
- it will be added automatically if you specify that you want to build
a library.

      **      Don't forget to add the ".mli"-files, too!        **
      **  Don't forget that order of the source files matters!  **

The order is important, because it matters during linking anyway
due to potential side effects caused at program startup. This is
why OCamlMakefile does not attempt to partially order dependencies by
itself, which might confuse users even more. It just compiles and links
OCaml-sources in the order specified by the user, even if it could
determine automatically that the order cannot be correct.

The minimum of your "Makefile" looks like this (assuming that
"OCamlMakefile" is in the search path of "make"):

  -include OCamlMakefile

This will assume that you want to compile a file "foo.ml" to a binary
"foo".

Otherwise, your Makefile will probably contain something like this:

  SOURCES = foo.ml
  RESULT  = foo
  -include OCamlMakefile

Be careful with the names you put into these variables: if they are wrong,
a "make clean" might erase the wrong files - but I know you will not do
that ;-)

A simple "make" will generate a byte-code executable. If you want to
change this, you may add an "all"-rule that generates something else.

E.g.:

  SOURCES = foo.ml
  RESULT  = foo
  all: native-code-library
  -include OCamlMakefile

This will build a native-code library "foo.cmxa" (+ "foo.a") from file
"foo.ml".

You may even build several targets at once. To produce byte- and native-code
executables with one "make", add the following rule:

    all: byte-code native-code

You will probably want to use a different suffix for each of these targets
so that the result will not be overwritten (see optional variables below
for details).

You may also tell "make" at the command-line what kind of target to
produce (e.g. "make nc").  Here all the possibilities with shortcuts
between parenthesis:

   * byte-code                     (bc)
   * byte-code-nolink              (bcnl)   - no linking stage
   * byte-code-library             (bcl)
   * native-code                   (nc)
   * native-code-nolink            (ncnl)   - no linking stage
   * native-code-library           (ncl)
   * debug-code                    (dc)
   * debug-code-nolink             (dcnl)   - no linking stage
   * debug-code-library            (dcl)
   * profiling-byte-code           (pbc)
   * profiling-byte-code-library   (pbcl)
   * profiling-native-code         (pnc)
   * profiling-native-code-library (pncl)
   * byte-code-dll                 (bcd)
   * native-code-dll               (ncd)
   * pack-byte-code                (pabc)
   * pack-native-code              (panc)
   * toplevel interpreter          (top)
   * subprojs

Here a short note concerning building and linking byte code libraries
with C-files:

  OCaml links C-object files only when they are used in an executable.
  After compilation they should be placed in some directory that is in
  your include path if you link your library against an executable.

  It is sometimes more convenient to link all C-object files into a
  single C-library. Then you have to override the automatic link flags
  of your library using "-noautolink" and add another linkflag that
  links in your C-library explicitly.

What concerns maintainance:

  "make clean" removes all (all!) automatically generated files - so
  again: make sure your variables are ok!

  "make cleanup" is similar to "make clean" but leaves executables.

Another way to destroy some important files is by having "OCamlMakefile"
automatically generate files with the same name. Read the documentation
about the tools in the OCaml-distribution to see what kind of files are
generated. "OCamlMakefile" additionally generates ('%' is basename of
source file):

  %_idl.c  - "camlidl" generates a file "%.c" from "%.idl", but this is
             not such a good idea, because when generating native-code,
             both the file "%.c" and "%.ml" would generate files "%.o"
             which would overwrite each other. Thus, "OCamlMakefile"
             renames "%.c" to "%_idl.c" to work around this problem.

The dependencies are stored in three different subdirectories (dot dirs):

  ._d    - contains dependencies for .ml-files
  ._bcdi - contains byte code dependencies for .mli-files
  ._ncdi - contains native code dependencies for .mli-files

The endings of the dependency files are: "%.d" for those generated from
"%.ml"-files, "%.di" for ones derived from "%.mli"-files.

---------------------------------------------------------------------------

                                 Debugging

  This is easy: if you discover a bug, just do a "make clean; make dc"
  to recompile your project with debugging information. Then you can
  immediately apply "ocamldebug" to the executable.

---------------------------------------------------------------------------

                                 Profiling

  For generating code that can be profiled with "ocamlprof" (byte code)
  or "gprof" (native code), compile your project with one of the profiling
  targets (see targets above). E.g.:

    * "make pbc" will build byte code that can be profiled with
      "ocamlprof".

    * "make pnc" will build native code that can be profiled with
      "gprof".

  Please note that it is not currently possible to profile byte code with
  threads. OCamlMakefile will force an error if you try to do this.

  A short hint for DEC Alpha-users (under Digital Unix): you may also
  compile your sources to native code without any further profiling
  options/targets. Then call "pixie my_exec", "my_exec" being your
  executable. This will produce (among other files) an executable
  "my_exec.pixie". Call it and it will produce profiling information which
  can be analysed using "prof -pixie my_exec". The resulting information
  is extremely detailed and allows analysis up to the clock cycle level...

---------------------------------------------------------------------------

                             Using Preprocessors

  Because one could employ any kind of program that reads from standard
  input and prints to standard output as preprocessor, there cannot be any
  default way to handle all of them correctly without further knowledge.

  Therefore you have to cooperate a bit with OCamlMakefile to let
  preprocessing happen automatically. Basically, this only requires
  that you put a comment into the first line of files that should be
  preprocessed, e.g.:

    (*pp cat *)
    ... rest of program ...

  OCamlMakefile looks at the first line of your files, and if it finds
  a comment that starts with "(*pp", then it will assume that the
  rest of the comment tells it how to correctly call the appropriate
  preprocessor. In this case the program "cat" will be called, which will,
  of course, just output the source text again without changing it.

  If you are, for example, an advocate of the new "revised syntax",
  which is supported by the camlp4 preprocessor, you could simply write:

    (*pp camlp4r *)
    ... rest of program in revised syntax ...

  Simple, isn't it?

  If you want to write your own syntax extensions, just take a look at the
  example in the directory "camlp4": it implements the "repeat ... until"
  extension as described in the camlp4-tutorial.

---------------------------------------------------------------------------

                     Library (Un-)Installation Support

  OCamlMakefile contains two targets using "ocamlfind" for this purpose:

    * libinstall
    * libuninstall

  These two targets require the existence of the variable
  "LIBINSTALL_FILES", which should be set to all the files that you
  want to install in the library directory (usually %.mli, %.cmi, %.cma,
  %.cmxa, %.a and possibly further C-libraries). The target "libinstall"
  has the dependency "all" to force compilation of the library so make
  sure you define target "all" in your Makefile appropriately.

  The targets inform the user about the configured install path and ask
  for confirmation to (un)install there. If you want to use them, it
  is often a good idea to just alias them in your Makefile to "install"
  and "uninstall" respectively.

  Two other targets allow installation of files into a particular
  directory (without using ocamlfind):

    * rawinstall
    * rawuninstall

---------------------------------------------------------------------------

                            Building toplevels

  There is just one target for this:

    * top

  The generated file can be used immediately for interactive sessions -
  even with scanners, parsers, C-files, etc.!

---------------------------------------------------------------------------

                         Generating documentation

  The following targets are supported:

   * htdoc      - generates HTML-documentation
   * ladoc      - generates Latex-documentation
   * psdoc      - generates PostScript-documentation
   * pdfdoc     - generates PDF-documentation
   * doc        - generates all supported forms of documentation
   * clean-doc  - generates all supported forms of documentation

  All of them generate a sub-directory "doc". More precisely, for HTML it
  is "doc/$(RESULT)/html" and for Latex, PostScript and PDF the directory
  "doc/$(RESULT)/latex". See the OCamldoc-manual for details and the
  optional variables below for settings you can control.

---------------------------------------------------------------------------

                           Handling subprojects

  You can have several targets in the same directory and manage them
  from within an single Makefile.

  Give each subproject a name, e.g. "p1", "p2", etc. Then you export
  settings specific to each project by using variables of the form
  "PROJ_p1", "PROJ_p2", etc.  E.g.:

    define PROJ_p1
      SOURCES="foo.ml main.ml"
      RESULT="p1"
      OCAMLFLAGS="-unsafe"
    endef
    export PROJ_p1

    define PROJ_p2
      ...
    endef
    export PROJ_p2

  You may also export common settings used by all projects directly, e.g.
  "export THREADS = y".

  Now it is a good idea to define, which projects should be affected by
  commands by default.  E.g.:

    ifndef SUBPROJS
      export SUBPROJS = p1 p2
    endif

  This will automatically generate a given target for all those
  subprojects if this variable has not been defined in the shell
  environment or in the command line of the make-invocation by the user.
  E.g., "make dc" will generate debug code for all subprojects.

  Then you need to define a default action for your subprojects if "make"
  has been called without arguments:

    all: bc

  This will build byte code by default for all subprojects.

  Finally, you'll have to define a catch-all target that uses the target
  provided by the user for all subprojects. Just add (assuming that
  OCAMLMAKEFILE has been defined appropriately):

    %:
            @make -f $(OCAMLMAKEFILE) subprojs SUBTARGET=$@

  See the "threads"-directory in the distribution for a short example!

---------------------------------------------------------------------------

         Optional variables that may be passed to "OCamlMakefile"

  * LIB_PACK_NAME - packs all modules of a library into a module whose
                    name is given in variable "LIB_PACK_NAME".

  * RES_CLIB_SUF  - when building a library that contains C-stubs, this
                    variable controls the suffix appended to the name
                    of the C-library (default: "_stubs").

  * THREADS       - say "THREADS = yes" if you need thread support compiled in,
                    otherwise leave it away.

  * VMTHREADS     - say "VMTHREADS = yes" if you want to force VM-level
                    scheduling of threads (byte-code only).

  * ANNOTATE      - say "ANNOTATE = yes" to generate type annotation files
                    (.annot) to support displaying of type information
                    in editors.

  * USE_CAMLP4    - say "USE_CAMLP4 = yes" in your "Makefile" if you
                    want to include the camlp4 directory during the
                    build process, otherwise leave it away.

  * INCDIRS       - directories that should be searched for ".cmi"- and
                    ".cmo"-files.  You need not write "-I ..." - just the
                    plain names.
  * LIBDIRS       - directories that should be searched for libraries
                    Also just put the plain paths into this variable
  * EXTLIBDIRS    - Same as "LIBDIRS", but paths in this variable are
                    also added to the binary via the "-R"-flag so that
                    dynamic libraries in non-standard places can be found.
  * RESULTDEPS    - Targets on which results (executables or libraries)
                    should additionally depend.

  * PACKS         - adds packages under control of "findlib".

  * PREDS         - specifies "findlib"-predicates.

  * LIBS          - OCaml-libraries that should be linked (just plain names).
                    E.g. if you want to link the Str-library, just write
                    "str" (without quotes).
                    The new OCaml-compiler handles libraries in such
                    a way that they "remember" whether they have to
                    be linked against a C-library and it gets linked
                    in automatically.
                    If there is a slash in the library name (such as
                    "./str" or "lib/foo") then make is told that the
                    generated files depend on the library.  This
                    helps to ensure that changes to your libraries are
                    taken into account, which is important if you are
                    regenerating your libraries frequently.
  * CLIBS         - C-libraries that should be linked (just plain names).

  * PRE_TARGETS   - set this to a list of target files that you want
                    to have buildt before dependency calculation actually
                    takes place. E.g. use this to automatically compile
                    modules needed by camlp4, which have to be available
                    before other modules can be parsed at all.

                    ** WARNING **: the files mentioned in this variable
                    will be removed when "make clean" is executed!

  * LIBINSTALL_FILES - the files of a library that should be installed
                       using "findlib". Default:

                         $(RESULT).mli $(RESULT).cmi $(RESULT).cma
                         $(RESULT).cmxa $(RESULT).a lib$(RESULT).a

  * OCAML_LIB_INSTALL - target directory for "rawinstall/rawuninstall".
                        (default: $(OCAMLLIBPATH)/contrib)

  * DOC_FILES     - names of files from which documentation is generated.
                    (default: all .mli-files in your $(SOURCES)).

  * DOC_DIR       - name of directory where documentation should be stored.

  * OCAMLFLAGS    - flags passed to the compilers
  * OCAMLBCFLAGS  - flags passed to the byte code compiler only
  * OCAMLNCFLAGS  - flags passed to the native code compiler only

  * OCAMLLDFLAGS  - flags passed to the OCaml-linker
  * OCAMLBLDFLAGS - flags passed to the OCaml-linker when linking byte code
  * OCAMLNLDFLAGS - flags passed to the OCaml-linker when linking
                    native code

  * OCAMLMKLIB_FLAGS - flags passed to the OCaml library tool

  * OCAMLCPFLAGS  - profiling flags passed to "ocamlcp" (default: "a")

  * PPFLAGS       - additional flags passed to the preprocessor (default: none)

  * LFLAGS        - flags passed to "ocamllex"
  * YFLAGS        - flags passed to "ocamlyacc"
  * IDLFLAGS      - flags passed to "camlidl"

  * OCAMLDOCFLAGS - flags passed to "ocamldoc"

  * OCAMLFIND_INSTFLAGS - flags passed to "ocamlfind" during installation
                          (default: none)

  * DVIPSFLAGS    - flags passed to dvips
                    (when generating documentation in PostScript).

  * STATIC        - set this variable if you want to force creation
                    of static libraries

  * CC            - the C-compiler to be used
  * CXX           - the C++-compiler to be used

  * CFLAGS        - additional flags passed to the C-compiler.
                    The flag "-DNATIVE_CODE" will be passed automatically
                    if you choose to build native code. This allows you
                    to compile your C-files conditionally. But please
                    note: You should do a "make clean" or remove the
                    object files manually or touch the %.c-files:
                    otherwise, they may not be correctly recompiled
                    between different builds.

  * CXXFLAGS      - additional flags passed to the C++-compiler.

  * CPPFLAGS      - additional flags passed to the C-preprocessor.

  * CFRAMEWORKS   - Objective-C framework to pass to linker on MacOS X.

  * LDFLAGS       - additional flags passed to the C-linker

  * RPATH_FLAG    - flag passed through to the C-linker to set a path for
                    dynamic libraries.  May need to be set by user on
                    exotic platforms.  (default: "-R").

  * ELF_RPATH_FLAG - this flag is used to set the rpath on ELF-platforms.
                     (default: "-R")

  * ELF_RPATH     - if this flag is "yes", then the RPATH_FLAG will be
                    passed by "-Wl" to the linker as normal on
                    ELF-platforms.

  * OCAMLLIBPATH  - path to the OCaml-standard-libraries
                    (first default: `$(OCAMLC) -where`)
                    (second default: "/usr/local/lib/ocaml")

  * OCAML_DEFAULT_DIRS - additional path in which the user can supply
                         default directories to his own collection of
                         libraries.  The idea is to pass this as an environment
                         variable so that the Makefiles do not have to contain
                         this path all the time.

  * OCAMLFIND     - ocamlfind from findlib       (default: "ocamlfind")
  * OCAMLC        - byte-code compiler           (default: "ocamlc")
  * OCAMLOPT      - native-code compiler         (default: "ocamlopt")
  * OCAMLMKTOP    - top-level compiler           (default: "ocamlmktop")
  * OCAMLCP       - profiling byte-code compiler (default: "ocamlcp")
  * OCAMLDEP      - dependency generator         (default: "ocamldep")
  * OCAMLLEX      - scanner generator            (default: "ocamllex")
  * OCAMLYACC     - parser generator             (default: "ocamlyacc")
  * OCAMLMKLIB    - tool to create libraries     (default: "ocamlmklib")
  * CAMLIDL       - IDL-code generator           (default: "camlidl")
  * CAMLIDLDLL    - IDL-utility                  (default: "camlidldll")
  * CAMLP4        - camlp4 preprocessor          (default: "camlp4")
  * OCAMLDOC      - OCamldoc-command             (default: "ocamldoc")

  * LATEX         - Latex-processor              (default: "latex")
  * DVIPS         - dvips-command                (default: "dvips")
  * PS2PDF        - PostScript-to-PDF converter  (default: "ps2pdf")

  * CAMELEON_REPORT - report tool of Cameleon  (default: "report")
  * CAMELEON_REPORT_FLAGS - flags for the report tool of Cameleon

  * CAMELEON_ZOGGY - zoggy tool of Cameleon
                     (default: "camlp4o pa_zog.cma pr_o.cmo")
  * CAMELEON_ZOGGY_FLAGS - flags for the zoggy tool of Cameleon

  * OCAML_GLADECC - Glade compiler for OCaml     (default: "lablgladecc2")
  * OCAML_GLADECC_FLAGS - flags for the Glade compiler

  * OXRIDL        - OXRIDL-generator  (default: "oxridl")

  * NOIDLHEADER   - set to "yes" to prohibit "OCamlMakefile" from using
                    the default camlidl-flag "-header".

  * NO_CUSTOM     - Prevent linking in custom mode.

  * QUIET         - unsetting this variable (e.g. "make QUIET=")
                    will print all executed commands, including
                    intermediate ones. This allows more comfortable
                    debugging when things go wrong during a build.

  * REALLY_QUIET  - when set this flag turns off output from some commands.

  * OCAMLMAKEFILE - location of (=path to) this "OCamlMakefile".
                    Because it calles itself recursively, it has to
                    know where it is. (default: "OCamlMakefile" =
                    local directory)

  * BCSUFFIX      - Suffix for all byte-code files. E.g.:

                      RESULT   = foo
                      BCSUFFIX = _bc

                    This will produce byte-code executables/libraries
                    with basename "foo_bc".

  * NCSUFFIX      - Similar to "BCSUFFIX", but for native-code files.
  * TOPSUFFIX     - Suffix added to toplevel interpreters (default: ".top")

  * SUBPROJS      - variable containing the names of subprojects to be
                    compiled.

  * SUBTARGET     - target to be built for all projects in variable
                    SUBPROJS.

---------------------------------------------------------------------------

                    Optional variables for Windows users

  * MINGW         - variable to detect the MINGW-environment
  * MSVC          - variable to detect the MSVC-compiler

---------------------------------------------------------------------------

Up-to-date information (newest release of distribution) can always be
found at:

  http://www.ocaml.info/home/ocaml_sources.html

---------------------------------------------------------------------------

Enjoy!

New York, 2007-04-22
Markus Mottl

e-mail: markus.mottl@gmail.com
WWW:    http://www.ocaml.info