ocamlbuild

ocamlbuild [options] [targets]
ocamlbuild -clean

-clean
    Removes all generated files and temporary directories created by ocamlbuild.

-r, -rebuild
    Forces a complete rebuild of all targets from scratch, ignoring existing compiled files.

-use-ocamlfind
    Enables integration with the ocamlfind tool for managing and locating OCaml libraries.

-package <pkg>
    Adds an ocamlfind package (e.g., 'core', 'lwt') to the list of required packages for the build.

-plugin-tag <tag>
    Loads a specific ocamlbuild plugin by its tag, extending its functionality.

-show-tags
    Displays the list of tags currently recognized and applied by ocamlbuild in the configuration.

-ocamlc <path>
    Specifies the path to the ocamlc (OCaml bytecode compiler) executable to be used.

-ocamlopt <path>
    Specifies the path to the ocamlopt (OCaml native code compiler) executable to be used.

-where
    Prints the installation path of the ocamlbuild tool itself.

-quiet
    Suppresses most of the verbose output during the build process, showing only errors.

-no-progress
    Disables the display of real-time compilation progress indicators.

-classic-display
    Uses a simpler, non-interactive output format instead of the enhanced progress display.

-no-auto-clean
    Prevents ocamlbuild from automatically cleaning intermediate files before building.

-version
    Prints the version information of the ocamlbuild command.

-help
    Displays a help message detailing command line options and usage.

ocamlbuild is a powerful and flexible build system specifically designed for OCaml projects. It automates the compilation and linking process by automatically inferring dependencies between source files and managing the invocation of ocamlc, ocamlopt, and other tools. Unlike traditional build tools like make, ocamlbuild uses a declarative, rule-based approach, where users specify build goals (targets) and ocamlbuild determines the necessary steps to achieve them.

It supports common OCaml features such as bytecode compilation, native code compilation, .cmi and .cmx files, and integration with ocamlfind for library management. Its extensibility through plugins allows users to define custom build rules and integrate with external tools or specific project structures. It handles cleaning intermediate files and rebuilding only what's necessary, improving build times. While widely used, especially in older OCaml projects, newer alternatives like Dune have become more prevalent.

While powerful, ocamlbuild can have a significant learning curve due to its reliance on a tag-based system and specific directory structures. Configuring it for complex projects, especially those involving C-bindings or unusual dependencies, might require deep understanding. It has largely been superseded by dune for new OCaml projects, which offers a simpler, more opinionated, and faster build experience. As such, ocamlbuild is more commonly encountered in older or legacy OCaml codebases.

ocamlbuild employs a sophisticated tag system to control the build process. Tags are keywords (e.g., native, thread, debug) that can be associated with files, directories, or build targets. These tags influence which compilation flags are used, which libraries are linked, and which build rules apply. For instance, tagging a file with native will ensure it's compiled to native code, while thread indicates the need for thread-related libraries.

Customization and configuration in ocamlbuild projects are often managed through a file named _tags in the project directory. This plain text file allows users to declaratively specify rules for associating tags with file patterns or directories. For example, one might write '<src/*>: pkg_unix' to apply the pkg_unix tag to all files in the src directory, thereby linking the Unix library to them. This provides a flexible way to tailor the build without modifying ocamlbuild's core logic.

ocamlbuild was introduced as a standard component of the OCaml distribution starting with OCaml 3.10 (circa 2007-2008). Its aim was to provide a more automated and robust build system for OCaml projects, moving beyond simple Makefiles by automatically inferring dependencies and supporting common OCaml build patterns. For a period, it became the de-facto standard build tool for OCaml. However, with the emergence of dune (originally jbuilder) around the mid-2010s, which offered a simplified project setup, improved performance, and a more user-friendly experience, ocamlbuild's role has diminished in new project development, though it remains maintained and is still active in many established projects.

ocamlc(1), ocamlopt(1), ocamlfind(1), dune(1), make(1)