Previous  Up  Next

Module Assemblage.Args

module Args: sig .. end
Command argument bundles.

Argument bundles are conditional bindings from execution contexts to lists of command arguments. They provide a simply mechanism to allow the end user to inject flags on the command lines of actions.

See Argument bundles basics and Argument bundle propagation model for more details.


Argument bundles


type t
The type for argument bundles.
val v : ?exists:bool Assemblage.Conf.value ->
       Assemblage.Ctx.t -> string list Assemblage.Conf.value -> t
v ~exists ctx args is the bundle that binds ctx to args whenever exists evaluates to true (defaults to Assemblage.Conf.true_).
val vc : ?exists:bool Assemblage.Conf.value ->
       Assemblage.Ctx.t -> string list -> t
vc ~exists ctx args is v ~exists ctx (Conf.const args).
val empty : t
empty is the empty bundle.
val is_empty : t -> bool
is_empty a is true if a is empty.
val append : t -> t -> t
append a a' is the bundle that has the bindings of a and a'. If both a and a' have bindings for the same context, they are preserved each with their own condition of existence and it is guaranteed that the binding arguments of a will appear before those of a' on the command line.
val (@@@) : t -> t -> t
a @@@ a' is append a a'.
val concat : t list -> t
concat args is List.fold_left append empty args

Built-in argument bundles


val linkall : t
linkall is the -linkall flag in the right `OCaml contexts.
val thread : t
thread is the -thread flag in the right `OCaml contexts.
val vmthread : t
vmthread is the -vmthread flag in the right `OCaml contexts.
val cclib : string list -> t
The -cclib x args. FIXME
val ccopt : string list -> t
The -ccopt x args. FIXME
val stub : string -> t
stub s adds -cclib -ls -dllib -ls to the bytecode linking options and -cclib -ls to the native linking options. FIXME

Argument bundles basics

Argument bundles allow to tweak actions by prepending additional arguments to their command invocations. For example the following bundle: 

let ocaml_debug =

  let debug ctx = Args.vc ~exists:Conf.debug ctx ["-g"] in

  Args.(debug [`OCaml; `Compile] @@@ debug [`OCaml; `Link])
used with a part will, whenever the configuration value of Assemblage.Conf.debug evaluates to true, prepend the option -g to any command of its actions that operates in a context that contains the `OCaml and `Compile or `Link elements. Note, you don't need the above definition, assemblage's OCaml built-in actions know how to handle the Assemblage.Conf.debug key for you.

Given an argument bundle and a command to execute, every binding in the bundle is considered, if the context of the binding matches the context of the command and the binding exists, the arguments of the binding are prepended to the command invocation.

Warning. Do not rely on the order of context matches for your command lines to be valid. The argument bundle mechanism is a rough end user build action tweaking mechanism that is mostly useful for injecting command line options, not positional arguments. The final bundle given to actions is the concatenation of many bundle sources (project, parts, action implementation) that may be applied in arbitrary order.

Argument bundle propagation model

Which argument bundles are applied to an action (and its commands):

  1. Each part has a user defined argument bundle, this bundle is automatically applied to any of its actions.
  2. Each part has needs. In these needs there are parts that integrated and other that are consulted. When a part i is integrated by a part p its build actions are integrated into p. In that case these actions have both the argument bundle of the integrated part i and that of the integrating part p.
  3. Finally the project's argument bundle is added to any action.