Name

dk - Launch tools that run or access `dk` coder scripts.

Synopsis

dk [OPTION]… ENTRY_MODULE_ID [ARG]…

dk [OPTION]… SCRIPT_MODULE_FILE [ARG]…

dk [OPTION]… TOOL_MODULE_ID [ENTRY_MODULE_ID] [ARG]…

dk [OPTION]… gc [ARG]…

The first two forms above use the `StdStd_Std.Run` tool to run the ENTRY_MODULE_ID or SCRIPT_MODULE_FILE.

The third form explicitly selects the TOOL_MODULE_ID, which embeds both which tool is to be used and which version of the tool. The TOOL_MODULE_ID has the format `StdStd_<toolversion>.<toolname>`. The tools are documented in the TOOLS section.

The fourth form `dk gc [ARG]…` does garbage collection in cache and data directories. See `dk gc --help` for more details.

Tools

A tool is code that, given an analysis of a script module or a project, performs an action on that script module or that project. The default tool is `StdStd_Std.Run` which runs a script module.

You must use the `dk [OPTION]… TOOL_MODULE_ID [ENTRY_MODULE_ID] [ARG]…` command line form to change the tool. For example:

 dk StdStd_Std.Run YouLibrary_Std.RunMe

 dk StdStd_Std.REPL YouLibrary_Std.RunMe

 dk StdStd_Std.Exe YouLibrary_Std.RunMe

 dk StdStd_Std.SBOM

are all ways to run different tools on the same script module (`YouLibrary_Std.RunMe`) or on the entire project.

See the TOOL VERSIONING section for how to select a specific version of a tool.

`StdStd_Std.Run` is the fully-qualified module id for the tool which has a short alias `Run` to save typing. So the following are equivalent:

 dk StdStd_Std.Run YouLibrary_Std.RunMe

 dk Run YouLibrary_Std.RunMe

The other official tools all have short aliases as well, and are documented below.

Tool versioning

The version of the tool is embedded in the TOOL_MODULE_ID when you run `dk [OPTION]… TOOL_MODULE_ID [ENTRY_MODULE_ID] [ARG]…`. Using an older or explicit version means that you can migrate your project and its script modules on your timeline (subject to the version's end-of-life policies).

The TOOL_MODULE_ID format is `StdStd_<toolversion>.<toolname>` where <toolversion> is either:

Aliases

Often a module with `Std` in its module id has a short form (an alias) that can be typed on the command line. That is why the tool `StdStd_Std.Run` can be typed as `Run`.

The rules are that all of the `Std` parts of the library id may be omitted if the `Std` are present consecutively on the right-hand side of the library id. That is quite wordy so let's see some examples:

 ALIAS FULLY QUALIFIED ID

 ----- ------------------

 Run StdStd_Std.Run

 Our.ReadMe OurStd_Std.ReadMe

 OurTests.Suite OurTests_Std.Suite

 Ml.Init MlStd_Std.Init

Aliases can only be used if the `Std` are on the right hand side of the library. With `StdStd_Env.Run`, for example, the right-hand side of the library id is `Env` not `Std`, so there is no alias for `StdStd_Env.Run`.

Adhoc modules

These options are only used with the Run, Exe, Embed and REPL tools described in the TOOLS section.

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.

Build mode

These options are only used with the Exe tool described in the TOOLS section.

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

These options are only used with the Run, Exe, Embed and REPL tools described in the TOOLS section.

Generators

These options are only used with the Run, Exe, Embed and REPL tools described in the TOOLS section.

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.

Response files

Data home directory

The data home directory is the directory containing DkCoder-specific data files. It can be specified by the `--data-home DIR` option but will use a default from the rule list below, highest precedence to lowest precedence:

Options

Common options

Advanced options

Exit status

dk exits with:

Environment

These environment variables affect the execution of dk:

Bugs

Check feature requests and bugs at https://github.com/diskuv/dk/issues

See also

https://diskuv.com/dk/help/latest/