Module B0_ocaml.Code

OCaml compiler code generation specification.

In an OCaml build, the codes that are generated must be precisely known because the OCaml compilers compete to produce shared build artefacts. Besides, the code that needs to be generated for a unit depends on how it will be used. Here are a few examples:

The user of the build may also want to choose the codes to be generated. If unspecified, a reasonable default should be derived depending on the units that must build.

We call built codes the codes generated in a build. They are stored in Code.built which OCaml build procedures should consult and adapt to.

Build units can constrain the codes they want their build procedure to generate by defining the Code.restrict function which given Code.built must return which codes must be generated for the unit (or the empty set if they can't build). The result is used by the unit's build procedure to act accordingly.

Now remains how to describe how Code.built is determined. The user can specify a build desire with the Code.wanted key, see its documentation for details.

Code

type t =
  1. | Byte
    (*

    OCaml bytecode.

    *)
  2. | Native
    (*

    Native code.

    *)
  3. | Wasm
    (*

    Wasm code, not available use B0_jsoo instead.

    *)

The type for codes.

module Set : sig ... end

Sets of codes.

val none : Set.t

none is Set.empty

val byte : Set.t

byte is Set.singletonByte

val native : Set.t

native is Set.singletonNative

val wasm : Set.t

wasm is Set.singletonNative

val traditional : Set.t

traditional has Byte and Native.

val all : Set.t

all has Byte, Native and Wasm.

Metadata keys

type restrict = string * (Set.t -> Set.t)

The type for codes restrictions. Given a set of codes to generate, indicates which ones to generate in a given context. The string is used for documentation.

val restrict : restrict B0_meta.key

restrict can be set on a unit to define which codes should should be generated for the unit. It is invoked by build procedures with the values of Code.built and should return a subset of it. It default to Fun.id.

For example B0_ocaml.exe uses unique_favour_native.

TODO.

  • This should be able to access the configuration.
  • This should rather be a per unit B0_store.key, determined once and user settable from the cli or a conf spec
val unique_favour_native : restrict

unique_favour_native returns a single code which is Native if in the given set and Set.min_elt otherwise, that is Byte if it's in the set.

val check_any : supported:Set.t -> by:B0_build.t -> unit B0_std.Fut.t

check_any ~supported ~by:build fails the current build unit if the intersection of supported and built in build is empty. This should be used by build procedures to check they can be built. These empty intersections may happen on dynamic requests of may units.

val check_all : supported:Set.t -> by:B0_build.t -> unit B0_std.Fut.t

check_all is like check_any but checks for containement of supported in built.

Store keys

type wanted =
  1. | Auto
    (*

    The set made of the union of calling all Code.restrict of OCaml executable units that must build with B0_ocaml.Conf.codes or B0_ocaml.Conf.codes itself if there is no such executable.

    *)
  2. | Wanted of t list
    (*

    These exact codes.

    *)

The type for generated code wanted by the user.

val wanted : wanted B0_store.key

wanted indicates which codes should be generated. Defaults to Auto.

val built : Set.t B0_store.key

built is a memo key indicating the built codes. By default determines by consulting wanted. It fails the build if the later is Wanted w and w is not included in B0_ocaml.Conf.codes.

Formatting

val pp : t B0_std.Fmt.t

pp formats code values.

val pp_wanted : wanted B0_std.Fmt.t

pp_wanted formats desires.