How to Generate Opam Files from ``dune-project``
================================================

.. highlight:: dune

This guide will show you how to configure Dune so that it generates opam files.

Declaring Package Dependencies
------------------------------

The goal of this first step is to add ``(package)`` stanzas in your
``dune-project`` file. These stanzas declare the metadata that your package
uses in the language of opam packages. See :ref:`declaring-a-package`.

The next step depends on whether you are starting from a clean slate (new
package) or adapting an existing opam file.

For a New Package (No Existing Opam File)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If your project does not have any opam files, you will have to find your
package dependencies. In the simple case, collect all the libraries
that appear in the ``(libraries)`` fields of your project and put this list in
the ``(depends)`` field of the corresponding ``(package)``. See
:doc:`../explanation/ocaml-ecosystem` for the difference between libraries and
packages.

Example: you have a library that looks like::

  (library
   (public_name frobnitz)
   (libraries lwt fmt))

You can declare the package as::

  (package
   (name frobnitz)
   (depends lwt fmt))

Also add common metadata using ``(authors)``, ``(maintainers)``, ``(license)``,
``(source)``, as well as a ``(synopsis)`` and a ``(description)`` for

For an Existing Package
^^^^^^^^^^^^^^^^^^^^^^^

If you already have an opam file (or several of them), you can convert it by
following the rules in :doc:`/reference/dune-project/package`.

For example, if your opam file looks like:

.. code:: opam

   opam-version: 2.0
   authors: ["Anil Madhavapeddy" "Rudi Grinberg"]
   maintainer: ["team@mirage.org"]
   name: "cohttp-async"
   synopsis: "HTTP client and server for the Async library"
   description: "A _really_ long description"
   license: "ISC"
   bug-reports: "https://github.com/mirage/ocaml-cohttp/issues"
   homepage: "https://github.com/mirage/ocaml-cohttp/"
   dev-repo: "git+https://github.com/mirage/ocaml-cohttp.git"
   build: [
     ["dune" "subst"] {dev}
     [
       "dune"
       "build"
       "-p"
       name
       "-j"
       jobs
       "@install"
       "@runtest" {with-test}
       "@doc" {with-doc}
     ]
   ]
   depends: [
     "dune" { >= "3.4" }
     "odoc" { with-doc }
     "cohttp" { >= "1.0.2" }
     "conduit-async" { >= "1.0.3" }
     "async" { >= "v0.10.0" }
   ]
   x-maintenance-intent: [ "(latest)" ]

You can express this as::

   (source (github mirage/ocaml-cohttp))
   (license ISC)
   (authors "Anil Madhavapeddy" "Rudi Grinberg")
   (maintainers "team@mirage.org")
   (maintenance_intent "(latest)")

   (package
    (name cohttp-async)
    (synopsis "HTTP client and server for the Async library")
    (description "A _really_ long description")
    (depends
     (cohttp (>= 1.0.2))
     (conduit-async (>= 1.0.3))
     (async (>= v0.10.0))))

General Notes and Tips
^^^^^^^^^^^^^^^^^^^^^^

- Do not declare a dependency on the ``dune`` and ``odoc`` packages. Dune will
  generate them with the right constraints.
- For fields that are common between packages (like ``(authors)`` or
  ``(license)``), you can use a global one rather than replicate it between
  packages.
- If you use a platform such as GitHub you can use ``(source)`` as a shorthand
  instead of specifying ``(bug_reports)``, ``(homepage)``, etc.
- ``(package)`` stanzas do not support all opam fields or complete syntax for
  dependency specifications. If the package you are adapting requires this,
  keep the corresponding opam fields in a ``pkg.opam.template`` file. See
  :doc:`../reference/packages`.
- It is not necessary to specify ``(version)``, this will be added at release
  time if you use `dune-release <https://github.com/tarides/dune-release>`_.
- To generate an opam variable such as ``version``, use a colon ``:`` followed
  by the name of the variable. For example, to generate ``a { = version }`` in
  the opam file, use ``(a (= :version))`` in ``dune-project``.

Generating Opam Files
---------------------

If you have existing ``*.opam`` files, make a backup of them because the instructions in this section will overwrite them.

Now that you have declared package metadata in ``dune-project``, you can add
``(generate_opam_files)`` in ``(dune-project)``.

From now on, commands like ``dune build`` and ``dune runtest`` are going to regenerate the contents of opam files from the metadata in ``(package)`` stanzas.
If you only want to generate the opam file, run ``dune build <project_name>.opam``.

Run ``dune build`` once and observe that the opam files have been created or
updated. Make sure to add these changes to your version control system.

.. seealso::

   :token:`~pkg-dep:dep_specification`
     How ``(depends)`` and similar fields are processed.

   :doc:`/explanation/opam-integration`
     How ``with-test`` and related variables are used by opam.