Add a doc entry for setting up an OxCaml project with dune pkg #12780

Sudha247 · 2025-11-24T11:48:50Z

Adds a tutorial for setting up an OxCaml project with Dune package management.

I contemplated where this should go, and thought this might be a good place, after all. It shows (1) how to setup an OxCaml project, (2) servers as a live example of the previous two tutorials.

#12111 is a more comprehensive tutorial about parametric libraries and OxCaml, but it doesn't specifically cover the topic of Dune package management with OxCaml. I recently ported an OxCaml project to build with Dune package management and the configuration was not as straightforward as I expected, and thought a tutorial on this topic might be useful.

This takes some material from https://github.com/gridbugs/hello-oxcaml (thanks @gridbugs!).

doc/tutorials/dune-package-management/oxcaml.md

Alizter · 2025-11-24T12:00:21Z

Here are some screenshots:

I think having these drop-down code excerpts is kind of pointless. Perhaps it would be better just to have the code inline like we do elsewhere in the docs.

Alizter · 2025-11-24T12:01:12Z

The main title doesn't need to say Example: probably.

shonfeder

Glad to have this included!

doc/tutorials/dune-package-management/oxcaml.md

doc/tutorials/dune-package-management/oxcaml/dune

doc/tutorials/dune-package-management/oxcaml/main.ml

doc/tutorials/dune-package-management/oxcaml.md

Alizter · 2025-11-26T10:08:22Z

At some point these how-to's turned into markdown rather than being rst documents which is slightly confusing. In rst we have syntax highlighting for dune files etc. Does anybody remember why markdown was chosen for these?

I would suggest writing this tutorial in rst, not only for consistency, but because it will play better with cross-linking that we have elsewhere in the docs.

Signed-off-by: Sudha Parimala <[email protected]>

Sudha247 · 2025-11-26T17:08:51Z

I would suggest writing this tutorial in rst, not only for consistency, but because it will play better with cross-linking that we have elsewhere in the docs.

I'm not opposed to doing this, but wouldn't be weird if only one of the dune-package-management entries is in rst, while others are in markdown?

Alizter · 2025-11-26T17:46:16Z

Ideally they should be all in rst, but would blow this PR out of scope. If you think it would be too much work to do in this PR, let's instead create an issue so that we remember to do it eventually. I won't block on this point.

Leonidas-from-XIV · 2025-11-26T18:25:29Z

Ah, I dug a bit around and it is because of this PR by @emillon where he notes:

it maps fully to reST

it's more contributor friendly

editor tooling is better

it alleviates some vendor lock-in (since we're likely to migrate to ocaml.org at some point, and it's more likely to use a variant of md than sphinx support odoc syntax)

Which all sound like pretty decent points.

Alizter · 2025-11-27T09:29:36Z

doc/tutorials/dune-package-management/oxcaml.md

+
+As an example of how to add custom repositories and pin dependencies in projects
+using Dune Package Management, let's look at setting up a basic OxCaml project.
+[OxCaml](https://oxcaml.org/) is a compiler branch with fast moving set of


I would put the link on the mention of OxCaml just before.

Alizter · 2025-11-27T09:31:20Z

doc/tutorials/dune-package-management/oxcaml.md

+## Setting up the `dune-workspace`
+
+OxCaml has a custom `opam-repository` that provides compatible dependencies.
+This is specified in the `dune-workspace`.


This sounds like the opam repository is configured in dune-workspace. I would probably say something like: Dune can use packages from this repositories by configuring it in the dune-workspace file using the repository (link) and lock_dir (link) stanzas.

Alizter · 2025-11-27T09:31:30Z

doc/tutorials/dune-package-management/oxcaml.md

+This is specified in the `dune-workspace`.
+
+```{code-block} dune
+(lang dune 3.20)


Let's make this 3.21

Alizter · 2025-11-27T09:32:49Z

doc/tutorials/dune-package-management/oxcaml.md

+In the `dune-project`, we also need to add a constraint to depend on the OxCaml
+compiler. Otherwise, the solver may pick up the latest upstream compiler, which
+does not support the OxCaml extensions.


"We would like dune to pick the oxcaml compiler rather than the latest upstream one. This can be achieved by manually adding a constraint on the compiler that is picked in the package stanza (link) in the dune-project.

Alizter · 2025-11-27T09:34:47Z

doc/tutorials/dune-package-management/oxcaml.md

+
+## Building the project
+
+As usual, let's build the project with:


Let's not assume users are used to the usual way of doing things here. Let's instead say, we can now build and execute our binary compiled with OxCaml. We use the dune exec command which will first build all the packages we need, including the OxCaml compiler and then builds our binary and runs it.

You should probably mention the passage of time here, since this step takes a while and dune atm doesn't give too much feedback.

Agreed. Unfortunately at the moment the compilation of OxCaml is glacial, partly because of limited concurrency but possibly also due to flambda being enabled. The former we can fix with #12737, the latter is outside of our control.

Alizter · 2025-11-27T09:35:37Z

doc/tutorials/dune-package-management/oxcaml.md

+
+```{code-block} dune
+
+(lang dune 3.20)


Alizter · 2025-11-27T09:36:52Z

doc/tutorials/dune-package-management/oxcaml.md

+tools in the `dune-workspace` if you intend to use them for your development
+workflows.
+
+For `ocamlformat` it would look something like this:


Maybe we should add a warning that this configuration is likely to change in the future as our method for achieving this settles. Especially once the patches themselves are upstreamed. I think some prose explaining and linking the stanzas would also be a good idea.

I think it would be nice to document configuring dev-tools in general as part of #12756, then the resulting document could be linked here.

Leonidas-from-XIV · 2025-11-24T14:04:50Z

doc/tutorials/dune-package-management/oxcaml.md

+As an example to adding custom repositories and pinning projects, let's look at
+setting up a basic OxCaml project. [OxCaml](https://oxcaml.org/) is a compiler
+branch with fast moving set of extenstions to OCaml. Some tweaks are required to
+set up an OxCaml project with dune package management.


Suggested change

set up an OxCaml project with dune package management.

set up an OxCaml project with Dune package management.

Leonidas-from-XIV · 2025-11-24T14:05:13Z

doc/tutorials/dune-package-management/oxcaml.md

+
+As an example to adding custom repositories and pinning projects, let's look at
+setting up a basic OxCaml project. [OxCaml](https://oxcaml.org/) is a compiler
+branch with fast moving set of extenstions to OCaml. Some tweaks are required to


Suggested change

branch with fast moving set of extenstions to OCaml. Some tweaks are required to

branch with fast moving set of extensions to OCaml. Some tweaks are required to

Leonidas-from-XIV · 2025-11-27T11:25:29Z

doc/tutorials/dune-package-management/oxcaml.md

+tools in the `dune-workspace` if you intend to use them for your development
+workflows.
+
+For `ocamlformat` it would look something like this:


I think it would be nice to document configuring dev-tools in general as part of #12756, then the resulting document could be linked here.

Leonidas-from-XIV · 2025-11-27T11:26:52Z

doc/tutorials/dune-package-management/oxcaml.md

+using Dune Package Management, let's look at setting up a basic OxCaml project.
+[OxCaml](https://oxcaml.org/) is a compiler branch with fast moving set of
+extensions to OCaml. Some tweaks are required to set up a project that compiles
+with OxCaml when using dune package management.


Nitpick but we should be consistent about how we capitalize Dune (and Dune package management).

Leonidas-from-XIV · 2025-11-27T11:31:03Z

doc/tutorials/dune-package-management/oxcaml.md

+
+## Building the project
+
+As usual, let's build the project with:


Agreed. Unfortunately at the moment the compilation of OxCaml is glacial, partly because of limited concurrency but possibly also due to flambda being enabled. The former we can fix with #12737, the latter is outside of our control.

Leonidas-from-XIV · 2025-11-27T11:31:52Z

doc/tutorials/dune-package-management/oxcaml.md

+   (version 3.1.0+ox)))
+
+(lock_dir
+ (path "dune.lock")


This path is probably optional.

Leonidas-from-XIV · 2025-11-27T11:33:20Z

doc/tutorials/dune-package-management/oxcaml.md

+ (repositories :standard oxcaml))
+
+(lock_dir
+ (path "dev-tools.locks/ocamlformat")


This path needs to be adjusted now that #12671 is merged, it should be "_build/.dev-tools.locks/ocamlformat"

Leonidas-from-XIV · 2025-11-27T11:34:00Z

doc/tutorials/dune-package-management/oxcaml/main.ml

+  let local_ i = 42 in
+  let j = i + 1 in
+  print_endline (Printf.sprintf "%d" j)
+


Some newline issue here.

Leonidas-from-XIV · 2025-11-27T11:34:45Z

doc/tutorials/dune-package-management/oxcaml/main.ml

+  (* The `local_` keyword requires OxCaml *)
+  let local_ i = 42 in
+  let j = i + 1 in
+  print_endline (Printf.sprintf "%d" j)


Suggested change

print_endline (Printf.sprintf "%d" j)

Printf.printf "%d\n" j

Alizter · 2025-11-27T17:02:19Z

We also have a macros for the latest dune lang version which might be sensible to use.

Sudha247 requested review from Alizter and shonfeder November 24, 2025 11:49

Alizter reviewed Nov 24, 2025

View reviewed changes

doc/tutorials/dune-package-management/oxcaml.md Outdated Show resolved Hide resolved

shonfeder approved these changes Nov 25, 2025

View reviewed changes

Sudha247 force-pushed the hello-oxcaml branch 2 times, most recently from 65b4bc6 to 64d39ec Compare November 25, 2025 14:48

Sudha247 commented Nov 25, 2025

View reviewed changes

doc/tutorials/dune-package-management/oxcaml.md Show resolved Hide resolved

gridbugs reviewed Nov 26, 2025

View reviewed changes

doc/tutorials/dune-package-management/oxcaml.md Outdated Show resolved Hide resolved

Sudha247 added 2 commits November 26, 2025 18:04

Add a doc entry for setting up an OxCaml project with dune pkg

010f449

Signed-off-by: Sudha Parimala <[email protected]>

Address review comments

68a550d

Signed-off-by: Sudha Parimala <[email protected]>

Sudha247 force-pushed the hello-oxcaml branch from 64d39ec to 135bb8e Compare November 26, 2025 17:05

refer to Dune Package Management

9f8c4b7

Signed-off-by: Sudha Parimala <[email protected]>

Sudha247 force-pushed the hello-oxcaml branch from 135bb8e to 9f8c4b7 Compare November 26, 2025 17:06

Sudha247 requested a review from Alizter November 27, 2025 09:25

Alizter reviewed Nov 27, 2025

View reviewed changes

doc/tutorials/dune-package-management/oxcaml.md

```{code-block} dune

(lang dune 3.20)

Copy link

Collaborator

Alizter Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lang 3.21

Alizter reviewed Nov 27, 2025

View reviewed changes

Leonidas-from-XIV reviewed Nov 27, 2025

View reviewed changes


		## Building the project

		As usual, let's build the project with:

	set up an OxCaml project with dune package management.
	set up an OxCaml project with Dune package management.

	branch with fast moving set of extenstions to OCaml. Some tweaks are required to
	branch with fast moving set of extensions to OCaml. Some tweaks are required to

Add a doc entry for setting up an OxCaml project with dune pkg #12780

Are you sure you want to change the base?

Add a doc entry for setting up an OxCaml project with dune pkg #12780

Conversation

Sudha247 commented Nov 24, 2025 • edited by shonfeder Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Alizter commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Alizter commented Nov 24, 2025

Uh oh!

shonfeder left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Alizter commented Nov 26, 2025

Uh oh!

Sudha247 commented Nov 26, 2025

Uh oh!

Alizter commented Nov 26, 2025

Uh oh!

Leonidas-from-XIV commented Nov 26, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Leonidas-from-XIV Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Alizter commented Nov 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Sudha247 commented Nov 24, 2025 •

edited by shonfeder

Loading

Alizter commented Nov 24, 2025 •

edited

Loading

Leonidas-from-XIV Nov 27, 2025 •

edited

Loading