Implementation of run-time support libraries for KreMLin
This directory contains F* source files that model various C concepts and libraries. These are collectively known as the "kremlib".
This directory additionally provides trusted, hand-written implementations:
- of the F* models from kremlib (in
- of selected modules from F*'s own standard library (also in
c/, prefixed with
Once built, this directory produces:
- a set of C files ready to be integrated by a consumer into their own source
- a pre-built version of libkremlib (as
This Makefile extracts and packages several variants of kremlib, to be found in
dist/ subdirectory. The default build is
dist/generic, and the resulting
object file is
A client wishing to integrate kremlib in their project should:
- leave these files in their own directory
- rely on
Makefile.basic, a sound, parallel Makefile, to compile and generate
libkremlib.aat the final linking stage.
Clients who have more complex use-cases (shared library, MSVC, 32-bit, ancient toolchains) should read the remainder of this document.
What is in kremlib (default build)
kremlib/dist/generic directory contains numerous header files for the
F* standard library modules. These header files are crucial, as they
embody the expected function signatures that kremlib must provide when
implementing some F* standard library module. They are automatically
re-generated from the source F* files.
kremlib/c directory contains corresponding unverified implementations,
which are hand-written. Each C file, e.g.
its generated header, e.g.
kremlib/dist/generic/FStar_Date.h, thus ensuring
that the implementation provides the correct C function prototype.
Main build variants for kremlib
There are several build configurations supported for kremlib. Remember that
the generated code can be easily customized by passing more KreMLin options
The default build (
The default build:
- assumes a 64-bit target and either GCC or clang
- includes every implementation found in
FStar.UInt128with external linkage.
The minimalistic builds (
The generic build configuration above includes as much as possible in terms of
implementations. However, one oftentimes wishes to restrict the amount of files
present in kremlib. To that end, the
dist/minimal directory contains a
barebones kremlib, made up of only the machine integers.
A verified, universal FStar.UInt128 implementation (
For clients that wish to use a verified uint128 implementation from C, the
dist/uint128 directory contains a self-contained, standalone implementation of
FStar.UInt128. It must be compiled with
In the event that the target platform does not support
unsigned __int128, this
implementation can be used in lieu of
An unverified, MSVC-specific FStar.UInt128 implementation
The implementation of
FStar.UInt128 in the default build relies on
unsigned __int128, a GCC/Clang-specific extension. In the event that one should wish to
build with MSVC, it suffices to use
fstar_uint128_msvc.c file relies on
compiler intrinsics, unless
KRML_VERIFIED_UINT128 is defined, in which case it
uses the slow, verified implementation (see immediately above).
No Makefile is provided for this build configuration, but the user might wish to take inspiration from https://github.com/project-everest/mitls-fstar/blob/master/src/windows/kremlib/makefile.vs
One can also use
fstar_uint128_msvc.c in the
minimal build configuration.