Markus Mottl avatar Markus Mottl committed e0007c3

Improved README

Comments (0)

Files changed (1)

----------------------------------------------------------------------------
-
-                        Distribution of "ocaml_make"
-     Copyright (C) 1999 - 2006  Markus Mottl - free to copy and modify!
-                           USE AT YOUR OWN RISK!
+OCamlMakefile - A Simple Generic Makefile for OCaml-Projects
+============================================================
 
 ---------------------------------------------------------------------------
 
-                            PREREQUISITES
+Prerequisites
+-------------
 
-             *** YOU WILL NEED GNU-MAKE VERSION >3.80 ***
+  * GNU-Make version 3.80 or higher
 
----------------------------------------------------------------------------
+Pros
+----
 
-                    Contents of this distribution
+  * It is well-tested across multiple platforms and has been used in many
+    projects.
 
-Changes        - guess what? ;-)
+  * 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` can do its job.
 
-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.
+  * Convenience.  Even fairly complex compilation processes (see example
+    `calc.ml`) need only little information to work correctly, sometimes
+    just about the minimum (filenames of sources).
 
-README.txt     - this file
+Cons
+----
 
-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.
+  * It may not be a good choice in projects where many compilation units
+    require different flags.
 
-camlp4/        - This simple example demonstrates how to automatically
-                 preprocess files with the camlp4-preprocessor.
+  * Though it can scale to medium-sized projects, large projects with,
+    for example, dependencies across multiple libraries in different
+    directories are not well-supported.
 
-gtk/           - Demonstration of how to use OCamlMakefile with GTK
-                 and threads. Courtesy of Tim Freeman <tim@fungible.com>.
+    This is a general shortcoming of the already somewhat dated `make`.
+    You may want to investigate the following tools to approach larger
+    projects:
 
-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.
+      * [OMake](http://omake.metaprl.org/index.html)
+      * [ocamlbuild](http://brion.inria.fr/gallium/index.php/Ocamlbuild)
+      * [Oasis](http://oasis.forge.ocamlcore.org)
 
-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.
+Usage
+-----
 
----------------------------------------------------------------------------
+It is recommended that first-time users take a look at the examples in the
+distribution for a quick introduction.  `OCamlMakefile`-projects are often so
+simple that they are self-explanatory.
 
-                      Why should you use it?
+To create your own project, first edit a project-specific `Makefile` in the
+appropriate directory.  There are two ways of making use of `OCamlMakefile`:
 
-For several reasons:
+  1. Have a look at the default settings in `OCamlMakefile` and set
+     them to the values that are vaild on your system.   For example, check
+     whether the path to the standard libraries is ok, what executables shall
+     be used, etc.  Copy it into the directory of the project to be compiled.
+     Add the following statement as last line to your `Makefile`:
 
-  * It is well-tested (I use it in all of my projects).
+         :::makefile
+         -include OCamlMakefile
 
-  * 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!
+  2. Put `OCamlMakefile` somewhere else in your system.  In this case you
+     will have to set the variable `OCAMLMAKEFILE` in your project-specific
+     `Makefile`.  This is the way in which the examples are written.  Now you
+     only need one version of `OCamlMakefile` to manage all of your projects!
      See the examples for details.
 
-You should usually specify two further variables for your project:
+You will usually need to specify two further variables for your project:
 
-  * SOURCES  (default: foo.ml)
-  * RESULT   (default: foo)
+  * `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.
+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!  **
+    :::text
+    **      Don't forget to add the `.mli`-files, too!            **
+    **  Don't forget that the 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 order is important, because it matters during linking 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"):
+The minimum of your `Makefile` looks like this (assuming that `OCamlMakefile`
+is in the search path of `make`):
 
-  -include OCamlMakefile
+    :::makefile
+    -include OCamlMakefile
 
-This will assume that you want to compile a file "foo.ml" to a binary
-"foo".
+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
+    :::makefile
+    SOURCES = foo.ml
+    RESULT  = foo
 
-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 ;-)
+    -include OCamlMakefile
 
-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.
+Be careful with the names you put into these variables.  If they are wrong,
+a `make clean` might erase the wrong files!
 
-E.g.:
+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.  For example:
 
-  SOURCES = foo.ml
-  RESULT  = foo
-  all: native-code-library
-  -include OCamlMakefile
+    :::makefile
+    SOURCES = foo.ml
+    RESULT  = foo
 
-This will build a native-code library "foo.cmxa" (+ "foo.a") from file
-"foo.ml".
+    all: native-code-library
 
-You may even build several targets at once. To produce byte- and native-code
-executables with one "make", add the following rule:
+    -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:
+
+    :::makefile
     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).
+so that the result will not be overwritten.  See the 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:
+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
+    :::text
+    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                       (top)
+    subprojs
 
-Here a short note concerning building and linking byte code libraries
+Here is 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.
+> 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.
 
-  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.
+Concerning maintainance:
 
-What concerns maintainance:
+  * `make clean` removes all (all!) automatically generated files.
+    So again, make sure your variables are ok!
 
-  "make clean" removes all (all!) automatically generated files - so
-  again: make sure your variables are ok!
+  * `make cleanup` is similar to `make clean` but keeps executables.
 
-  "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 the basename of source file):
 
-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.
+  * `%_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
+  * `._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.
+The endings of the dependency files are: `%.d` for those generated from
+`%.ml`-files and `%.di` for ones derived from `%.mli`-files.
 
----------------------------------------------------------------------------
+### Debugging
 
-                                 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.
 
-  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
 
----------------------------------------------------------------------------
+To generate 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.:
 
-                                 Profiling
+  * `make pbc` will build byte code that can be profiled with `ocamlprof`.
+  * `make pnc` will build native code that can be profiled with `gprof`.
 
-  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.:
+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.
 
-    * "make pbc" will build byte code that can be profiled with
-      "ocamlprof".
+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...
 
-    * "make pnc" will build native code that can be profiled with
-      "gprof".
+### Using Preprocessors
 
-  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.
+Because any kind of program that reads from standard input and prints to
+standard output can be used as a preprocessor, there cannot be any default
+way to handle all of them correctly without further knowledge.
 
-  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...
+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.:
 
----------------------------------------------------------------------------
+    :::ocaml
+    (*pp cat *)
+    (* ... rest of program ... *)
 
-                             Using Preprocessors
+`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.
 
-  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.
+If, for example, you were an advocate of the "revised syntax", which is
+supported by the `camlp4` preprocessor, you could simply write:
 
-  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.:
+    :::ocaml
+    (*pp camlp4r *)
+    (* ... rest of program in revised syntax ... *)
 
-    (*pp cat *)
-    ... rest of program ...
+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.
 
-  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.
+### Library (Un-)Installation Support
 
-  If you are, for example, an advocate of the new "revised syntax",
-  which is supported by the camlp4 preprocessor, you could simply write:
+`OCamlMakefile` contains two targets using `ocamlfind` for this purpose:
 
-    (*pp camlp4r *)
-    ... rest of program in revised syntax ...
+  * `libinstall`
+  * `libuninstall`
 
-  Simple, isn't it?
+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.
 
-  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.
+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`):
 
-                     Library (Un-)Installation Support
+  * `rawinstall`
+  * `rawuninstall`
 
-  OCamlMakefile contains two targets using "ocamlfind" for this purpose:
+### Building toplevels
 
-    * libinstall
-    * libuninstall
+There is just one target for this:
 
-  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.
+  * `top`
 
-  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.
+The generated file can be used immediately for interactive sessions - even
+with scanners, parsers, C-files, etc.!
 
-  Two other targets allow installation of files into a particular
-  directory (without using ocamlfind):
+### Generating documentation
 
-    * rawinstall
-    * rawuninstall
+The following targets are supported:
 
----------------------------------------------------------------------------
+    :::text
+    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
 
-                            Building toplevels
+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.
 
-  There is just one target for this:
+### Handling subprojects
 
-    * top
+You can have several targets in the same directory and manage them from
+within an single `Makefile`.
 
-  The generated file can be used immediately for interactive sessions -
-  even with scanners, parsers, C-files, etc.!
+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.:
 
----------------------------------------------------------------------------
-
-                         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.:
-
+    :::makefile
     define PROJ_p1
       SOURCES="foo.ml main.ml"
       RESULT="p1"
     endef
     export PROJ_p2
 
-  You may also export common settings used by all projects directly, e.g.
-  "export THREADS = y".
+You may also export common settings used by all projects directly, e.g.:
 
-  Now it is a good idea to define, which projects should be affected by
-  commands by default.  E.g.:
+    :::makefile
+    export THREADS = y
 
+Now is a good time to define which projects should be affected by commands
+by default.  E.g.:
+
+    :::makefile
     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.
+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:
+Now you need to define a default action for your subprojects if `make`
+has been called without arguments:
 
+    :::makefile
     all: bc
 
-  This will build byte code by default for all subprojects.
+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):
+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=$@
+  %:
+          @make -f $(OCAMLMAKEFILE) subprojs SUBTARGET=$@
 
-  See the "threads"-directory in the distribution for a short example!
+See the `threads`-directory in the distribution for a short example!
+
+### Optional `OCamlMakefile` variables
+
+    :::text
+    * 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)
+    * OCAML         - OCaml interpreter            (default: ocaml)
+    * 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
+
+    :::text
+    * MINGW         - variable to detect the MINGW-environment
+    * MSVC          - variable to detect the MSVC-compiler
 
 ---------------------------------------------------------------------------
 
-         Optional variables that may be passed to "OCamlMakefile"
+Contact Information and Contributing
+------------------------------------
 
-  * LIB_PACK_NAME - packs all modules of a library into a module whose
-                    name is given in variable "LIB_PACK_NAME".
+In the case of bugs, feature requests, contributions and similar, you can
+contact me here: <markus.mottl@gmail.com>
 
-  * 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")
-  * OCAML         - OCaml interpreter            (default: "ocaml")
-  * 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
-
----------------------------------------------------------------------------
+Up-to-date information concerning this tool should be available at:
+<https://bitbucket.org/mmottl/ocaml-makefile>
 
 Enjoy!
 
-New York, 2011-03-23
-Markus Mottl
-
-e-mail: markus.mottl@gmail.com
-WWW:    http://www.ocaml.info
+Markus Mottl in Rutherford, NJ on July 10, 2012
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.