package b0

  1. Overview
  2. Docs
package b0
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module B0_ocaml.CodeSource

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:

  • When compiling a library for installation, all codes supported by the installation must be generated.
  • When compiling an executable tool only one code needs to be generated. For example most often native code if available and bytecode if not.
  • For a browser executable and considering B0_jsoo, only the bytecode must be generated. Native code compilation is technically incompatible.

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

Sourcetype t =
  1. | Byte
    (*

    OCaml bytecode.

    *)
  2. | Native
    (*

    Native code.

    *)
  3. | Wasm
    (*

    Wasm code, not available use B0_jsoo instead.

    *)

The type for codes.

Sourcemodule Set : sig ... end

Sets of codes.

Sourceval none : Set.t

none is Set.empty

Sourceval byte : Set.t

byte is Set.singletonByte

Sourceval native : Set.t

native is Set.singletonNative

Sourceval wasm : Set.t

wasm is Set.singletonNative

Sourceval traditional : Set.t

traditional has Byte and Native.

Sourceval all : Set.t

all has Byte, Native and Wasm.

Metadata keys

Sourcetype 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.

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
Sourceval 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.

Sourceval 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.

Sourceval 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

Sourcetype 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.

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

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

pp formats code values.

Sourceval pp_wanted : wanted B0_std.Fmt.t

pp_wanted formats desires.