Command Reference

with-dkml.exe

Summary

Runs a specified command with an appropriate environment for a Microsoft/Apple/GNU compiler that includes headers and libraries of optionally vcpkg and optionally third-party C packages.

The environment variable DKML_3P_PREFIX_PATH can be set to a semicolon separated list of third-party directories, and any bin, include, lib and lib/pkgconfig subdirectories will be added to various compiler environment variables (more details below).

The environment variable DKML_3P_PROGRAM_PATH can be set to a semicolon separated list of third-party directories, and any directory in it will be added to the PATH.

An SDK Project automatically sets DKML_3P_PREFIX_PATH and DKML_3P_PROGRAM_PATH to the CMAKE_PREFIX_PATH and CMAKE_PROGRAM_PATH variables, respectively.

Usage
# Execute: CMD ARGS
with-dkml CMD ARGS
Examples
# Enter a Bash session
with-dkml CMD ARGS

# Run Opam
with-dkml opam
Configuration File dkmlvars-v2.sexp

This file must exist in one of the following directories:

  1. $LOCALAPPDATA/Programs/DiskuvOCaml/

  2. $XDG_DATA_HOME/diskuv-ocaml/

  3. $HOME/.local/share/diskuv-ocaml/

The directories are checked in order, and the first directory that contains dkmlvars-v2.sexp is used.

The value will have been set automatically by the Windows Diskuv OCaml installer or by makeit init-dev of SDK Projects for non-Windows OSes.

Configuration File vsstudio.dir.txt

This file is located using the same directory search as dkmlvars-v2.sexp. It only needs to be present when Visual Studio has been detected, and is set automatically by the Windows Diskuv OCaml installer.

The value is the location of the Visual Studio installation. Example: C:\DiskuvOCaml\BuildTools

Configuration File vsstudio.msvs_preference.txt

This file is located using the same directory search as dkmlvars-v2.sexp. It only needs to be present when Visual Studio has been detected, and is set automatically by the Windows Diskuv OCaml installer.

The value is the MSVS_PREFERENCE environment variable that must be set to locate the Visual Studio installation when https://github.com/metastack/msvs-tools’s or Opam’s msvs-detect is invoked. Example: VS16.6

Configuration File vsstudio.cmake_generator.txt

This file is located using the same directory search as dkmlvars-v2.sexp. It only needs to be present when Visual Studio has been detected, and is set automatically by the Windows Diskuv OCaml installer.

The value is a recommendation for which CMake Generator to use when setting up a CMake project initially.

Arguments CMD ARGS

The name of the command to run, and any optional arguments. The command does not need to an absolute path if it already part of the existing PATH or part of the modified PATH.

Note

On Windows the command may come from MSYS2. For example, bash is a valid command.

Sequence of operations

  1. The environment variable DKML_TARGET_ABI will be detected through compiler probing and set to one of:

    • android_arm64v8a

    • android_arm32v7a

    • android_x86

    • android_x86_64

    • darwin_arm64

    • darwin_x86_64

    • linux_arm64

    • linux_arm32v6

    • linux_arm32v7

    • linux_x86_64

    • windows_x86_64

    • windows_x86

    • windows_arm64

    • windows_arm32

    The compiler probing is done when with-dkml is compiled. During Diskuv OCaml installation on Windows a with-dkml will be placed on the PATH; that will use the Visual Studio compiler detected at installation time.

    Note

    An SDK Project supports cross-compilation and can have many with-dkml binaries. Any ./makeit *-<platform>-<buildtype> target like ./makeit build-windows_x86-Debug or ./makeit build-dev will first call a ./makeit init-<platform> target; that will compile a with-dkml binary using a compiler specific to the given <platform>. That means that DKML_TARGET_ABI will be <platform>, except DKML_TARGET_ABI will be the results of probing the system compiler if <platform> = "dev".

    Warning

    Only windows_x86_64, darwin_arm64 and darwin_x86_64 are supported today.

  2. If and only if the configuration file vsstudio.msvs_preference.txt exists then the MSVS_PREFERENCE environment variable will be set to its value

  3. If and only if the configuration file vsstudio.cmake_generator.txt exists then the CMAKE_GENERATOR_RECOMMENDED environment variable will be set to its value

  4. If and only if the configuration file vsstudio.dir.txt exists then the CMAKE_GENERATOR_INSTANCE_RECOMMENDED environment variable will be set to its value

  5. The existing environment variable PATH is:

    • (MSYS2) Stripped of all path entries that end with \MSYS2\usr\bin. For example, if the existing PATH is

      C:\Program Files\Miniconda3\Scripts;C:\MSYS2\usr\bin;C:\WINDOWS\system32;C:\WINDOWS

      the stripped PATH will be

      C:\Program Files\Miniconda3\Scripts;C:\WINDOWS\system32;C:\WINDOWS

    • (MSVC) Stripped of all path entries that end with \Common7\IDE or \Common7\Tools or \MSBuild\Current\Bin

    • (MSVC) Stripped of all path entries that contain \VC\Tools\MSVC\, \Windows Kits\10\bin\, \Microsoft.NET\Framework64\ or \MSBuild\Current\bin\

  6. If and only if there is a DiskuvOCamlMSYS2Dir configuration value in dkmlvars-v2.sexp, the VsDevCmd.bat Microsoft batch script is run. The following environment variables are captured and passed to the CMD ARGS:

    • PATH

    • DevEnvDir

    • ExtensionSdkDir

    • Framework40Version

    • FrameworkDir

    • Framework64

    • FrameworkVersion

    • FrameworkVersion64

    • INCLUDE

    • LIB

    • LIBPATH

    • UCRTVersion

    • UniversalCRTSdkDir

    • VCIDEInstallDir

    • VCINSTALLDIR

    • VCToolsInstallDir

    • VCToolsRedistDir

    • VCToolsVersion

    • VisualStudioVersion

    • VS140COMNTOOLS

    • VS150COMNTOOLS

    • VS160COMNTOOLS

    • VSINSTALLDIR

    • WindowsLibPath

    • WindowsSdkBinPath

    • WindowsSdkDir

    • WindowsSDKLibVersion

    • WindowsSdkVerBinPath

    • WindowsSDKVersion

  7. The PATH is stripped of all directories in the semicolon separated environment variable DKML_3P_PROGRAM_PATH. For example, on Windows if the existing PATH is

    C:\Project\tools\local\bin;C:\Temp\share;C:\WINDOWS\system32;C:\WINDOWS

    and the environment variable DKML_3P_PROGRAM_PATH is C:\Project\tools\local;C:\Temp\share, the stripped PATH will be

    C:\Project\tools\local\bin;C:\WINDOWS\system32;C:\WINDOWS

  8. Each directory in DKML_3P_PROGRAM_PATH is added to the PATH environment variable

  9. The following environment variables:

    • INCLUDE

    • CPATH

    • COMPILER_PATH

    • LIB

    • LIBRARY_PATH

    • PKG_CONFIG_PATH

    • PATH

    are:

    1. Stripped of all directories in the semicolon separated environment variable DKML_3P_PREFIX_PATH or any of its subdirectories. For example, on Windows if the existing INCLUDE is

      C:\Project\tools\local\include;C:\Temp\share;C:\WINDOWS\system32;C:\WINDOWS

      and the environment variable DKML_3P_PREFIX_PATH is C:\Project\tools\local;C:\Temp\share, the stripped INCLUDE will be

      C:\WINDOWS\system32;C:\WINDOWS

    2. For each directory $DIR in DKML_3P_PREFIX_PATH: