Module Dkml_c_probe.C_confSource

Cross-compiler friendly configuration of C headers and libraries.

Problem

Let's take the C library "gmp" (GNU Multiprecision Bignum Library) as an example. Many OCaml libraries depend on it through the "conf-gmp" Opam package. However almost all "conf-*" packages use the system's package manager to install the C library or use "pkg-config" to locate the C library. So if the system were a Linux x86_64 system and the cross-compiling toolchain is for Android ARM64, the Android ARM64 executables should never be linked to the system Linux x86_64 C library "gmp".

Solution

A solution is to let the consumer define and link to pre-existing cross-compiled libraries.

During cross-compilation each distinct toolchain would need its own external C libraries and perhaps C headers. This module lets the developer specify the locations of these libraries and headers by setting environment variables.

The environment variables follow the grammar:

variableName:
  'CP_' clibrary '_' type '_DEFAULT' ('_' toolchain)?
  ;
clibrary:
  [A-ZA-Z0-9_]+
  ;
toolchain:
  [A-ZA-Z0-9_]+
  ;
type:
  'CP' | 'LINK'
  ;

(*  Semicolons separate list items in a variable *)
variableValue:
  listItem (';' listItem)*
  ;
(*  Any 7-bit ASCII printable character are valid. Spaces are significant,
    and there are no space characters. *)
listItem:
  ([\x20-\x7E] - ';')*
  ;

Both "<clibrary>" and "<toolchain>" must be uppercased and sanitized with underscores.

For example, the following environment variables can be set for the C library "gmp":

CP_GMP_CC_DEFAULT                 = -IZ:/build/darwin_arm64/vcpkg_installed/arm64-osx/include
CP_GMP_CC_DEFAULT_DARWIN_X86_64   = -IZ:/build/darwin_x86_64/vcpkg_installed/x64-osx/include
CP_GMP_LINK_DEFAULT               = -LZ:/build/darwin_arm64/vcpkg_installed/arm64-osx/lib;-lgmp
CP_GMP_LINK_DEFAULT_DARWIN_X86_64 = -LZ:/build/darwin_x86_64/vcpkg_installed/x64-osx/lib;-lgmp

Semantically each environment variable is equivalent to an optional list of items. In particular:

• An undefined environment variable and an empty environment variable are equivalent to an absent list (ie. None)
• Any empty list item is skipped. So you can use ";" to mean Some []

For CC type variables, each list item is a command line option:

• "-I<path>" adds an include directory. The path should have forward slashes, even on Windows.

For LINK type variables, each list item is a command line option:

• "-L<path>" adds a library directory. The path should have forward slashes, even on Windows.
• "-l<library>" adds a named library.

There are no spaces between the command line option (ex. "-L") and the option value.

As a library author you can use this module to convert these CC and LINK variables into the paricular convention used by your OCaml tool or C compiler. For example, using the compiler_flags_msvc in the "darwin_x86_64" toolchain will give you:

   let link_flags = ["-LIBPATH:Z:/build/darwin_x86_64/vcpkg_installed/x64-osx/lib"; "gmp.lib"]
   let cc_flags = ["-IZ:/build/darwin_x86_64/vcpkg_installed/x64-osx/include"]

while using the tool_flags_ocamlmklib in the same toolchain will give you:

   let link_flags = ["-LZ:/build/darwin_x86_64/vcpkg_installed/x64-osx/lib"; "-lgmp"]

Prerequisites

The consumer of your library will need:

• cross-compiled toolchains named according to C_abi's "get_abi_name".

• pre-existing cross-compiled libraries. The cross-compiled libraries are available from many sources:

  • development environments like Android Studio
  • C package managers like vcpkg and Conan
  • "sysroot" images
  • direct downloads from architecture specific package repositories
• set environment variables that reference the pre-existing cross-compiled libraries. For an Opam switch you can use opam option setenv+="CP_xxx=yyy"; the docs for setenv are at https://opam.ocaml.org/doc/Manual.html#opamfield-setenv

Integrations

When you are using the Dune Configurator you should:

1. Use the load_from_dune_context_name constructor by supplying the Dune variable "%{context_name}"
2. Use compiler_flags_of_ccomp_type to get the compiler flags by supplying the Dune variable "%{ocaml-config:ccomp_type}".

Dune variables are described in the General Concepts of the Dune Docs.

Module Documentation