Add doc about making brew package with dune pkg

Signed-off-by: Stephen Sherratt <[email protected]>

Author: gridbugs

doc/howto/homebrew-package.rst

@@ -0,0 +1,96 @@
+How to make a Homebrew Package with Dune
+========================================
+
+This guide will show you how to make a Homebrew package for an application
+using Dune package management. The only dependency of the Homebrew package will
+be Dune, and all OCaml dependencies (including the OCaml compiler) will be
+installed by Dune while building the Homebrew package.
+
+To use Dune package management to build a project as a Homebrew package, the
+project must have a source archive hosted online somewhere (e.g. a gzipped
+tarball on the project's Github release page).
+
+Before making a Homebrew package, it's a good idea to familiarize yourself with
+Homebrew's terminology and packaging conventions `here
+<https://docs.brew.sh/Adding-Software-to-Homebrew>`__.
+
+Homebrew packages are recommended to be source-based, and for the source code
+to be explicitly versioned, so for this example assume ``my_app`` has a
+versioned archive hosted on Github with version ``0.1.0``.
+
+Homebrew can generate a starting point for a formula if you point it at a
+source archive hosted on Github:
+
+.. code:: console
+
+  $ brew create https://github.com/me/my_app/archive/refs/tags/0.1.0.tar.gz
+
+A source archive like the one in the above command is generated when you
+release a project on Github. The above command will generate a file named
+``my_app.rb`` in your current tap. All the project metadata will be filled in
+automatically based on the project on Github. All we need to do now is to
+specify dependencies and the commands ``brew`` should run when installing the
+package.
+
+Here's the complete formula for ``my_app``. Note that the ``test`` section is
+intended to be a sanity check of the core functionality of the package, not a
+complete integration test suite. Read more about Homebrew package tests `here
+<https://docs.brew.sh/Formula-Cookbook#add-a-test-to-the-formula>`__. Note
+however that tests run in an environment without access to build dependencies
+such as Dune, so ``dune runtest`` can't be used to test Homebrew packages.
+
+.. code:: ruby
+
+  class MyApp < Formula
+    desc "My awesome app"
+    homepage "https://github.com/me/my_app"
+    url "https://github.com/me/my_app/releases/download/0.1.0/0.1.0.tar.gz"
+    sha256 "eb8705de406441675747a639351d0d59bffe7b9f5b05ec9b6e11b4c4c9d7a6ee"
+    license "MIT"
+
+    depends_on "dune" => :build
+
+    def install
+      system "dune", "pkg", "lock"
+      system "dune", "build", "@install", "--release", "--only-packages", "my_app"
+      system "dune", "install", "--prefix=#{prefix}", "my_app"
+    end
+
+    test do
+      # Test your application here!
+      system "my_app", "--version"
+    end
+  end
+
+This assumes that the name of the package in the source archive is ``my_app``.
+That is, the archive contains a ``dune-project`` file defining a package named
+``my_app``, or that the archive contains a ``my_app.opam``. The archive may
+contain multiple packages provided that ``my_app`` is one of them.
+
+Note the first install command: ``dune pkg lock``. This is only necessary if
+the source archive doesn't contain a lockdir (a ``dune.lock`` directory
+containing the transitive dependency closure of the package). Running ``dune
+pkg lock`` invokes Dune's dependency solver resolving the dependencies in
+``dune-project`` or ``my_app.opam`` against the current tip of the `Opam
+Repository <https://github.com/ocaml/opam-repository>`_. Solving dependencies
+while installing a Homebrew package means that the exact versions of
+dependencies may be different each time the Homebrew package is installed. For
+this reason it's advised to use source archives which already contain a
+lockdir, and omit the ``dune pkg lock`` command when packaging a Dune project
+for Homebrew. However in some situations solving dependencies at install time
+is unavoidable, such as when packaging a project whose source archive is
+already released and lacks a lockdir.
+
+If there are any packages with external dependencies (i.e. ``depexts``) in
+``my_app``'s transitive dependency closure, their corresponding Homebrew
+package must be added as a dependency of ``my_app``'s Homebrew packages by
+adding a ``depends_on`` entry for each. List all the external dependencies
+among ``my_app``'s transitive dependency closure by running:
+
+.. code:: console
+
+   $ dune show depexts
+
+External dependencies can be platform-specific, so if you're planning to make the
+Homebrew package available for macOS, be sure to run the above command on a Mac
+to determine which external dependencies need to be added to the formula.

doc/howto/index.rst

@@ -23,3 +23,4 @@ These guides will help you use Dune's features in your project.
    toplevel
    rule-generation
    override-default-entrypoint
+   homebrew-package