doc: dune pkg tutorial

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

@@ -0,0 +1,140 @@
+# Managing Dependencies
+
+The OCaml ecosystem has a wealth of third-party packages that are available for
+use. In this section we will look into how to use them with Dune.
+
+## Adding Dependencies
+
+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 dependeny on the opam package.
+
+::::{dropdown} `dune-project`
+:icon: file-code
+
+:::{literalinclude} dependencies/dune-project
+:language: dune
+:emphasize-lines: 8
+:::
+
+::::
+
+After this change to our project dependencies, we need to relock dependencies
+to update our lock directory with the new packages.
+
+```sh
+$ 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:
+
+::::{dropdown} `dune`
+:icon: file-code
+
+:::{literalinclude} dependencies/dune
+:language: dune
+:emphasize-lines: 3
+:::
+
+Adding a library dependency to our `dune` file via the `libraries` stanza.
+
+::::
+
+This will allow us to use the `Fmt` module in our OCaml code.
+
+::::{dropdown} `test.ml`
+:icon: file-code
+
+:::{literalinclude} dependencies/test.ml
+:language: ocaml
+:emphasize-lines: 4
+:::
+
+We update the code to define an `Fmt.t` pretty-printer for the list of strings
+and then use it to print the value.
+
+::::
+
+To build it we just call `build` again.
+
+```sh
+$ dune build
+```
+
+which will download and install the new dependencies and build our project as
+before.
+
+As we see, the code works and uses `fmt` to do the pretty-printing:
+
+```sh
+$ dune exec ./test.exe
+Hello, OCaml, Rust!
+```
+
+### Dependency Constraints
+
+Packages are often only compatible with some versions of dependencies. To
+specify a version range, use the regular Dune dependency syntax
+used for opam dependencies in the `dune-project` file.
+
+::::{dropdown} `dune-project`
+:icon: file-code
+
+:::{literalinclude} dependencies/constraints
+:language: dune
+:emphasize-lines: 7-8
+:::
+
+::::
+
+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:
+
+```sh
+$ 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.
+
+The new lock directory 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.
+:::

doc/tutorials/dune-package-management/dependencies/constraints

@@ -0,0 +1,8 @@
+(lang dune 3.17)
+(name test)
+
+(package
+ (name test)
+ (depends
+  (ocaml (>= 4.14))
+  (fmt (and (>= 0.6) (< 1.0)))))

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

@@ -0,0 +1,3 @@
+(executable
+  (public_name test)
+  (libraries fmt))

doc/tutorials/dune-package-management/dependencies/dune-project

@@ -0,0 +1,8 @@
+(lang dune 3.17)
+(name test)
+
+(package
+  (name test)
+  (depends
+    (ocaml (>= 4.14))
+    fmt))

doc/tutorials/dune-package-management/dependencies/test.ml

@@ -0,0 +1,5 @@
+let langs = ["OCaml"; "Rust"]
+
+let () =
+  let pp_langs = Fmt.(list ~sep:(any ", ") string) in
+  Format.printf "Hello, %a!\n" pp_langs langs

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

@@ -0,0 +1,27 @@
+---
+author: Marek Kubica
+---
+
+OCaml Package Management With Dune
+==================================
+
+:::{warning}
+Dune Package Management is not final yet and details are still subject to
+change.
+:::
+
+In this tutorial we will be looking at how to use Dune for managing project
+dependencies. This enables users to install the compiler as well as third-party
+dependencies using a single tool which takes care of building code and
+dependencies.
+
+To get started you only need Dune. Head to {doc}`setup` to begin the setup.
+
+:::{toctree}
+:hidden:
+:maxdepth: 1
+setup
+dependencies
+pinning
+repos
+:::

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

@@ -0,0 +1,50 @@
+# Pinning Projects
+
+When Dune is looking up packages to lock, it uses the (pre)configured OCaml
+package repositories. However it is also possible to manually specify the
+sources for packages; for example, if the package is not released in a package
+repository. This is called "pinning."
+
+## Installing Packages From a Pin
+
+To pin a package, a new `pin` has to be declared in the `dune-project` file.
+
+::::{dropdown} `dune-project`
+:icon: file-code
+
+:::{literalinclude} pinning/dune-project
+:language: dune
+:emphasize-lines: 4-6
+:::
+
+This will create a pin on the `fmt` package and use the specified Git repository
+URL to retrieve the sources.
+
+::::
+
+The next time the package is locked, Dune will use this repository instead of
+the information from the selected package repositories.
+
+```sh
+$ 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.
+
+The next build will check out the sources from that repository instead of
+downloading the release tarball:
+
+```sh
+$ dune exec ./test.exe
+Hello, OCaml, Rust!
+```

doc/tutorials/dune-package-management/pinning/dune-project

@@ -0,0 +1,12 @@
+(lang dune 3.17)
+(name test)
+
+(pin
+ (url "git+https://github.com/dbuenzli/fmt.git")
+ (package (name fmt)))
+
+(package
+ (name test)
+ (depends
+  (ocaml (>= 4.14))
+  fmt))

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

@@ -0,0 +1,52 @@
+# Custom Repositories
+
+By default when locking package versions, Dune looks up packages from two
+sources:
+
+  1. The upstream, community maintained `opam-repository` at
+     [ocaml/opam-repository](https://github.com/ocaml/opam-repository) for most
+     packages
+  2. An overlay repository with patched software to allow usage in Dune at
+     [ocaml-dune/opam-overlays](https://github.com/ocaml-dune/opam-overlays)
+
+To change the presets, the `dune-workspace` file has to be edited (and created
+if it didn't exist):
+
+::::{dropdown} `dune-workspace`
+:icon: file-code
+
+:::{literalinclude} repos/dune-workspace
+:language: dune
+:::
+
+::::
+
+In this case, we want to select a specific revision of the community repository
+instead of always using the most recent one, as it would do by default. We
+define a new repository and configure the lock directory to use this
+repository.
+
+When relocking the dependencies, the list of packages that are found as
+dependencies changes accordingly:
+
+```sh
+$ 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.
+
+:::{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.
+:::

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

@@ -0,0 +1,8 @@
+(lang dune 3.17)
+
+(lock_dir
+ (repositories overlay specific-upstream))
+
+(repository
+ (name specific-upstream)
+ (source "git+https://github.com/ocaml/opam-repository.git#00ac3727bc4ac0eabd3c89e69c1660d6b63a3d48"))