More progress on the opam generation

CHANGES.md

@@ -28,9 +28,9 @@ unreleased
 - Allow %{...} variables in pps flags (#2076, @mlasson review by @diml and
   @aalekseyev).
 
-- Add more opam metadata and use it to generate corrections to the .opam files
-  in the source. This allows the user to partially specify opam metadata in the
-  the dune-project file. (#2017, @avsm, @jonludlam)
+- Add more opam metadata and use it to generate `.opam` files. In particular, a
+  `package` field has been added to specify package specific information.
+  (#2017, #2091, @avsm, @jonludlam, @rgrinberg)
 
 - Clean up the special support for `findlib.dynload`. Before, Dune would simply
   match on the library name. Now, we only match on the findlib package name when

doc/opam.rst

@@ -8,35 +8,52 @@ integration with it.
 Generating opam files
 =====================
 
-Dune is able to use metadata specified in the ``dune-project`` file to cross
-reference it with the information in the user written ``.opam`` file. To enable
-this integration, a user needs to add an ``(opam ..)`` field to the dune-project
-file.
+Dune is able to use metadata specified in the ``dune-project`` file to generate
+``.opam`` files. To enable this integration, add the following field to the
+``dune-project`` file:
 
-The fields that dune uses for this purpose are:
+.. code:: scheme
+
+   (generate_opam_files true)
+
+Dune uses the following global fields to set the metadata for all packages
+defined in the project:
 
-- ``(license <name>)`` - Specified the license of the project
+- ``(license <name>)`` - Specifies the license of the project, ideally as an identifier from the `SPDX License List <https://spdx.org/licenses/>`__
 
 - ``(authors <authors>)`` - A list of authors
 
+- ``(maintainers <maintainers>)`` - A list of maintainers
+
 - ``(source <source>)`` - where the source is specified two ways:
   ``(github <user/repo>)`` or ``(uri <uri>)``
 
-To enable dune suggesting corrections to the opam stanza, the user must specify
-an ``(opam <fields>)`` with the fields:
+- ``(bug_reports <url>)`` - Where to report bugs. This defaults to the GitHub issue tracker if the source is specified as a GitHub repository
+
+- ``(homepage <url>)`` - The homepage of the project
+
+Package specific information is specified in the ``(package <package>)`` stanza.
+It contains the following fields:
+
+- ``(name <string>)`` is the name of the package. This must be specified.
+
+- ``(synopsis <string>)`` is a short package description
+
+- ``(description <string>)`` is a longer package description
+
+- ``(depends <dep-specification>)`` are package dependencies
 
-- ``(tags <tags>)`` - Specify the list of tags for all packages
-- ``(depends <dep-specification>)`` - The list of dependencies shared by all opam packages
-  in this dune project
-- ``(conflicts <dep-specification>)`` - The list of conflicts shared by all opam
-  packages in this dune project
-- ``(package <package>)`` - the list of packages in this project and their
-  individual metadata.
+- ``(conflicts <dep-specification)`` are package conflicts
+
+- ``(depopts <dep-specification)`` are optional package dependencies
+
+- ``(tags <tags>)`` are the list of tags for the package
 
 The list of dependencies ``<dep-specification>`` is modeled after opam's own
 language: The syntax is as a list of the following elements:
 
 .. code::
+
    op := '=' | '<' | '>' | '<>' | '>=' | '<='
 
    stage := :with_test | :build | :dev
@@ -51,17 +68,6 @@ language: The syntax is as a list of the following elements:
 
    dep-specification = dep+
 
-The `(package <package>)` field contains the fields:
-
-- ``(name <string>)`` is the name of the package
-
-- ``(synopsis <string>)`` is a short package description
-
-- ``(description <string>)`` is a longer package description
-
-- ``(depends <dep-specification>)`` are package specific dependencies
-
-- ``(conflicts <dep-specification)`` are package specific conflicts
 
 Here's a complete example of a dune file with opam metadata specification:
 
@@ -72,32 +78,41 @@ Here's a complete example of a dune file with opam metadata specification:
    (source (github mirage/ocaml-cohttp))
    (license ISC)
    (authors "Anil Madhavapeddy" "Rudi Grinberg")
-
-   (opam
-     (tags org:mirage org:dune)
-     (depends
-     (ocaml (>= 4.06.0))
-     (cohttp (>= 1.0.0)))
-     (package
-       (name cohttp)
-       (synopsis "An OCaml library for HTTP clients and servers")
-       (description "A longer description")
-       (depends
-         (alcotest :with-test)
-         (dune (and :build (> 1.5)))
-         (foo (and :dev (> 1.5) (< 2.0)))
-         (uri (>= 1.9.0))
-         (uri (< 2.0.0))
-         (fieldslib (> v0.12))
-         (fieldslib (< v0.13))))
-     (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))
-         (async (< v0.12)))))
+   (maintainers "team@mirage.org")
+
+   (package
+    (name cohttp)
+    (synopsis "An OCaml library for HTTP clients and servers")
+    (description "A longer description")
+    (depends
+     (alcotest :with-test)
+     (dune (and :build (> 1.5)))
+     (foo (and :dev (> 1.5) (< 2.0)))
+     (uri (>= 1.9.0))
+     (uri (< 2.0.0))
+     (fieldslib (> v0.12))
+     (fieldslib (< v0.13))))
+
+   (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))
+     (async (< v0.12))))
+
+Opam Template
+-------------
+
+A user may want to manually fill in some field in the opam file. In these
+situations, dune provides an escape hatch in the form of a user written opam
+template. An opam template must be named ``<package>.opam.template`` and should
+be a syntactically valid opam file. Any field defined in this template file will
+be taken as is by dune and never overwritten.
+
+*Note* the template file cannot be generated by a rule and must be available in
+the source tree.
 
 .. _opam: https://opam.ocaml.org/

dune-project

@@ -2,23 +2,24 @@
 (name dune)
 
 (implicit_transitive_deps false)
+(generate_opam_files true)
 
 (license MIT)
+(maintainers "Jane Street Group, LLC <opensource@janestreet.com>")
 (authors "Jane Street Group, LLC <opensource@janestreet.com>")
 (source (github ocaml/dune))
 
-(opam
- (package
-  (name dune)
-  (depends
-   (ocaml (>= 4.02))
-   base-unix
-   base-threads)
-  (conflicts
-   (jbuilder (<> "transition"))
-   (odoc (< 1.3.0)))
-  (synopsis "Fast, portable and opinionated build system")
-  (description "
+(package
+ (name dune)
+ (depends
+  (ocaml (>= 4.02))
+  base-unix
+  base-threads)
+ (conflicts
+  (jbuilder (<> "transition"))
+  (odoc (< 1.3.0)))
+ (synopsis "Fast, portable and opinionated build system")
+ (description "
 dune is a build system that was designed to simplify the release of
 Jane Street packages. It reads metadata from \"dune\" files following a
 very simple s-expression syntax.
@@ -35,4 +36,4 @@ It also supports multi-context builds, such as building against
 several opam roots/switches simultaneously. This helps maintaining
 packages across several versions of OCaml and gives cross-compilation
 for free.
-")))
+"))

dune.opam

@@ -1,28 +1,13 @@
 opam-version: "2.0"
-maintainer: "opensource@janestreet.com"
+maintainer: ["Jane Street Group, LLC <opensource@janestreet.com>"]
 authors: ["Jane Street Group, LLC <opensource@janestreet.com>"]
-homepage: "https://github.com/ocaml/dune"
 bug-reports: "https://github.com/ocaml/dune/issues"
-dev-repo: "git+https://github.com/ocaml/dune.git"
+homepage: "https://github.com/ocaml/dune"
 license: "MIT"
-depends: [
-  "ocaml" {>= "4.02"}
-  "base-unix"
-  "base-threads"
-]
-build: [
-  # opam 2 sets OPAM_SWITCH_PREFIX, so we don't need a hardcoded path
-  ["ocaml" "configure.ml" "--libdir" lib] {opam-version < "2"}
-  ["ocaml" "bootstrap.ml"]
-  ["./boot.exe" "--release" "--subst"] {pinned}
-  ["./boot.exe" "--release" "-j" jobs]
-]
-conflicts: [
-  "jbuilder" {!= "transition"}
-  "odoc" {< "1.3.0"}
-]
+dev-repo: "git+https://github.com/ocaml/dune.git"
 synopsis: "Fast, portable and opinionated build system"
 description: """
+
 dune is a build system that was designed to simplify the release of
 Jane Street packages. It reads metadata from "dune" files following a
 very simple s-expression syntax.
@@ -40,3 +25,19 @@ several opam roots/switches simultaneously. This helps maintaining
 packages across several versions of OCaml and gives cross-compilation
 for free.
 """
+depends: [
+  "ocaml" {>= "4.02"}
+  "base-unix"
+  "base-threads"
+]
+conflicts: [
+  "jbuilder" {!= "transition"}
+  "odoc" {< "1.3.0"}
+]
+build: [
+  # opam 2 sets OPAM_SWITCH_PREFIX, so we don't need a hardcoded path
+  ["ocaml" "configure.ml" "--libdir" lib] {opam-version < "2"}
+  ["ocaml" "bootstrap.ml"]
+  ["./boot.exe" "--release" "--subst"] {pinned}
+  ["./boot.exe" "--release" "-j" jobs]
+]

dune.opam.template

@@ -0,0 +1,7 @@
+build: [
+  # opam 2 sets OPAM_SWITCH_PREFIX, so we don't need a hardcoded path
+  ["ocaml" "configure.ml" "--libdir" lib] {opam-version < "2"}
+  ["ocaml" "bootstrap.ml"]
+  ["./boot.exe" "--release" "--subst"] {pinned}
+  ["./boot.exe" "--release" "-j" jobs]
+]