As dune non-literate I did a review of the introductory chapters of the dune manual (version June 22nd 2022).

FYI: @ejgallego @rgrinberg

Summary: the documentation is quite good, but especially new comers might have difficulties understanding basic concepts reading the introductory chapters.

Please find my notes below (following the section structure of the manual).

Overview

Introduction

• Cross-platform: it says that this is not yet supported, but there is (https://dune.readthedocs.io/en/stable/cross-compilation.html)

• Release directly from any revision It is unclear to me what this means Maybe "supplies a dedicated tool to quickly create opam release pull requests"

Terminology

• it is not so clear what the relation of project and root is. Since there are already packages, a project is multiple packages. What is root then? Multiple projects? Why would one want this? And then we have workspace as well ...

• I would probably swap workspace and root and introduce root as the root path of the workspace. This might be less confusing.

• scopes incomprehensible for new comers (those this section is for)

• build contex I am not sure it is helpful to say that a build context is a folder. I would think it is mostly a configurartion stored in dune-workspace which has a corresponding folder under _build. The folder is then the build context root.

• alias: before discussing specific build targets, it might make sense to inroduce build targets and their relation to packages.

• environment: it is unclear how this relates to build contexts. One would think that compiler flags are specified in a build context. So what is the difference between environment an dbuild context and/or what is the use of the two?

• build profile: OK, now I have build contexts, build profiles and environments, apparently all of which do the same thing.

Quickstart

• since the examples folder is referenced immedaiely, it might make sense to put some comments in the example dune files. It is e.g. not so obvious what "cram" means in (https://github.com/ocaml/dune/blob/main/example/dune).

• the layout of the examples folder is opposite to what is mentioned in (https://dune.readthedocs.io/en/stable/overview.html#project-layout): it has a dune file at the root and then dune-project files in the sub folders. This is mildly confusing.

Initializing an Executable

• on the generated opam file: the "-j" jobs might not be what the opam developers had in mind - this way the number of jobs used is quadratic with jobs.

• on the bin folder description: probably clear to every OCaml user, but auto capitalization of module names is implied here but not mentioned. Maybe where Project_name is replaced with the name of your project and Mod corresponds to the name of the file in the lib directory (both auto-capitalized)

• on the bin folder: it is not so obvious what one would do in the presence of multiple executables (which is advertised just before). Would they go all into the same bin folder or would one choose entirely different names then. If so is bin/lib a good name for the auto generated project? Or would one put several executables in the same dune file?

Initializing a Library

• If one does both the executable and the library demo one wonders if one can go up and use dune build there - one can't. This adds to the initial confusion on packages, projects, workspaces and root. It looks like dune init proj actually initializes a workspace and not a project (despite its name).

• One might want to leave a few words on static vs. shared libraries here.

Building a Hello World Program

• I find this section way confusing since the section two up does the same. Maybe this section should be names Building a minimal executable dune project from scratch. Also it is not so clear how this fits into the root/workspace/project thing. Simply create a new folder and that's it? No dune-project file?

• It is not clear if _build/default/hello_world.exe and dune exec ./hello_world.exe have any other differences besides that the second one also builds. Some recommendation which one should use would help, especially since the Initializing an Executable section only metnions the dune method.

• I would put the "troubleshooting" section under a separate headline and reference it from the above sections - people might have tried to build and failed there already.

• The trouble shooting section should handle people which don't have opam (last time I looked the recommended OCaml installation on Windows was without opam)

Building a Hello World Program Using Lwt

Fine!

Building a Hello World Program Using Core and Jane Street PPXs

Fine!

Defining a Library Using Lwt and ocaml-re

• Maybe replace , unless you write an explicit mylib.ml file. with . If you write an explicit mylib.ml file, only this file is accessible as MyLib - other modules are treated as private.

Building a Hello World Program in Bytecode

• I guess (modes byte exe) means that both a bytecode and a release executable can be built. It is not 100% obvious that .exe means release.

• It might make sense to show how to call ocamldebug from dune. Since the Initialize an executable section says one should use dune exec project_name to run the executable, the user expects one should do this and that one also needs dune to start ocaldebug.

Setting the OCaml Compilation Flags Globally

• it is not clear how the dev and release build profiles correspond to the byte and exe modes introduced in the previous section.

Using Cppo

• This is the first mention of the word stanza - maybe one should take this as opportunity to leave a few words on the basic syntax of dune files ans also show how the stanzas look after inserting this. Maybe it would make more sense to have a separate section on Basic dune file syntax (just before this one).

• It is not obvious if the rule thing is part of the previous stanza additions (all is needed) or an alternative was of doing things.

Defining a Library with C Stubs

• I guess this also compiles all ML modules in the same folder and that these contain the stubs then. This is a bit confusing because this one library stanza seems to build actually two librararies, a C library blah and an OCaml library mylib.

• It is not clear what happens with the -lblah option - is this passed to the linker when linking mylib or is this passed to the linker of projects using mylib?

Defining a Library with C Stubs using pkg-config

• I am not sure it makes sense to include this into a Quickstart section without some explanation what the various things do. At least the prupose of e.g. the config dune file should be mentioned.

Using a Custom Code Generator

• It is not clear how dune knows the extension of the input file from which the .ml file is generated, so that it can track the dependency.

• Users might be interested in the question if there is special support for e.g. menhir.

Defining Tests

Fine!

Building a Custom Toplevel

Fine!

Missing:

• Since this section goes into quite some details and variations, one could at least mention other langauges (Reason and Coq) and link the respective chapters, especially because this is metnioned in the Overview.

cc @christinerose

On it!