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.