Previous  Up  Next

Module Assemblage.Conf

module Conf: sig .. end
Build configuration.

A configuration represents a concrete build environment for a project. It allows to adjust a project's outcomes to the build environment and desires of the end user.

A configuration is a map from named keys to configuration values. The value associated to a key is either determined automatically from the environment by the key's default value or explicitly set by the end user of the build system (e.g. manually from the command line or via an IDE).

A configuration value denotes an OCaml value that depends on the configuration. Configuration values are transformed and composed into new values and keep track of the set of keys that are needed to define them. Since they must be used to define a project, it means that assemblage can (conservatively) determine the configuration keys of a project.

Configuration schemes are named, user defined, partial configurations. They allow the ends user to quickly setup a given configuration (in general it's a good practice not to use them in the context of package distribution, try to rely on the defaults as much as possible).

Important. Before defining your own keys you should prefer the built-in ones.


Configuration values


type 'a value
The type for configuration values evaluating to OCaml values of type 'a.

A value of this type means that it depends on the configuration: its concrete value can not be determined without a configuration. We say that we evaluate a value when we take a configuration and determine its OCaml value in that configuration.

val const : 'a -> 'a value
const v is a configuration value that evaluates to v.
val app : ('a -> 'b) value ->
       'a value -> 'b value
app f v is a configuration value that evaluates to the result of applying the evaluation of v to the one of f.
val ($) : ('a -> 'b) value ->
       'a value -> 'b value
f $ v is app f v.
val true_ : bool value
true_ is const true.
val false_ : bool value
false_ is const false.
val neg : bool value -> bool value
neg a is const ( not ) $ a.
val (&&&) : bool value ->
       bool value -> bool value
a &&& b is const ( && ) $ a $ b.
val (|||) : bool value ->
       bool value -> bool value
a &&& b is const ( || ) $ a $ b.
val pick_if : bool value ->
       'a value ->
       'a value -> 'a value
pick_if c a b is a if c evaluates to true and b otherwise.
module Option: sig .. end

Configuration converters

A configuration converter transforms a string value to an OCaml value and vice-versa. There are a few built-in converters.

type 'a parser = string -> [ `Error of string | `Ok of 'a ]
The type for configuration converter parsers.
type 'a printer = Format.formatter -> 'a -> unit
The type for configuration converter printers.
type 'a converter = 'a parser * 'a printer
The type for configuration converters.
val parser : 'a converter -> 'a parser
parser c is c's parser.
val printer : 'a converter -> 'a printer
converter c is c's printer.

Configuration keys


type 'a key
The type for configuration keys that map to values of type 'a.
val key : ?public:bool ->
       ?docs:string ->
       ?docv:string ->
       ?doc:string ->
       string ->
       'a converter ->
       'a value -> 'a key
key public docs docv doc name conv v is a configuration key named name that maps to value v by default. converter is used to convert key values provided by end users.

If public is true (default), the key is public which means that it can be redefined by the end user. In this case docs is the title of a documentation section under which the key is documented (defaults to Assemblage.Conf.docs_project). doc is a short documentation string for the key, this should be a single sentence or paragraph starting with a capital letter and ending with a dot. docv is a meta-variable for representing the values of the key (e.g. "BOOL" for a boolean).
Raises Invalid_argument if the key name is not made of a sequence of ASCII lowercase letter, digit, dash or underscore. FIXME not implemented.

Warning. No two public keys should share the same name as this may lead to difficulties in the UI of certain assemblage drivers like the inability to be able to precisely refer to a key. In particular do not reuse the built-in names (they have the same name as the key variables with underscores replaced by dashes).

val value : 'a key -> 'a value
value k is a value that evaluates to k's binding in the configuration. Note that this may be different from the value given in Assemblage.Conf.key.

Configuration schemes


type scheme
The type for configuration schemes. A configuration scheme is a named set of configuration key-value binding definitions.
type def
The type for key-value binding definitions.
val def : 'a key -> 'a -> def
def k v is a definition that binds key k to value v.
val defv : 'a key -> 'a value -> def
defv k v is a definition that binds key k to value v.
val scheme : ?doc:string ->
       ?base:scheme ->
       string -> def list -> scheme
scheme base name defs is a configuration scheme named name that has the key-value bindings of base together with those of defs, the latter taking precedence. doc is a documentation string for the scheme, it should be a single sentence or paragraph starting with a capital letter and ending with a dot.

Built-in configuration keys



Project keys


val project_version : string key
project_version is the version number of the project (defaults is inferred from the VCS). FIXME what to do on distrib setup ? read from a file ? Best would be that the distrib procedure sets the version field of the opam file in the tarball and that we read from there.
val docs_project : string
docs_project is the name of the documentation section in which project keys are described.

Build property keys


val debug : bool key
debug is true iff build products in general must support debugging (defaults to false).
val profile : bool key
profile is true iff build products in general must support profiling (defaults to false).
val warn_error : bool key
warn_error is true iff tools in general should treat warnings as errors (defaults to false).
val test : bool key
test is true iff test build products should be built (defaults to false).
val doc : bool key
doc is true iff documentation should be built (defaults to false).
val jobs : int key
jobs is the number of jobs to run for building (defaults to machine processor count).
val docs_build_properties : string
docs_build_properties is the name of the documentation section in which build property keys are described.

Build directory keys


val root_dir : Assemblage.Path.t key
root_dir is the absolute path to the project directory (defaults to the driver program current directory).
val build_dir : Assemblage.Path.rel key
build_dir is the path to the build directory expressed relative to the Assemblage.Conf.root_dir (defaults to "_build").
val docs_build_directories : string
docs_build_directories is the name of the documentation section in which build directory keys are described.

OCaml system keys


val ocaml_native_tools : bool key
ocaml_native_tools is true to use the native compiled (.opt) OCaml tools (defaults to true).
val ocaml_version : (int * int * int * string option) key
ocaml_version is the OCaml compiler version (defaults is inferred by invoking an OCaml compiler).
val ocaml_byte : bool key
ocaml_byte is true iff OCaml byte code compilation is requested (defaults to true).
val ocaml_native : bool key
ocaml_native is true iff OCaml native code compilation is requested (defaults to true).
val ocaml_native_dynlink : bool key
ocaml_native_dynlink is true iff OCaml native code dynamic linking compilation is requested (defaults to true).
val ocaml_js : bool key
ocaml_js is true iff OCaml JavaScript compilation is requested (defaults to false).
val ocaml_annot : bool key
ocaml_annot is true iff OCaml binary annotation files generation is requested (defaults to true).
val ocaml_build_ast : bool key
ocaml_build_ast is true if OCaml source AST should be built and dumped to a file with Assemblage.Conf.ocaml_dumpast (defaults to false). This may speed up your builds if you have pre-processing cancer.
val ocaml_dumpast : string key
ocaml_dumpast is the ocaml-dumpast utility (defaults to "ocaml-dumpast").
val ocamlc : string key
ocamlc is the ocamlc utility (defaults to "ocamlc" or "ocamlc.opt" according to Assemblage.Conf.ocaml_native_tools).
val ocamlopt : string key
ocamlopt is the ocamlopt utility (defaults to "ocamlopt" or "ocamlopt.opt" according to Assemblage.Conf.ocaml_native_tools).
val js_of_ocaml : string key
js_of_ocaml is the js_of_ocaml utility (defaults to "js_of_ocaml").
val ocamldep : string key
ocamldep is the ocamldep utility (defaults to "ocamldep" or "ocamldep.opt" according to Assemblage.Conf.ocaml_native_tools).
val ocamlmklib : string key
ocamlmklib is the ocamlmklib utility (defaults to "ocamlmklib").
val ocamldep : string key
ocamldep is the ocamldoc utility (defaults to "ocamldoc" or "ocamldoc.opt" according to Assemblage.Conf.ocaml_native_tools).
val ocamllex : string key
ocamllex is the ocamllex utility (defaults to "ocamllex" or "ocamllex.opt" according to Assemblage.Conf.ocaml_native_tools).
val ocamlyacc : string key
ocamlyacc is the ocamlyacc utility (defaults to "ocamlyacc").
val ocaml : string key
ocaml is the ocaml utility (defaults to "ocaml").
val ocamlrun : string key
ocamlrun is the ocamlrun utility (defaults to "ocamlrun").
val ocamldebug : string key
ocamldebug is the ocamldebug utility (defaults to "ocamldebug").
val ocamlprof : string key
ocamlprof is the ocamlprof utility (defaults to "ocamlprof").
val ocamlfind : string key
ocamlfind is the ocamlfind utility (defaults to "ocamlfind").
val opam : string key
opam is the opam tool (defaults to "opam").
val opam_installer : string key
opam_installer is the opam-installer tool (defaults to "opam-installer")
val opam_admin : string key
opam_admin is the opam-admin tool (defaults to "opam-admin")
val docs_ocaml_system : string
docs_ocaml_system is the name of the documentation section in which OCaml system keys are described.

C system keys


val c_dynlink : bool key
c_dynlink is true iff C dynamic linking compilation is requested (default to true).
val c_js : bool key
c_js is true iff C JavaScript compilation is request (defaults to false). FIXME through e.g. emscripten should we support that ? Well it's just a few actions after all.
val cc : string key
cc is the C compiler (defaults to "cc")
val pkg_config : string key
pkg_config is the pkg-config utility (defaults to "pkg-config").
val docs_c_system : string
docs_c_system is the name of the documentation section in which C system keys are described.

Machine information keys


val uname : string key
uname is the uname utility (defaults to "uname").
val host_os : string key
host_os is the operating system name of the host machine (defaults is "Win32" if the driver's Sys.os_type is "Win32" otherwise it is the lowercased result of Assemblage.Conf.uname invoked with -s).
val host_arch : string key
host_arch is the hardware architecture of the host machine (defaults to the value of the driver's "PROCESSOR_ARCHITECTURE" environment variable if the driver Sys.os_type is "Win32" otherwise it is the lowercased result of Assemblage.Conf.uname invoked with -m)
val host_word_size : int key
host_word_size is the host machine word bit size (defaults to the driver's Sys.word_size).
val target_os : string key
target_os is the operating system name of the target machine (defaults to the value of Assemblage.Conf.host_os).
val target_arch : string key
target_arch is the hardware architecture of the target machine (defaults to the value of Assemblage.Conf.host_arch).
val target_word_size : int key
target_word_size is the target machine word bit size (defaults to the value of Assemblage.Conf.host_word_size).
val docs_machine_information : string
docs_machine_utilities is the name of the documentation section in which machine information keys are described.

System utility keys

Note. Action commands should not use these utilities directly but use portable system utility invocations.

val echo : string key
echo is the echo utility (defaults to "echo").
val cd : string key
cd is the cd utility (defaults to "cd").
val ln : string key
ln is the ln utility (defaults to "ln"). FIXME windows.
val cp : string key
cp is the cp utility (defaults to "cp" on Unix and "copy" on Windows).
val mv : string key
mv is the mv utility (defaults to "mv" on Unix and "move" on Windows).
val rm : string key
rm is the rm utility (defaults to "rm" on Unix and "del" on Windows).
val rmdir : string key
rmdir is the rmdir utility (defaults to "rmdir").
val mkdir : string key
mkdir is the mkdir (defaults to "mkdir").
val cat : string key
cat is the cat (defaults to "cat" on Unix and "type" on Windows).
val make : string key
make is the make utility (defaults to "make"). FIXME remove that.
val docs_system_utilities : string
docs_system_utilities is the name of the documentation section in which system utility keys are described.

Built-in value converters


val bool : bool converter
bool converts values with bool_of_string.
val int : int converter
int converts values with int_of_string.
val string : string converter
string converts values with the indentity function.
val path : Assemblage.Path.t converter
path converts value with Assemblage.Path.of_string.
val abs_path : Assemblage.Path.abs converter
path converts value with Assemblage.Path.of_string.
val rel_path : Assemblage.Path.rel converter
path converts value with Assemblage.Path.of_string.
val enum : (string * 'a) list -> 'a converter
enum l converts values such that string names in l map to the corresponding value of type 'a.
val version : (int * int * int * string option) converter
version converts values of the form [v|V]major.minor[.patch][(-|+).*].