Module type Signatures.PLUGIN

module type PLUGIN = sig .. end

This module contains the functions and values that can be used by plugins.

module Pathname: Signatures.PATHNAME

module Tags: Signatures.TAGS

module Command: Signatures.COMMAND  with type tags = Tags.t and type pathname = Pathname.t

module Outcome: Signatures.OUTCOME

module String: Signatures.STRING

module List: Signatures.LIST

module StringSet: Set.S  with type elt = String.t

module Options: Signatures.OPTIONS  with type command_spec = Command.spec

module Arch: Signatures.ARCH

include Signatures.MISC

type command = Command.t =

`\|`	`Seq of command list`
`\|`	`Cmd of spec`
`\|`	`Echo of string list * Pathname.t`
`\|`	`Nop`

See COMMAND for the description of these types.

type spec = Command.spec =

`\|`	`N`
`\|`	`S of spec list`
`\|`	`A of string`
`\|`	`P of string`
`\|`	`Px of string`
`\|`	`Sh of string`
`\|`	`T of Tags.t`
`\|`	`V of string`
`\|`	`Quote of spec`

val (/) : Pathname.t -> Pathname.t -> Pathname.t

path1/path2 Join the given path names.

val (-.-) : Pathname.t -> string -> Pathname.t

path-.-extension Add the given extension to the given pathname.

val (++) : Tags.t -> Tags.elt -> Tags.t

tags++tag Add the given tag to the given set of tags.

val (--) : Tags.t -> Tags.elt -> Tags.t

tags--tag Remove the given tag to the given set of tags.

val (+++) : Tags.t -> Tags.elt option -> Tags.t

tags+++optional_tag Add the given optional tag to the given set of tags if the given option is Some.

val (---) : Tags.t -> Tags.elt option -> Tags.t

tags---optional_tag Remove the given optional tag to the given set of tags if the given option is Some.

type env = Pathname.t -> Pathname.t

The type of the builder environments. Here an environment is just the lookup function of it. Basically this function will resolve path variables like % or more generally %(var_name).

type builder = Pathname.t list list -> (Pathname.t, exn) Outcome.t list

A builder is a function that waits for conjonction of alternative targets. The alternatives are here to support some choices, for instance for an OCaml module an alternatives can be foo.cmo, foo.cmi, Foo.cmo, Foo.cmi. Conjonctions are here to help making parallelism, indeed commands that are independant will be run concurently.

type action = env ->
       builder -> Command.t

This is the type for rule actions. An action receive as argument, the environment lookup function (see env), and a function to dynamically build more targets (see builder). An action should return the command to run in order to build the rule productions using the rule dependencies.

val rule : string ->
       ?tags:string list ->
       ?prods:string list ->
       ?deps:string list ->
       ?prod:string ->
       ?dep:string ->
       ?stamp:string ->
       ?insert:[ `after of string | `before of string | `bottom | `top ] ->
       action -> unit

This is the main function for adding a rule to the ocamlbuild engine.

The first argument is the name of the rule (should be unique).
It takes files that the rule produces. Use ~prod for one file, ~prods for list of files.
It also takes files that the rule uses. Use ~dep for one file, ~deps for list of files.
It finally takes the action to perform in order to produce the productions files using the dependencies (see action). There is also two more options:
The ~insert argument allow to insert the rules precisely between other rules.
The ~stamp argument specify the name of a file that will be automatically produced by ocamlbuild. This file can serve as a virtual target (or phony target), since it will be filled up by a digest of it dependencies.
The ~tags argument in deprecated, don't use it.

val copy_rule : string ->
       ?insert:[ `after of string | `before of string | `bottom | `top ] ->
       string -> string -> unit

copy_rule name ?insert source destination

val dep : Tags.elt list -> Pathname.t list -> unit

dep tags deps Will build deps when all tags will be activated.

val flag : Tags.elt list -> Command.spec -> unit

flag tags command_spec Will inject the given piece of command (command_spec) when all tags will be activated.

val flag_and_dep : Tags.elt list -> Command.spec -> unit

flag_and_dep tags command_spec Combines flag and dep function. Basically it calls flag tags command_spec, and calls dep tags files where files is the list of all pathnames in command_spec. Pathnames selected are those in the constructor P or Px, or the pathname argument of builtins like Echo.

val non_dependency : Pathname.t -> string -> unit

non_dependency module_path module_name Example: non_dependency "foo/bar/baz" "Goo" Says that the module Baz in the file foo/bar/baz.* does not depend on Goo.

val use_lib : Pathname.t -> Pathname.t -> unit

use_lib module_path lib_path

val ocaml_lib : ?extern:bool ->
       ?byte:bool ->
       ?native:bool -> ?dir:Pathname.t -> ?tag_name:string -> Pathname.t -> unit

ocaml_lib <options> library_pathname Declare an ocaml library.

Example: ocaml_lib "foo/bar" This will setup the tag use_bar tag. At link time it will include: foo/bar.cma or foo/bar.cmxa If you supply the ~dir:"boo" option -I boo will be added at link and compile time. Use ~extern:true for non-ocamlbuild handled libraries. Use ~byte:false or ~native:false to disable byte or native mode. Use ~tag_name:"usebar" to override the default tag name.

val expand_module : Pathname.t list -> Pathname.t -> string list -> Pathname.t list

expand_module include_dirs module_name extensions Example:

expand_module ["a";"b";"c"] "Foo" ["cmo";"cmi"] =
         ["a/foo.cmo"; "a/Foo.cmo"; "a/foo.cmi"; "a/Foo.cmi";
          "b/foo.cmo"; "b/Foo.cmo"; "b/foo.cmi"; "b/Foo.cmi";
          "c/foo.cmo"; "c/Foo.cmo"; "c/foo.cmi"; "c/Foo.cmi"]

val string_list_of_file : Pathname.t -> string list

Reads the given file, parse it has list of words separated by blanks. It ignore lines that begins with a '#' character.

val module_name_of_pathname : Pathname.t -> string

Takes a pathname and returns an OCaml module name. Basically it will remove directories and extensions, and then capitalize the string.

val mv : Pathname.t -> Pathname.t -> Command.t

The Unix mv command.

val cp : Pathname.t -> Pathname.t -> Command.t

The Unix cp command.

val ln_f : Pathname.t -> Pathname.t -> Command.t

The Unix ln -f command.

val ln_s : Pathname.t -> Pathname.t -> Command.t

The Unix ln -s command.

val rm_f : Pathname.t -> Command.t

The Unix rm -f command.

val chmod : Command.spec -> Pathname.t -> Command.t

The Unix chmod command (almost deprecated).

val cmp : Pathname.t -> Pathname.t -> Command.t

The Unix cmp command (almost deprecated).

val hide_package_contents : string -> unit

hide_package_contents pack_name Don't treat the given package as an open package. So a module will not be replaced during linking by this package even if it contains that module.

val tag_file : Pathname.t -> Tags.elt list -> unit

tag_file filename tag_list Tag the given filename with all given tags.

val tag_any : Tags.elt list -> unit

tag_any tag_list Tag anything with all given tags.

val tags_of_pathname : Pathname.t -> Tags.t

Returns the set of tags that applies to the given pathname.

type hook =

`\|`	`Before_hygiene`
`\|`	`After_hygiene`
`\|`	`Before_options`
`\|`	`After_options`
`\|`	`Before_rules`
`\|`	`After_rules`

Here is the list of hooks that the dispatch function have to handle. Generally one respond to one or two hooks (like After_rules) and do nothing in the default case.

val dispatch : (hook -> unit) -> unit

dispatch hook_handler Is the entry point for ocamlbuild plugins. Every plugin must call it with a hook_handler where all calls to plugin functions lives.