Name

dk-Exe - Produces target-specific executables.

Synopsis

dk Exe [OPTION]… (1) TOOL_MODULE_ID [(2) SCRIPT_MODULE_ID] [(3) SCRIPT_MODULE_ARGS]…

Compiler arguments

Exe generates build files, then uses those build files to produce OCaml bytecode, and then uses the bytecode to produce target-specific executables.

Lifecycle when executable runs

The sequence is:

1. The entry module you specify on the `dk` command line is analyzed and all of its transitive dependent modules are located. The entry and transitive modules are compiled into a bytecode executable (just like a standard Run), except the [at_exit] handlers are not called at the end of the module initialization.

2. After module initialization, the OCaml runtime is shut down. As the runtime is shut down, the [at_exit] handlers will be called.

Options

Adhoc modules

The contents of a script module can be specified on the command line instead of pre-existing on the filesystem. These options are `--struct` (`-S`), `--struct-url` (`-s`), `--expr-unit` (`-U`) and `--expr-unit-url` (`-u`). Each of these options is transformed and then concatenated into a single "adhoc" script module.

Your adhoc script module is treated just like any other `You` module. In particular, your adhoc script module has access to all your project code and to external `Us` and `Them` libraries.

The main use-case is to quickly try out expressions and code without having to go to a text editor or IDE. In particular, a user should be able to copy-and-paste a multi-line `dk Run -S "..."` command line from an intranet/Internet site, and have it behave identically regardless of how their browser handles tabs and newlines.

If you are posting a multi-line `dk Run -S "..."` command line, follow the format below to make it work in both PowerShell and a standard Unix shell. The format relies enclosing each `-S` and `-E` option with a double quote; most shells allow double quotes across multiple lines.

dk -S "
(* the contents of a struct without any double quotes *)
let print_endline = Tr1Stdlib_V414Io.StdIo.print_endline
" -U "
(* the expression without any double quotes or exclamation points.
Use {|...|} for strings. *)
print_endline {|okay line 1|};
print_endline {|okay line 2|}
" Run

Adhoc module sequencing

The sequence of steps to create the adhoc module is as follows:

The adhoc script module starts out empty.

1. Gather all the `--struct` (`-S`) from left to right as they appear on the command line, and then gather the `--struct-url` (`-s`). Each `--struct-url` (`-s`) is fetched if the execution policy allows it, but otherwise the contents of the fetched `--struct-url` are treated identically to a `--struct`.

2. Each `--struct`, and the content of each fetched `--struct-url`, are formatted with the ocamlformat code formatter for copy-and-paste resiliency, and then added to the adhoc module.

3. Gather all the `--expr-unit` (`-U`) from left to right as they appear on the command line, and then gather the `--expr-unit-url` (`-u`). Each `--expr-unit-url` (`-e`) is fetched if the execution policy allows it, but otherwise the contents of the fetched `--expr-unit-url` are treated identically to a `--expr-unit`.

4. Each `--expr-unit`, and the content of each fetched `--expr-unit-url`, are converted to `let __init (context: DkCoder_Std.Context.t) = (* the expression *); __init context` statements, then formatted with the ocamlformat code formatter, and then added to the adhoc module.

5. The adhoc module is saved into a cache directory as `ZzZz_Zz/Adhoc.ml`. The cache directory is keyed by the contents of the adhoc module. Because the contents were processed with a code formatter, the cache contents should be identical across different users even if copy-and-pasted from an intranet/Internet forum.

Configuration

Configuration files for DkCoder are not automatically created; the default configuration should be sufficient for typical situations. If you would like to customize DkCoder, you can create or edit the `policy.scfg` configuration file in one of two places

The schema is as follows:

dk.exe {
  cache {
    # Any @USER@ tokens will be replaced by the username (currently `root`).
    dir 'C:cache@USER@'
  }
  data {
    # Any @USER@ tokens will be replaced by the username (currently `root`).
    dir 'C:data@USER@'
  }
}

The scfg format of the configuration file is available at https://git.sr.ht/~emersion/scfg

Build mode

DkCoder's build mode (`-O` or `--optimize`) controls how fast and how big the generated executables are.

The DkCoder build mode was influenced by Zig's build mode. However, unlike Zig, DkCoder has no modes that reduce safety checks.

Compiler options

The dk executable will supply these options to the Exe tool.

Generators

There are a couple generators that can be selected with the --generator option.

Generator: dune

This generator creates build files for the Dune build tool. All of those files are generated inside the generator build directory. This is the generator is to use for the highest reproducibility and for publishing (tweaks will be needed) to an opam repository. It is also the generator that is the most similar to an upcoming native-code generator.

Generator: dune-ide

This generator creates build files for the Dune build tool, configured to work with Merlin-based IDEs like Visual Studio Code with the OCaml Platform plugin. The generator:

- places the Dune project file `.z-dk-dune-project` inside the project tree (you should add it to `.gitignore`)

- places the Merlin configuration `.merlin` inside the project tree (you should add it to `.gitignore`)

- places `dune-file` files in `#s` inside the project tree (you should add `#s` to `.gitignore`)

- uses the conventional `_build/` subfolder for Dune compilation (you should add it to `.gitignore`)

- does not generate `.opam` files (to not pollute the project tree)

- does not generate a `.dkcodermeta` metadata file (to not pollute the project tree)

You directories

The --you-dir option, which can be repeated, takes precedence for specifying the You directories.

The project's `dkproject.jsonc`, if it is present, can contain a `{sources: you: [...]}` JSON array. The directories in the array, if non-empty, will be the You directories if the --you-dir option was not specified.

The default You directory is the project directory's `src/` folder when all other search paths are empty.

Regardless of the You search path, if you specified a script as an absolute path (ex. `./dk test/Xy_Std/Hi.ml`) then the parent directory of the library (ex. `Xy_Std`) is added as the first You directory. In the example, the `test/` directory would be the first You directory.

Common options

Debugging options

Advanced options

Exit status

dk Exe exits with:

Environment

These environment variables affect the execution of Exe:

See also

dk(1)