Module Assemblage.Part

module Part: sig .. end

Parts, part sets and maps.

Parts are the logical build units that define a project, they define the project's outcomes for every possible configuration.

A part defines a coherent set of build actions. There are different kinds of part, each which specific metadata that it uses to define its action. Parts may also refer to, or integrate, other parts to define their actions.

A part can also be seen as defining the outputs of its build actions. These build products depend on the configuration.

In addition to part specific metadata, each part has the following attributes that the user specifies:

A name used to identify the part; note that it may not be unique. The name is often used as metadata itself. For example it defines the library name for library parts or the name of a compilation unit, etc.
A kind that identifies the kind of metadata the part uses and the build action it produces.
A usage. This is a broad usage label to classify parts. It can be used by drivers to derive bureaucratic information about a project. For example if some of parts are only used for developing the project they should have a `Dev usage; this will allow drivers to understand that their dependencies are only needed for development.
Needs. This is a list of parts used by the part to define its actions. The way a part uses its needs depends on its kind, consult their specific documentation.
An exists configuration boolean that indicates whether a part exists in a given configuration. If the part doesn't exist it doesn't define any build action. For example the existence of a library may depends on the presence of an optional package.
An argument bundle applied to its actions. See Argument bundles basics for more information about argument bundles.

Given all this information a part will give you build actions whose outputs define a part's build products.

Kinds

type kind = [ `Base | `Bin | `Dir | `Doc | `Lib | `Pkg | `Run | `Unit ]

The type for part kinds. See the corresponding individual modules for more information.

val pp_kind : Format.formatter -> kind -> unit

pp_kind ppf k prints an unspecified represetation of k on ppf.

Usage

type usage = [ `Build | `Dev | `Doc | `Other of string | `Outcome | `Test ]

The type for part usage.

`Outcome, the part is an outcome of the project.
`Build, the part is used for building the project.
`Dev, the part is used when developing the project.
`Test, the part is used to test the project.
`Doc, the part is used for building the project documentation.
`Other u, the part is used according to a user-defined semantics.

val pp_usage : Format.formatter -> usage -> unit

pp_usage ppf u prints an unspecified representation of u on ppf.

Metadata

type meta

The type for part metadata

val meta_key : unit -> ('a -> meta) * (meta -> 'a option)

meta_key () pairs a metadata injector and projector.

val meta_nil : meta

meta_nil is metadata that cannot be accessed.

Parts

type [< Assemblage.part_kind ] t = ([< Assemblage.part_kind ] as 'a) Assemblage.part

The type for parts.

val v : ?usage:usage ->
       ?exists:bool Assemblage.Conf.value ->
       ?args:Assemblage.Args.t ->
       ?meta:meta ->
       ?needs:[< Assemblage.part_kind ] Assemblage.part list ->
       ?root:Assemblage.Path.rel Assemblage.Conf.value ->
       ?actions:(kind Assemblage.part ->
                 Assemblage.Action.t list Assemblage.Conf.value) ->
       ?check:(kind Assemblage.part -> bool Assemblage.Conf.value) ->
       string -> [< Assemblage.part_kind > `Base ] Assemblage.part

v ?usage ?exists ?meta ?needs ?args ?actions ?check name defines a base part named name.

usage is the part's usage, default to `Outcome.
exists is a condition for the part to exist, defaults to Assemblage.Conf.true_.
args is an argument bundle added to the actions of the part, defaults to Assemblage.Args.empty.
meta is the part's metadata, defaults to Assemblage.Part.meta_nil.
needs are the parts that are needed by the part, defaults to [], the given list is uniqified.
root is a build root for the part, usually best left unspecified. Note that this value should not be used as a constant for defining actions as it may be redefined by integrating parts. Use Assemblage.Part.root p instead.
actions is the function that defines the actions associated to the part. The function is given the part itself which allows to access its metadata. Action outputs should be generated in the directory returned by Assemblage.Part.root p, not the root argument given to the constructor. This will ensure that the part adapts correctly if it is integrated by another.
check is a diagnostic function that should Assemblage.Log information about potential problems with the part and return true if there is no problem.

val kind : [< Assemblage.part_kind ] Assemblage.part -> kind

kind p is p's kind.

val name : [< Assemblage.part_kind ] Assemblage.part -> string

name p is p's name.

val usage : [< Assemblage.part_kind ] Assemblage.part -> usage

usage p is p's usage.

val exists : [< Assemblage.part_kind ] Assemblage.part -> bool Assemblage.Conf.value

exists p determines if p exists.

val meta : [< Assemblage.part_kind ] Assemblage.part -> meta

meta p is p's metadata.

val get_meta : (meta -> 'a option) ->
       [< Assemblage.part_kind ] t -> 'a

get_meta proj p uses proj on p's metadata.
Raises Invalid_argument if proj returns None.

val root : [< Assemblage.part_kind ] Assemblage.part ->
       Assemblage.Path.rel Assemblage.Conf.value

root p is p's root build directory expressed relative to Assemblage.Conf.root_dir. Most of the time the actions of a part will output their build products in this direcory. This directory may change when a part is integrated in another.

val root_path : [< Assemblage.part_kind ] Assemblage.part ->
       Assemblage.Path.t Assemblage.Conf.value

root_path is like Assemblage.Part.root but as a generic path.

val needs : [< Assemblage.part_kind ] Assemblage.part ->
       kind t list

needs p is the (uniqified) list of parts needed by p to define itself.

val actions : [< Assemblage.part_kind ] Assemblage.part ->
       Assemblage.Action.t list Assemblage.Conf.value

actions p are the actions to build part p. If Assemblage.Part.exists p evaluates to false this evaluates to the empty list.

val check : [< Assemblage.part_kind ] Assemblage.part -> bool Assemblage.Conf.value

check p logs information about potential problems with p and returns true if there is no such problem.

val id : [< Assemblage.part_kind ] Assemblage.part -> int

id p is a unique id for the part.

val equal : [< Assemblage.part_kind ] Assemblage.part ->
       [< Assemblage.part_kind ] Assemblage.part -> bool

equal p p' is (id p) = (id p').

val compare : [< Assemblage.part_kind ] Assemblage.part ->
       [< Assemblage.part_kind ] Assemblage.part -> int

compare p p' is compare (id p) (id p').

val redefine : ?check:(kind Assemblage.part -> bool Assemblage.Conf.value) ->
       ?actions:(kind Assemblage.part ->
                 Assemblage.Action.t list Assemblage.Conf.value) ->
       ([< Assemblage.part_kind ] as 'a) Assemblage.part -> 'a Assemblage.part

redefine check actions p is p with check function check and actions function action (both defaults to p's one if unspecified).

Warning. As far as Assemblage is concerned this is equivalent to Obj.magic.

File part

val file : ?usage:usage ->
       ?exists:bool Assemblage.Conf.value ->
       Assemblage.Path.t -> [< Assemblage.part_kind > `Base ] Assemblage.part

file p is a part with a noop action that inputs p.

Part integration

val integrate : ?add_need:(kind Assemblage.part -> bool) ->
       ([< Assemblage.part_kind ] as 'a) Assemblage.part ->
       [< Assemblage.part_kind ] Assemblage.part -> 'a Assemblage.part

integrate ?add_need i p is i as integrated in p. This is i except its root and usage now match those of p and the needs of p that returned true on add_need were added to the new part. add_need defaults to fun _ -> false. The new part will adapt to the new parameters by recomputing actions using the part's action definition function.

Coercions

val coerce : ([< Assemblage.part_kind ] as 'a) ->
       [< Assemblage.part_kind ] Assemblage.part -> 'a Assemblage.part

coerce k p coerces p to kind k,
Raises Invalid_argument if p's kind is not k.

val coerce_if : ([< Assemblage.part_kind ] as 'a) ->
       [< Assemblage.part_kind ] Assemblage.part -> 'a Assemblage.part option

coerce_if k p is Some if p is of kind k and None otherwise.

Part lists

val list_actions : kind Assemblage.part list ->
       Assemblage.Action.t list Assemblage.Conf.value

list_actions ps is the list of actions of the parts ps. The list order is preserved.

val list_uniquify : kind Assemblage.part list ->
       kind Assemblage.part list

list_uniquify ps is ps with duplicates as determined by Assemblage.Part.equal removed. The list order is preserved.

val list_keep : (([< Assemblage.part_kind ] as 'a) Assemblage.part -> bool) ->
       'a Assemblage.part list -> 'a Assemblage.part list

list_keep pred ps is the elements of ps that satisfy pred. The list order is preserved.

val list_keep_map : (([< Assemblage.part_kind ] as 'a) Assemblage.part -> 'b option) ->
       'a Assemblage.part list -> 'b list

list_keep_map f ps is the elements of ps for which f returns Some value. The list order is according to ps.

val list_keep_kind : ([< Assemblage.part_kind ] as 'a) ->
       [< Assemblage.part_kind ] Assemblage.part list -> 'a Assemblage.part list

list_keep_kind k ps is the elements of ps that have kind kind. The list order is preserved.

val list_keep_kinds : kind list ->
       ([< Assemblage.part_kind ] as 'a) Assemblage.part list ->
       'a Assemblage.part list

list_keep_kinds ks is the elements of ps that have one of the kind ks. The list order is preserved.

val list_fold : ('a -> ([< Assemblage.part_kind ] as 'b) Assemblage.part -> 'a) ->
       'a -> 'b Assemblage.part list -> 'a

list_fold f acc ps is List.fold_left f acc ps.

val list_fold_kind : ([< Assemblage.part_kind ] as 'b) ->
       ('a -> 'b Assemblage.part -> 'a) ->
       'a -> [< Assemblage.part_kind ] Assemblage.part list -> 'a

list_fold kind f acc ps is like Assemblage.Part.list_fold but folds only over the parts whose kind is kind.

val list_fold_rec : ('a -> kind Assemblage.part -> 'a) ->
       'a -> kind Assemblage.part list -> 'a

fold_rec f acc l folds over the parts of l and their needs recusively, in depth first pre-order. If a part appears twice in the traversal is it only folded over the first time.

val list_fold_kind_rec : ([< Assemblage.part_kind ] as 'b) ->
       ('a -> 'b t -> 'a) ->
       'a -> kind t list -> 'a

list_fold_kind_rec is the same traversal as Assemblage.Part.list_fold_rec but only parts whose kind is kind are folded over.

Part sets and maps

module Set: sig .. end

module Map: sig .. end