Record change and document variants

Signed-off-by: Lucas Pluvinage <lucas.pluvinage@gmail.com>

CHANGES.md

@@ -1,6 +1,11 @@
 unreleased
 ----------
 
+- Redesign of the library variant feature according to the #2134 proposal. The
+  set of variants is now computed when the virtual library is installed.
+  Introducing a new `external_variant` stanza. (#2169, @TheLortex, review by
+  @diml)
+
 - Restricted the set of variables available for expansion in the destination
   filename of `install` stanza to simplify implementation and avoid dependency
   cycles. (#2073, @aalekseyev, @diml)

doc/dune-files.rst

@@ -983,6 +983,23 @@ run this toplevel with:
 
    $ dune exec ./tt.exe
 
+external_variant
+-----------------
+
+The ``external_variant`` allow to declare a tagged implementation that does not
+live inside the virtual library project.
+
+.. code:: scheme
+
+   (external_variant
+    (variant foo)
+    (implementation lib-foo)
+    (virtual_library vlib))
+
+This will add `lib-foo` to the list of known implementations of `vlib`. For more
+details see :ref:`dune-variants`
+
+
 Common items
 ============
 

doc/variants.rst

@@ -76,11 +76,13 @@ implementation for every virtual library that we've used:
      clock_unix ;; leaving this dependency will make dune loudly complain
      calendar))
 
+.. _dune-variants:
+
 Variants
 ========
 
 This feature is still under development and may change with new dune
-releases. You need to write ``(using library_variants 0.1)`` in your
+releases. You need to write ``(using library_variants 0.2)`` in your
 ``dune-project`` file to unlock it.
 
 When building a binary, implementations can be selected using a set of variants
@@ -108,6 +110,21 @@ implementation would have the following configuration:
     (implements time)
     (variant js))
 
+Since dune 1.11.0, the list of available variants is computed while building
+the virtual library. This means only variant implementations that are part of
+the same project are implicitely taken into account. It's possible to declare
+an external implementation by using the `external_variant` stanza in the
+virtual library scope.
+
+.. code:: scheme
+
+   (external_variant
+    (variant foo)
+    (implementation lib-foo)
+    (virtual_library vlib))
+
+This will add `lib-foo` to the list of known implementations of `vlib`.
+
 Default implementation
 ======================