Update documentation to use autolocking

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

Author: Leonidas-from-XIV

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

@@ -9,7 +9,8 @@ Much like in regular projects, to add a library we need to add a dependency to
 it. For simplicity we will use the popular `fmt` library as an example, but any
 package from the [package repository](https://ocaml.org/packages) can be used.
 
-First we update the `dune-project` file to add a dependency on the opam package.
+To do so we update the `dune-project` file to add a dependency on the opam
+package.
 
 ::::{dropdown} `dune-project`
 :icon: file-code
@@ -21,28 +22,6 @@ First we update the `dune-project` file to add a dependency on the opam package.
 
 ::::
 
-After this change to our project dependencies, we need to relock dependencies
-to update our lock directory with the new packages.
-
-```
-$ dune pkg lock
-Solution for dune.lock:
-- base-unix.base
-- fmt.0.9.0
-- ocaml.5.2.0
-- ocaml-base-compiler.5.2.0
-- ocaml-config.3
-- ocamlbuild.0.15.0+dune
-- ocamlfind.1.9.6+dune
-- topkg.1.0.7
-```
-
-You can see a lot of new dependencies, among these `fmt`.
-
-:::{note}
-The list of packages being output includes all dependencies of your project,
-including transitive dependencies.
-:::
 
 This will take care of installing the dependencies, but we still need to add it to
 our build as a library as usual:
@@ -80,8 +59,10 @@ To build it we just call `build` again.
 $ dune build
 ```
 
-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
+re-run the internal dependency solver to find a solution for the set of
+packages to use. It will then use this new solution to download, build and
+install these dependencies automatically.
 
 As we see, the code works and uses `fmt` to do the pretty-printing:
 
@@ -106,35 +87,24 @@ used for opam dependencies in the `dune-project` file.
 
 ::::
 
-This ensures the `fmt` package to install will be compatible with
-our request. These constraints will be taken into account the next time the
-package is locked:
+This ensures the `fmt` package to install will be compatible with our request.
+These constraints will be taken into account the next time the build system is
+ran.
 
+```sh
+dune build
 ```
-$ dune pkg lock
-Solution for dune.lock:
-- base-unix.base
-- fmt.0.9.0
-- ocaml.5.2.0
-- ocaml-base-compiler.5.2.0
-- ocaml-config.3
-- ocamlbuild.0.15.0+dune
-- ocamlfind.1.9.6+dune
-- topkg.1.0.7
-```
-
-The version of `fmt` picked is indeed between `0.6` and `1.0`.
 
 ## Removing Dependencies
 
 Given all dependencies are defined in the `dune-project` file, removing a
-dependency means to remove the dependency from the `depends` field of your
-`dune-project` and relocking the project.
+dependency just means to remove the dependency from the `depends` field of your
+`dune-project`.
 
-The new lock directory will not depend on the package anymore, and in future
-builds, the package will not be accessible as `library` anymore.
+From then on the project will not depend on the package anymore, and in future
+builds the package will not be accessible as `library` anymore.
 
 :::{note}
-The removed dependency might still be part of the lock directory if some other
-dependency of your project depends on it.
+The removed dependency might still be accessible if some other dependency of
+your project depends on it, thus if it is a transitive dependency.
 :::

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

@@ -24,4 +24,5 @@ setup
 dependencies
 pinning
 repos
+locking
 :::

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

@@ -0,0 +1,62 @@
+# Locking Your Dependencies
+
+In the default use-case Dune will automatically determine which packages to
+install, including solving compatible versions and installing their
+dependencies recursively.
+
+For many projects this is a good and acceptable behavior as users often want to
+use new versions of their dependencies. However some projects might want to
+keep a fixed set of dependencies that is only updated manually. This can be
+done in multiple ways.
+
+## Create a lock directory
+
+Dune locks dependencies by creating lock directories. The default lock 
+directory is called `dune.lock`. To create a lock, run
+
+```
+$ dune pkg lock
+Solution for dune.lock:
+- ocaml.5.2.0
+- ocaml-base-compiler.5.2.0
+- ocaml-config.3
+```
+
+Whenever Dune encounters a `dune.lock` folder, it will use the set of
+dependencies defined in the lock. The lock will not be updated until a user
+relocks by running `dune pkg lock` again.
+
+On the next build, Dune will read the solution from the `dune.lock` directory,
+download and build the dependencies and then continue on building the project
+as usual.
+
+:::{note}
+This approach is similar to using `opam switch export --full --freeze` to
+export the configuration of a switch.
+:::
+
+## Pin the package repositories to a commit
+
+A way to ensure that dependencies won't change due to package updates is to pin
+the package repositories to a fixed commit.
+
+::::
+
+::::{dropdown} `dune-workspace`
+:icon: file-code
+
+:::{literalinclude} locking/dune-workspace
+:language: dune
+:::
+
+
+::::
+
+On the next build, Dune will check out out these specific two repositories at
+the specified commit and use them for resolving all dependencies. It will then
+download and build the dependencies as usual.
+
+:::{note}
+This approach is similar to pinning OPAM repositories by explicitely setting
+them to known versions using commands like `opam repository add <name> <fixed-url>`.
+:::

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

@@ -0,0 +1,13 @@
+(lang dune 3.21)
+(pkg enabled)
+
+(repository
+ (name overlay1)
+ (url "https://github.com/ocaml-dune/opam-overlays.git#2a9543286ff0e0656058fee5c0da7abc16b8717d"))
+
+(repository
+ (name upstream1)
+ (url "https://github.com/ocaml/opam-repository.git#2fd4164ca1e27b8c6027454c4844c1a1f6dca0bc"))
+
+(lock_dir
+ (repositories overlay1 upstream1))

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

@@ -29,19 +29,6 @@ dependencies.
 The next time the package is locked, Dune will use this repository instead of
 the information from the selected package repositories.
 
-```
-$ dune pkg lock
-Solution for dune.lock:
-- base-unix.base
-- fmt.dev
-- ocaml.5.0.0
-- ocaml-base-compiler.5.0.0
-- ocaml-config.3
-- ocamlbuild.0.15.0+dune
-- ocamlfind.1.9.6+dune
-- topkg.1.0.7
-```
-
 Unlike previously, the version of the `fmt` library that is picked is `dev`, to
 signify a development version.
 

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

@@ -30,27 +30,19 @@ For more information about the stanzas refer to the {doc}`repositories stanza
 </reference/dune-workspace/repository>` as well as the {doc}`lock_dir stanza
 </reference/dune-workspace/lock_dir>`.
 
-When relocking the dependencies, the list of packages that are found as
-dependencies changes accordingly:
-
-```
-$ dune pkg lock
-Solution for dune.lock:
-- base-unix.base
-- fmt.0.9.0
-- ocaml.5.0.0
-- ocaml-base-compiler.5.0.0
-- ocaml-config.3
-- ocamlbuild.0.15.0+dune
-- ocamlfind.1.9.6+dune
-- topkg.1.0.
-```
-
-Compared to before, the OCaml compiler version is older, which shows
-that we did indeed pick an older version of the package repository for locking.
+The next time the build system is run, instead of using the default
+repositories at their newest versions, the solver will check out the configured
+repositories at the defined revisions. These will then be used to determine the
+new solution, which will get used for downloading and building the
+dependencies.
 
 :::{note}
 This feature can also be used to make sure the locked dependencies are
 reproducible, as fixing all the package repository versions will lead to
 equivalent locking results.
 :::
+
+:::{seealso}
+{doc}`/tutorials/dune-package-management/locking`
+  More information how to keep package versions locked.
+:::

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

@@ -55,30 +55,24 @@ just define the module as an executable.
 
 After our project skeleton is set up, we can proceed to the next step.
 
-## Locking Dependencies
+## Enable package management
 
-After declaring the dependencies, you will need to tell Dune which package
-versions to use for your project. This is done by creating a lock directory.
-This is easily done with a new Dune command:
+So far we have done everything as in a regular Dune project. However, now we
+need to tell Dune that we want to use the package management feature. To do so
+we have to add a new stanza to our `dune-workspace` file, creating it if it
+doesn't exist.
 
-```
-$ dune pkg lock
-Solution for dune.lock:
-- ocaml.5.2.0
-- ocaml-base-compiler.5.2.0
-- ocaml-config.3
-```
-
-This will update all the required opam repositories, use the newest version of
-each and try to find a set of packages and versions that satisfy the
-constraints that your project dependencies declare.
+::::{dropdown} `dune-workspace`
+:icon: file-code
 
-:::{note}
-The versions that get locked might be different from this tutorial, as we only
-specified the lower bound of `ocaml`; barring any additional configuration, Dune
-will pick the newest possible version for each dependency.
+:::{literalinclude} setup/dune-workspace
+:language: dune
+:emphasize-lines: 2
 :::
 
+This new stanza will tell Dune to determine the packages that your project
+depends on, find the right versions, download, and build them on the next build.
+
 ## Build Project
 
 To build the project, you can just use the regular Dune commands.
@@ -87,11 +81,22 @@ To build the project, you can just use the regular Dune commands.
 dune build
 ```
 
-This will download, build, and install all your locked dependencies and then use
-those to build your project. This means that the first time building it will take
-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
+management a number of things will happen:
+
+ 1. It will download and update all required opam repositories to determine
+    which packages are available.
+ 2. It will attempt to find a package solution that satisfies all dependency
+    constraints.
+ 3. It will download the sources of the dependencies.
+ 4. It will build the dependencies in sandbox locations.
+ 5. It will install the dependencies in the build folder.
+ 6. It will build the project using the dependencies that it has installed.
+
+This means that building the first time will take longer than usual, as the
+dependencies need to be built, possibly including the OCaml compiler.
+Subsequent builds where all dependencies have already been built will
+be significantly faster.
 
 We can show that the package has been built successfully and works as expected:
 
@@ -101,13 +106,16 @@ Hello, OCaml, Rust!
 ```
 
 :::{note}
-If you want to only build and fetch the project dependencies, you can use
+If you don't want to build your project, instead stopping at step 5, you can use
 the `@pkg-install` alias like so
 
 ```shell
 $ dune build @pkg-install
 ```
 
+This functionality can be useful to cache the installation of dependencies,
+somewhat similar to `opam switch create` followed by `opam install`.
+
 See {doc}`/reference/aliases/pkg-install` for more information.
 :::
 

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

@@ -0,0 +1,2 @@
+(lang dune 3.21)
+(pkg enabled)