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:
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.
module Set : sig ... end
Sets of codes.
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
.
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.
B0_store.key
, determined once and user settable from the cli or a conf specval 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
type wanted =
| 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.
| 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
val pp : t B0_std.Fmt.t
pp
formats code values.
val pp_wanted : wanted B0_std.Fmt.t
pp_wanted
formats desires.