CMAKE_OCamlDune_COMPILER_EXTERNAL_REQUIRED

A CMake option that, when ON, tells DkSDK to use external OCaml build tools and compiler rather than build its own.

By default, if DkML is installed on your machine and DKML_AVOID_GLOBAL_INSTALLATION is OFF then CMAKE_OCamlDune_COMPILER_EXTERNAL_REQUIRED is ON; otherwise it is OFF.

CMAKE_OCamlDune_COMPILER_EXTERNAL_REQUIRED=OFF

The implications when CMAKE_OCamlDune_COMPILER_EXTERNAL_REQUIRED is OFF are:

  • The initial build of the project will have to wait tens of minutes while the OCaml compiler and tools like dune are built from scratch

  • You will have to setup the Unix-specific direnv tool so you can get command line access to dune; look at your project's DkSDK.md for instructions on that. Alternatively, you can run ./dk dksdk.build.dune and follows the instructions it displays.

    If you use an incorrect dune and you are using the OCaml Language Server Protocol (in particular, Visual Studio Code with the OCaml Platform plugin), you may get the following error:

    The current Merlin configuration has been generated by another, incompatible, version of Dune. Please rebuild the project. (Using the same version of Dune as the one running the ocaml-merlin server.)

CMAKE_OCamlDune_COMPILER_EXTERNAL_REQUIRED=ON

The implications when CMAKE_OCamlDune_COMPILER_EXTERNAL_REQUIRED is ON are:

  • The initial build of the project should take only a few minutes

  • You can use the external OCaml build tool dune from the command line

  • The external OCaml compiler likely will not have debug symbols; debugging OCaml generated assembly or debugging OCaml C runtime code will be difficult

  • You must specify the CMake variables that are labeled as Required in the sections below

CMAKE_OCamlDune_OCAML_HOME (Required)

The full path to an OCaml installation tree that has a bin/ocaml that runs on the host ABI, and a lib/ocaml OCaml standard library directory.

Note

CMAKE_OCamlDune_OCAML_HOME for DkML

You do not need to specify CMAKE_OCamlDune_OCAML_HOME if you have installed DkML. DkML has a dkmlvars.cmake script in a standard location; that contains a DiskuvOCamlHome variable which becomes the CMAKE_OCamlDune_OCAML_HOME value.

CMAKE_OCamlDune_TARGET_ABI (Required)

The ABI of the target platform where you want to run your built executables.

The target ABI becomes the DKML_TARGET_ABI variable. See DKML_TARGET_ABI for the list of supported target ABIs.

For example, if you want to build executables and libraries that run on 32-bit ARM32 Android, your target ABI would be android_arm32v7a. Because of the constraints explained in the In Depth - OCaml Compiler guide, your host ABI would have to be linux_x86 and your build machine would have to be Linux (or WSL2 on Windows).

DkSDK cross-compilation is explained in the In Depth - OCaml Compiler guide.

Note

CMAKE_OCamlDune_TARGET_ABI for DkML

You should not need to specify CMAKE_OCamlDune_TARGET_ABI if you have installed DkML. DkSDK will detect if DkML:

  • has a single cross-compiler, the DkML cross-compiler's ABI will become the target ABI

  • has no cross-compilers, the target ABI will be the host ABI

  • has more than one cross-compiler, then you will need to specify CMAKE_OCamlDune_TARGET_ABI to resolve the ambiguity

CMAKE_OCamlDune_HOST_ABI

The ABI of executables that can run on the build machine.

The build machine is the machine that runs the cmake -G configuration command and the cmake build command.

The host ABI becomes the DKML_HOST_ABI variable. See DKML_HOST_ABI for the list of supported host ABIs.

Note

CMAKE_OCamlDune_HOST_ABI for DkML

You will not need to specify CMAKE_OCamlDune_HOST_ABI if you have installed DkML. DkSDK will inspect the ${CMAKE_OCamlDune_OCAML_HOME}/bin/ocamlopt.opt compiler to discover the host ABI.

By default the host ABI is automatically detected using DkSDKInspectHost_DetectHostABI(), which is sometime inaccurate. There are two situations where you will want to specify the host ABI explicitly:

  1. If you want to produce 32-bit binaries on a 64-bit Windows or Linux machine, you should select the 32-bit variant of the host ABI (either windows_x86 or linux_x86). Since Apple Silicon does not support 32-bit modes, 32-bit support is not provided for Apple.

  2. On macOS, Rosetta emulation makes detection difficult and ambiguous. If you have an Apple Silicon chip and Rosetta emulation, you can choose your host ABI to be either darwin_x86_64 or darwin_arm64.

CMAKE_OCamlDune_COMPILER (Required)

The full path to ocamlopt.opt (or ocamlopt.opt.exe on Windows) for the target ABI.

Note

CMAKE_OCamlDune_COMPILER for DkML

You do not need to specify CMAKE_OCamlDune_COMPILER if you have installed DkML. DkSDK will calculate a default using the computed or specified values of CMAKE_OCamlDune_OCAML_MLCROSS_DIR, CMAKE_OCamlDune_TARGET_ABI and CMAKE_OCamlDune_TARGET_IS_COMPATIBLE_HOST_ABI.

CMAKE_OCamlDune_TARGET_IS_COMPATIBLE_HOST_ABI

A CMake option that defaults to OFF. When it is ON, any target ABI executables are expected to run on the host ABI.

More simply, ON means that no cross-compilation is needed.

When it is OFF (so DkSDK cross-compilation is needed), other variables must be defined:

DkSDK cross-compilation is explained in the In Depth - OCaml Compiler guide.

Note

CMAKE_OCamlDune_TARGET_IS_COMPATIBLE_HOST_ABI for DkML

You do not need to specify CMAKE_OCamlDune_TARGET_IS_COMPATIBLE_HOST_ABI if you have installed DkML. DkSDK will compute the default using the cross-compiling compatibility rules explained in the In Depth - OCaml Compiler guide.

CMAKE_OCamlDune_COMPILER_HOST

The full path to ocamlopt.opt (or ocamlopt.opt.exe on Windows) for the host ABI.

Note

CMAKE_OCamlDune_COMPILER_HOST for DkML

You do not need to specify CMAKE_OCamlDune_COMPILER_HOST if you have installed DkML. DkSDK will use the default value of ${CMAKE_OCamlDune_OCAML_HOME}/bin/ocamlopt.opt or ${CMAKE_OCamlDune_OCAML_HOME}/usr/bin/ocamlopt.opt, whichever exists.

Defaults to the value of CMAKE_OCamlDune_COMPILER. That default value is incorrect when cross-compiling. So this CMake variable is required if the host and target ABIs are not compatible with each other. That is, when CMAKE_OCamlDune_TARGET_IS_COMPATIBLE_HOST_ABI is OFF or not specified, you should define this CMake variable.

CMAKE_OCamlDune_OCAML_MLCROSS_DIR

The full path to the parent directory of zero or more OCaml installation trees.

Example directory structure:

<CMAKE_OCamlDune_OCAML_MLCROSS_DIR>
├── darwin_x86_64
│   ├── bin
│   │   ├── ...
│   │   └── ocamlopt.opt
└── android_x86_64
    └── bin
        ├── ...
        └── ocamlopt.opt

Each subdirectory of CMAKE_OCamlDune_OCAML_MLCROSS_DIR is a target ABI.

Each target ABI has a bin/ocamlopt.opt that:

  • runs on the host ABI, but

  • produces executables for the target ABI

Note

CMAKE_OCamlDune_OCAML_MLCROSS_DIR for DkML

You do not need to specify CMAKE_OCamlDune_OCAML_MLCROSS_DIR if you have installed DkML. DkSDK will use the default value of ${CMAKE_OCamlDune_OCAML_HOME}/opt/mlcross

This CMake variable is required if and only if the host and target ABIs are not compatible with each other. That is, when CMAKE_OCamlDune_TARGET_IS_COMPATIBLE_HOST_ABI is OFF or not specified, you must define this CMake variable.

DkSDK cross-compilation is explained in the In Depth - OCaml Compiler guide.

CMAKE_DUNE

The full path to the dune (or dune.exe) executable.

If the executable is not set, it will be built using the external OCaml compiler.

CMAKE_OCAMLFIND

The full path to the ocamlfind (or ocamlfind.exe) executable.

If the executable is not set, it and a findlib.conf will be built using the external OCaml compiler. The newly created findlib installation will tell its users (ex. Dune) through the findlib.conf configuration to write in a DkSDK destination path so the external OCaml home is untouched.

DKSDK_MSYS2_DIR

The full path to a MSYS2 installation. It is described in DKSDK_MSYS2_DIR.

This CMake variable is only used on Windows.

Note

DKSDK_MSYS2_DIR for DkML

You do not need to specify DKSDK_MSYS2_DIR if you have installed DkML. DkML has a dkmlvars.cmake script in a standard location; that contains a DiskuvOCamlMSYS2Dir variable which becomes the DKSDK_MSYS2_DIR value.