Update tutorial to use autolocking #12859

Leonidas-from-XIV · 2025-12-03T16:31:33Z

Updates to the tutorial to use autolocking (plus explain how to manually lock).

Leonidas-from-XIV · 2025-12-05T10:16:04Z

Unfortunately I had to remove a lot of output where the solution was displayed, because with autolocking the solution is not displayed anymore. I've opened #12865 to discuss how to improve the user experience in that case, giving a users a way to figure out which packages + versions were selected by the solver.

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

shonfeder · 2025-12-05T17:41:40Z

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

+packages are published in the opam-repository occasionally, Dune might pick
+different solutions over time.


I think this isn't a very robust account of the dynamics at play. Whether or not new packages are published, different builds can end up with different dependencies based on a number of factors: the system run on, the which repos are pinned, whether or not the user has had connectivity, whether packages are marked unavailable, etc. I think it's better to just describe the core need that motivates locking. And you do that in the next paragraph. So maybe this sentence can be removed?

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

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

Sudha247

Good to have this updated!

Some remarks below. I also found mentions of dune pkg lock in howto/use-opam-alongside-dune-package-management.rst and howto/homebrew-package.rst which we might want to check.

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

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

shonfeder · 2025-12-10T12:15:01Z

Is this ready for another review? Or is it still being worked on?

Leonidas-from-XIV · 2025-12-10T13:18:45Z

Yes, I welcome some reviews so maybe we can get it merged in time for 3.21.

Signed-off-by: Marek Kubica <[email protected]>

Sudha247 · 2025-12-10T16:15:09Z

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

-longer than usual, as the dependencies need to be built first. Subsequent
-builds where all dependencies have been built before will be just as fast as
-before.
+Since this is the first time we have run the build system after enabling package


It seems this is getting folded in the collapsible dune-workspace. I'm not sure that is intended?

Sudha247

I've gone through the tutorial once to validate we get the expected results, and we do. I think this is good to go.

shonfeder

I have a few more suggestions, but they don't need to blocking.

shonfeder · 2025-12-11T03:23:17Z

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

+In this file we let Dune know to enable package management in the current
+workspace. This way Dune will know that it is expected to install the
+dependencies automatically.


(re)reading this, the anthropomorphism of Dune stands out to me. I think we can be more direct, and know attributing any "knowing" ;)

Suggested change

In this file we let Dune know to enable package management in the current

workspace. This way Dune will know that it is expected to install the

dependencies automatically.

In this file we direct Dune to enable package management in the current

workspace. This configures Dune to manage the declared dependencies automatically.

shonfeder · 2025-12-11T03:24:15Z

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


-which will download and install the new dependencies and build our project as
-before.
+This will recongnize that the project depends on new packages. Thus it will


What does 'this' refer to here?

shonfeder · 2025-12-11T03:26:27Z

doc/tutorials/dune-package-management/locking/dune-workspace

+(lock_dir
+ (repositories overlay1 upstream1))


Ugh, that is awkward :( seems to be leaking implementation details, but that can be addressed in some followup.

shonfeder · 2025-12-11T03:32:20Z

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

+Dune resolves dependencies by creating an internal lock directory
+automatically. However, if an manually created lock directory exists in the
+source, Dune will use that one instead. The default name of said lock directory
+is `dune.lock`, and it can be created manually:


IMO, it is confusing to talk about these internal implementation details in docs like this. Users shouldn't care what dune with its private dirs, they just need to know the user-facing behavior and properties. Referring to a "lock" directory that doesn't actually server to lock anything is going to get people confused, I predict.

Suggested change

Dune resolves dependencies by creating an internal lock directory

automatically. However, if an manually created lock directory exists in the

source, Dune will use that one instead. The default name of said lock directory

is `dune.lock`, and it can be created manually:

If a lock directory exists in the source, Dune will use that to fix the exact version and source of dependencies. The default name of said lock directory

is `dune.lock`. Lock directories are created with:

shonfeder · 2025-12-11T03:32:34Z

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

+## Create a lock directory manually
+
+Dune resolves dependencies by creating an internal lock directory
+automatically. However, if an manually created lock directory exists in the


At minimum:

Suggested change

automatically. However, if an manually created lock directory exists in the

automatically. However, if a manually created lock directory exists in the

shonfeder · 2025-12-11T03:33:05Z

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

+
+Whenever Dune encounters a `dune.lock` folder, it will use the set of
+dependencies defined in the lock. It contains all the metadata about package
+names and versions, their dependencies & source locations that are necesary to


Suggested change

names and versions, their dependencies & source locations that are necesary to

names and versions, their dependencies and source locations that are necessary to

shonfeder · 2025-12-11T03:33:25Z

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

+Whenever Dune encounters a `dune.lock` folder, it will use the set of
+dependencies defined in the lock. It contains all the metadata about package
+names and versions, their dependencies & source locations that are necesary to
+build the projects dependencies.


Suggested change

build the projects dependencies.

build the project's dependencies.

shonfeder · 2025-12-11T03:34:00Z

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

+The lock directory will not be updated until a new lock directory is created,
+by rerunning `dune pkg lock`.


Suggested change

The lock directory will not be updated until a new lock directory is created,

by rerunning `dune pkg lock`.

The lock directory will not be updated until `dune pkg lock` is rerun.

shonfeder · 2025-12-11T03:34:52Z

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

+export the configuration of a switch.
+:::
+
+Deleting the lock directory switches Dune back into automatically determining


To avoid possible confusion with switch in the note above:

Suggested change

Deleting the lock directory switches Dune back into automatically determining

Deleting the lock directory will cause Dune to fall back to automatically determining

Leonidas-from-XIV added docs Documentation improvements package management labels Dec 3, 2025

Leonidas-from-XIV self-assigned this Dec 3, 2025

shym mentioned this pull request Dec 4, 2025

Revise automagic steps with regards to package management ocaml-dune/setup-dune#13

Open

Leonidas-from-XIV force-pushed the update-pkg-mgmt-tutorial-autolock branch from c435b75 to eb5bcf5 Compare December 5, 2025 10:18

Leonidas-from-XIV marked this pull request as ready for review December 5, 2025 10:18

Leonidas-from-XIV requested review from Sudha247 and shonfeder December 5, 2025 10:18

shonfeder reviewed Dec 5, 2025

View reviewed changes

Leonidas-from-XIV force-pushed the update-pkg-mgmt-tutorial-autolock branch 2 times, most recently from aad05d3 to 15a0e31 Compare December 8, 2025 15:29

Leonidas-from-XIV requested a review from shonfeder December 8, 2025 15:32

Leonidas-from-XIV changed the title ~~Update documentation to use autolocking~~ Update tutorial to use autolocking Dec 8, 2025

Sudha247 reviewed Dec 8, 2025

View reviewed changes

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

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

Leonidas-from-XIV force-pushed the update-pkg-mgmt-tutorial-autolock branch from 9e4d89d to 598ff93 Compare December 10, 2025 10:59

Leonidas-from-XIV requested review from ElectreAAS and Sudha247 December 10, 2025 11:00

Leonidas-from-XIV added 4 commits December 10, 2025 15:01

Update documentation to use autolocking

5ce194c

Signed-off-by: Marek Kubica <[email protected]>

Clarify locking behavior

4206c90

Signed-off-by: Marek Kubica <[email protected]>

Use new log output style

81367a8

Signed-off-by: Marek Kubica <[email protected]>

Remove the repository pinning part, its not a real lock anyway

eebe860

Signed-off-by: Marek Kubica <[email protected]>

Leonidas-from-XIV force-pushed the update-pkg-mgmt-tutorial-autolock branch from 598ff93 to eebe860 Compare December 10, 2025 14:02

Sudha247 reviewed Dec 10, 2025

View reviewed changes

Sudha247 approved these changes Dec 10, 2025

View reviewed changes

shonfeder approved these changes Dec 11, 2025

View reviewed changes

		packages are published in the opam-repository occasionally, Dune might pick
		different solutions over time.

	automatically. However, if an manually created lock directory exists in the
	automatically. However, if a manually created lock directory exists in the

	names and versions, their dependencies & source locations that are necesary to
	names and versions, their dependencies and source locations that are necessary to

	build the projects dependencies.
	build the project's dependencies.

		The lock directory will not be updated until a new lock directory is created,
		by rerunning `dune pkg lock`.

	Deleting the lock directory switches Dune back into automatically determining
	Deleting the lock directory will cause Dune to fall back to automatically determining

Update tutorial to use autolocking #12859

Are you sure you want to change the base?

Update tutorial to use autolocking #12859

Conversation

Leonidas-from-XIV commented Dec 3, 2025

Uh oh!

Leonidas-from-XIV commented Dec 5, 2025

Uh oh!

Uh oh!

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!

Sudha247 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

shonfeder commented Dec 10, 2025

Uh oh!

Leonidas-from-XIV commented Dec 10, 2025

Uh oh!

Sudha247 Dec 10, 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!

Sudha247 left a comment

Choose a reason for hiding this comment

Uh oh!

shonfeder left a comment

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Sudha247 Dec 10, 2025 •

edited

Loading