Add an installation section to the manual (#2294)

It regroups the various bits about installing things and clarify the
section semantics for file installation.

Closes #2198

Signed-off-by: Anil Madhavapeddy <anil@recoil.org>
Signed-off-by: Jeremie Dimino <jeremie@dimino.org>
Co-Authored-By: Etienne Millon <etienne.millon@gmail.com>

doc/dune-files.rst

@@ -652,63 +652,9 @@ tests.
 install
 -------
 
-The ``install`` stanza is what lets you describe what dune should install,
-either when running ``dune install`` or through opam.
-
-Libraries and executables don't need an ``install`` stanza to be
-installed, just a ``public_name`` field. Everything else needs an
-``install`` stanza.
-
-The syntax is as follows:
-
-.. code:: scheme
-
-    (install
-     (section <section>)
-     (files   <filenames>)
-     <optional-fields>)
-
-``<section>`` is the installation section, as described in the opam
-manual. The following sections are available:
-
--  ``lib``
--  ``lib_root``
--  ``libexec``
--  ``libexec_root``
--  ``bin``
--  ``sbin``
--  ``toplevel``
--  ``share``
--  ``share_root``
--  ``etc``
--  ``doc``
--  ``stublibs``
--  ``man``
--  ``misc``
-
-``<files>`` is the list of files to install. Each element in the list
-must be either a literal filename or a S-expression of the form:
-
-.. code:: scheme
-
-    (<filename> as <destination>)
-
-where ``<destination>`` describe how the file will be installed. For
-instance, to install a file ``mylib.el`` as
-``emacs/site-lisp/mylib.el`` in the ``share_root`` section:
-
-.. code:: scheme
-
-    (install
-     (section share_root)
-     (files   (mylib.el as emacs/site-lisp/mylib.el)))
-
-``<optional-fields>`` are:
-
-- ``(package <name>)``. If there are no ambiguities, you can omit this field.
-  Otherwise you need it to specify which package these files are part of. The
-  package is not ambiguous when the first parent directory to contain a
-  ``<package>.opam`` file contains exactly one ``<package>.opam`` file
+Dune supports installing packages on the system, i.e. copying freshly
+built artifacts from the workspace to the system.  See the
+`installation` section for more details.
 
 Handling of the .exe extension on Windows
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/installation.rst

@@ -0,0 +1,245 @@
+*********************************
+Installing packages on the system
+*********************************
+
+Installation is the process of copying freshly built libraries,
+binaries and other files from the build directory to the system.  Dune
+offers two way of doing this: via opam or directly via the ``install``
+command.  In particular, the installation model implemented by Dune
+was copied from opam. Opam is the standard OCaml package manager.
+
+In both cases, Dune only know how to install whole packages.  A
+package being a collection of executables, libraries and other files.
+In this section, we will describe how to define a package, how to
+"attach" various elements to it and how to proceed with installing it
+on the system.
+
+Declaring a package
+===================
+
+To declare a package, simply add a ``package`` stanza to your
+``dune-project`` file:
+
+.. code:: scheme
+
+          (package
+           (name mypackage)
+           (synopsis "My first Dune package!")
+           (description "\| This is my first attempt at creating
+                        "\| a project with Dune.
+          ))
+
+Once you have done this, Dune will know about the package named
+``mypackage`` and you will be able to attach various elements to it.
+The ``package`` stanza accepts more fields, such as dependencies.
+
+Note that package names are in a global namespace so the name you choose must
+be universally unique.  In particular, package managers never allow to
+release two packages with the same name.
+
+.. TODO: describe this more in details
+
+In older projects using Dune, packages were defined by the presence of
+a file called ``<package-name>.opam`` at the root of the project.
+However, it is not recommended to use this method in new projects as
+we expect to deprecate it in the future.  The right way to define a
+package is with a ``package`` stanza in the ``dune-project`` file.
+
+Attaching elements to a package
+===============================
+
+Attaching an element to a package means declaring to Dune that this
+element is part of the said package.  The method to attach an element
+to a package depends on the kind of the element.  In this sub-section
+we will go through the various kinds of elements and describe how to
+attach each of them to a package.
+
+In the rest of this section, ``<prefix>`` refers to the directory in
+which the user chooses to install packages.  When installing via opam,
+it is opam who sets this directory.  When calling ``dune install``,
+the installation directory is either guessed or can be manually
+specified by the user.  This is described more in detail in the last
+section of this page.
+
+Libraries
+---------
+
+In order to attach a library to a package all you need to do is add a
+``public_name`` field to your library.  This is the name that external
+users of your libraries must use in order to refer to it.  Dune
+requires that the public name of a library is either the name of the
+package it is part of or start with the package name followed by a dot
+character.
+
+For instance:
+
+.. code:: scheme
+
+          (library
+           (name mylib)
+           (public_name mypackage.mylib))
+
+After you have added a public name to a library, Dune will know to
+install it as part of the package it is attached to.  Dune installs
+the library files in a directory ``<prefix>/lib/<package-name>``.
+
+If the library name contains dots, the full directory in which the
+library files are installed is ``lib/<comp1>/<comp2/.../<compn>``
+where ``<comp1>``, ``<comp2>``, ... ``<compn>`` are the dot separated
+component of the public library name.  By definition, ``<comp1>`` is
+always the package name.
+
+Executables
+-----------
+
+Similarly to libraries, to attach an executable to a package simply
+add a ``public_name`` field to your ``executable`` stanza, or a
+``public_names`` field for ``executables`` stanzas.  The name that
+goes in there is the name under which the executables will be
+available through the ``PATH`` once installed, i.e. the name users
+will need to type in there shell to execute the program.  Because Dune
+cannot guess which package an executable is part of from its public
+name, you also need to add a ``package`` field unless the project
+contains a single package, in which case the executable will be
+attached to this package.
+
+For instance:
+
+.. code:: scheme
+
+          (executable
+           (name main)
+           (public_name myprog)
+           (package mypackage))
+
+Once ``mypackage`` is installed on the system, the user will be able
+to type the following in their shell:
+
+::
+
+   $ myprog
+
+to execute the program.
+
+Other files
+-----------
+
+For all other kinds of elements, you need to attach them manually via
+an ``install`` stanza.  The install stanza takes three informations:
+
+- the list of files the install
+- the package to attach these files to. This field is optional if your
+  project contains a single package
+- the section in which the files will be installed
+
+For instance:
+
+.. code::
+
+   (install
+    (files hello.txt)
+    (section share)
+    (package mypackage))
+
+Indicate that the file ``hello.txt`` in the current directory is to be
+installed in ``<prefix>/share/mypacakge``.
+
+The following sections are available:
+
+- ``lib`` installs to ``<prefix>/lib/<pkgname>/``
+- ``lib_root`` installs to ``<prefix>/lib/``
+- ``libexec`` installs to ``<prefix>/lib/<pkgname>/`` with the
+   executable bit set
+- ``libexec_root`` installs to ``<prefix>/lib/`` with the executable
+   bit set
+- ``bin`` installs to ``<prefix>/bin/`` with the executable bit set
+- ``sbin`` installs to ``<prefix>/sbin/`` with the executable bit set
+- ``toplevel`` installs to ``<prefix>/lib/toplevel/``
+- ``share`` installs to ``<prefix>/share/<pkgname>/``
+- ``share_root`` installs to ``<prefix>/share/``
+- ``etc`` installs to ``<prefix>/etc/<pkgname>/``
+- ``doc`` installs to ``<prefix>/doc/<pkgname>/``
+- ``stublibs`` installs to ``<prefix>/lib/stublibs/`` with the
+   executable bit set
+- ``man`` installs relative to ``<prefix>/man`` with the destination
+   directory extracted from the extension of the source file (so that
+   installing ``foo.1`` is equivalent to a destination of
+   ``man1/foo.1``)
+- ``misc`` requires files to specify an absolute destination, and the
+   user will be prompted before the installation when it is done via
+   opam. Only use this for advanced cases.
+
+Normally, Dune uses the basename of the file to install to determine
+the name of the file once installed.  However, you can change that
+fact by using the form ``(<filename> as <destination>)`` in the
+``files`` field. For instance, to install a file ``mylib.el`` as
+``<prefix>/emacs/site-lisp/mylib.el`` you must write the following:
+
+.. code:: scheme
+
+    (install
+     (section share_root)
+     (files   (mylib.el as emacs/site-lisp/mylib.el)))
+
+Installing a package
+====================
+
+Via opam
+--------
+
+When releasing a package using Dune in opam there is nothing special
+to do.  Dune generates a file called ``<package-name>.opam`` at the
+root of the project.  This contains a list of files to install and
+opam reads it in order to perform the installation.
+
+Manually
+--------
+
+When not using opam or when you want to manually install a package,
+you can ask Dune to perform the installation via the ``install``
+command:
+
+::
+
+    $ dune install [PACKAGE]...
+
+This command takes a list of package names to install.  If no packages
+are specified, Dune will install all the packages available in the
+workspace.  When several build contexts are specified via a
+`dune-workspace`_ file, the installation will be performed in all the
+build contexts.
+
+Destination directory
+---------------------
+
+The ``<prefix>`` directory is determined as follows for a given build
+context:
+
+#. if an explicit ``--prefix <path>`` argument is passed, use this path
+#. if ``opam`` is present in the ``PATH`` and is configured, use the
+   output of ``opam config var prefix``
+#. otherwise, take the parent of the directory where ``ocamlc`` was found.
+
+As an exception to this rule, library files might be copied to a
+different location. The reason for this is that they often need to be
+copied to a particular location for the various build system used in
+OCaml projects to find them and this location might be different from
+``<prefix>/lib`` on some systems.
+
+Historically, the location where to store OCaml library files was
+configured through `findlib
+<http://projects.camlcity.org/projects/findlib.html>`__ and the
+``ocamlfind`` command line tool was used to both install these files
+and locate them. Many Linux distributions or other packaging systems
+are using this mechanism to setup where OCaml library files should be
+copied.
+
+As a result, if none of ``--libdir`` and ``--prefix`` is passed to ``dune
+install`` and ``ocamlfind`` is present in the ``PATH``, then library files will
+be copied to the directory reported by ``ocamlfind printconf destdir``. This
+ensures that ``dune install`` can be used without opam. When using opam,
+``ocamlfind`` is configured to point to the opam directory, so this rule makes
+no difference.
+
+Note that ``--prefix`` and ``--libdir`` are only supported if a single build
+context is in use.

doc/usage.rst

@@ -401,60 +401,6 @@ To setup the building and running of tests in opam, add this line to your
       ["dune" "runtest" "-p" name "-j" jobs] {with-test}
     ]
 
-Installation
-============
-
-Installing a package means copying the build artifacts from the build directory
-to the installed word.
-
-When installing via opam, you don't need to worry about this step: dune
-generates a ``<package>.install`` file that opam will automatically read to
-handle installation.
-
-However, when not using opam or doing local development, you can use dune to
-install the artifacts by hands. To do that, use the ``install`` command:
-
-::
-
-    $ dune install [PACKAGE]...
-
-without an argument, it will install all the packages available in the
-workspace. With a specific list of packages, it will only install these
-packages. If several build contexts are configured, the installation will be
-performed for all of them.
-
-Destination
------------
-
-The place where the build artifacts are copied, usually referred as **prefix**,
-is determined as follow for a given build context:
-
-#. if an explicit ``--prefix <path>`` argument is passed, use this path
-#. if ``opam`` is present in the ``PATH`` and is configured, use the
-   output of ``opam config var prefix``
-#. otherwise, take the parent of the directory where ``ocamlc`` was found.
-
-As an exception to this rule, library files might be copied to a different
-location. The reason for this is that they often need to be copied to a
-particular location for the various build system used in OCaml projects to find
-them and this location might be different from ``<prefix>/lib`` on some systems.
-
-Historically, the location where to store OCaml library files was configured
-through `findlib <http://projects.camlcity.org/projects/findlib.html>`__ and the
-``ocamlfind`` command line tool was used to both install these files and locate
-them. Many Linux distributions or other packaging systems are using this
-mechanism to setup where OCaml library files should be copied.
-
-As a result, if none of ``--libdir`` and ``--prefix`` is passed to ``dune
-install`` and ``ocamlfind`` is present in the ``PATH``, then library files will
-be copied to the directory reported by ``ocamlfind printconf destdir``. This
-ensures that ``dune install`` can be used without opam. When using opam,
-``ocamlfind`` is configured to point to the opam directory, so this rule makes
-no difference.
-
-Note that ``--prefix`` and ``--libdir`` are only supported if a single build
-context is in use.
-
 Workspace configuration
 =======================