Add bultin support for the 'deprecated' flag

doc/pages/Manual.md

@@ -1060,6 +1060,10 @@ files.
 
       Note that this behaviour is disabled when a flagged version of the package
       is already installed.
+    - <a id="opamflag-deprecated">`deprecated`</a>: this flag is equivalent to
+      [`avoid-version`](#opamflag-avoid-version) except for the addition of a
+      deprecation message after the package is installed as well as marked as
+      deprecated in the solution shown to the user upon installation.
 
 - <a id="opamfield-features">
   `features: [ <ident> { <pkgname> { <filtered-package-formula> } ... } { <string> } ... ]`

master_changes.md

@@ -202,6 +202,7 @@ users)
   * Enable cudf preprocessing for (co)insallability calculation, resulting in a x20 speedup [@AltGr]
   * Make sure that `--best-effort` only installs root package versions that where requested [#4796 @LasseBlaauwbroek]
   * Ask users to report errors when no explanations are given to them [#4981 @kit-ty-kate]
+  * Add bultin support for the 'deprecated' flag.  Any packages flagged with deprecated would be avoided by the solver unless there is no other choice (e.g. some user wants to install package a which depends on b which is deprecated) If it is installed, show up a note after installation notifying the user that the package is deprecated. [#4523 @kit-ty-kate]
 
 ## Client
   * Check whether the repository might need updating more often [#4935 @kit-ty-kate]
@@ -254,7 +255,8 @@ users)
   * Add source test [#5101 @rjbou]
   * Add upgrade (and update) test [#5106 @rjbou]
   * Update var-option test with no switch examples [#5025]
-  * Escape for cmdliner.1.1.1 output chane [#5131 @rjbou]
+  * Escape for cmdliner.1.1.1 output change [#5131 @rjbou]
+  * Add deprectaed flag test [#4523 @kit-ty-kate]
 ### Engine
   * Add `opam-cat` to normalise opam file printing [#4763 @rjbou @dra27] [2.1.0~rc2 #4715]
   * Fix meld reftest: open only with failing ones [#4913 @rjbou]

src/client/opamSolution.ml

@@ -40,6 +40,10 @@ let post_message ?(failed=false) st action =
     in
     let messages =
       let filter_env = OpamPackageVar.resolve ~opam ~local:local_variables st in
+      (if OpamFile.OPAM.has_flag Pkgflag_Deprecated opam then
+        ["Note: This package is deprecated."]
+      else
+        []) @
       OpamStd.List.filter_map (fun (message,filter) ->
           if OpamFilter.opt_eval_to_bool filter_env filter then
             Some (OpamFilter.expand_string ~default:(fun _ -> "")
@@ -1288,9 +1292,17 @@ let apply ?ask t ~requested ?add_roots ?(assume_built=false)
           else None
         )  messages in
       let append nv =
-        (* mark pinned packages with a star *)
-        if OpamPackage.Set.mem nv t.pinned then " (pinned)"
-        else ""
+        let pinned =
+          (* mark pinned packages *)
+          if OpamPackage.Set.mem nv t.pinned then " (pinned)"
+          else ""
+        and deprecated =
+          (* mark deprecated packages *)
+          let opam = OpamSwitchState.opam new_state nv in
+          if OpamFile.OPAM.has_flag Pkgflag_Deprecated opam then " (deprecated)"
+          else ""
+        in
+        pinned ^ deprecated
       in
       OpamSolver.print_solution ~messages ~append
         ~requested:names ~reinstall:(Lazy.force t.reinstall)

src/format/opamFile.ml

@@ -3231,6 +3231,7 @@ module OPAM = struct
              | Pkgflag_Compiler
              | Pkgflag_Conf
              | Pkgflag_AvoidVersion
+             | Pkgflag_Deprecated
              | Pkgflag_Unknown _
                -> false)
             t.flags);

src/format/opamTypes.mli

@@ -117,6 +117,9 @@ type package_flag =
                      .install, but likely has depexts *)
   | Pkgflag_AvoidVersion (** This version of the package will only be installed if
                              strictly required *)
+  | Pkgflag_Deprecated (** This version of the package will only be installed if
+                           strictly required and will print a deprecation
+                           warning *)
   | Pkgflag_Unknown of string (** Used for error reporting, otherwise ignored *)
 
 (** At some point we want to abstract so that the same functions can be used

src/format/opamTypesBase.ml

@@ -158,6 +158,7 @@ let string_of_pkg_flag = function
   | Pkgflag_Compiler -> "compiler"
   | Pkgflag_Conf -> "conf"
   | Pkgflag_AvoidVersion -> "avoid-version"
+  | Pkgflag_Deprecated -> "deprecated"
   | Pkgflag_Unknown s -> s
 
 let pkg_flag_of_string = function
@@ -167,6 +168,7 @@ let pkg_flag_of_string = function
   | "compiler" -> Pkgflag_Compiler
   | "conf" -> Pkgflag_Conf
   | "avoid-version" -> Pkgflag_AvoidVersion
+  | "deprecated" -> Pkgflag_Deprecated
   | s -> Pkgflag_Unknown s
 
 let action_contents = function

src/state/opamSwitchState.ml

@@ -859,11 +859,16 @@ let get_conflicts st packages opams_map =
 
 let avoid_version st nv =
   let open OpamStd.Option.Op in
-  OpamFile.OPAM.has_flag Pkgflag_AvoidVersion (opam st nv) &&
-  not ((OpamPackage.package_of_name_opt st.installed nv.name >>=
-        (fun nv -> OpamPackage.Map.find_opt nv st.installed_opams) >>|
-        OpamFile.OPAM.has_flag Pkgflag_AvoidVersion)
-       +! false)
+  let opam = opam st nv in
+  let has_avoid_flag opam =
+    OpamFile.OPAM.has_flag Pkgflag_AvoidVersion opam
+    || OpamFile.OPAM.has_flag Pkgflag_Deprecated opam
+  in
+  has_avoid_flag opam
+  && not ((OpamPackage.package_of_name_opt st.installed nv.name >>=
+           (fun nv -> OpamPackage.Map.find_opt nv st.installed_opams) >>|
+           has_avoid_flag)
+          +! false)
 
 let universe st
     ?(test=OpamStateConfig.(!r.build_test))

tests/reftests/deprecated.test

@@ -0,0 +1,160 @@
+N0REP0
+### <pkg:a.2>
+opam-version: "2.0"
+flags: deprecated
+### opam switch create default --empty
+### OPAMFAKE=1
+### OPAMYES=1
+### opam install a --show
+The following actions would be faked:
+=== install 1 package
+  - install a 2 (deprecated)
+### <pkg:a.1>
+opam-version: "2.0"
+### opam install a
+The following actions will be faked:
+=== install 1 package
+  - install a 1
+
+<><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><><><>
+Faking installation of a.1
+Done.
+### opam upgrade a
+Everything as up-to-date as possible (run with --verbose to show unavailable upgrades).
+
+The following packages are not being upgraded because the new versions conflict with other installed packages:
+  - a.2
+However, you may "opam upgrade" these packages explicitly, which will ask permission to downgrade or uninstall the conflicting packages.
+Nothing to do.
+### <pkg:a.1.1>
+opam-version: "2.0"
+### opam upgrade a
+The following actions will be faked:
+=== upgrade 1 package
+  - upgrade a 1 to 1.1
+
+<><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><><><>
+Faking installation of a.1.1
+Done.
+### <pkg:a.3>
+opam-version: "2.0"
+### opam upgrade a
+The following actions will be faked:
+=== upgrade 1 package
+  - upgrade a 1.1 to 3
+
+<><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><><><>
+Faking installation of a.3
+Done.
+### opam install a.2
+The following actions will be faked:
+=== downgrade 1 package
+  - downgrade a 3 to 2 (deprecated)
+
+<><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><><><>
+Faking installation of a.2
+Done.
+
+<><> a.2 installed successfully <><><><><><><><><><><><><><><><><><><><><><><><>
+=> Note: This package is deprecated.
+### opam upgrade a
+The following actions will be faked:
+=== upgrade 1 package
+  - upgrade a 2 (deprecated) to 3
+
+<><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><><><>
+Faking installation of a.3
+Done.
+### <pkg:b.1>
+opam-version: "2.0"
+depends: "a"
+### <pkg:b.2>
+opam-version: "2.0"
+depends: "a" {= "2"}
+### opam install b
+The following actions will be faked:
+=== install 1 package
+  - install b 1
+
+<><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><><><>
+Faking installation of b.1
+Done.
+### opam upgrade
+Everything as up-to-date as possible (run with --verbose to show unavailable upgrades).
+
+The following packages are not being upgraded because the new versions conflict with other installed packages:
+  - b.2
+However, you may "opam upgrade" these packages explicitly, which will ask permission to downgrade or uninstall the conflicting packages.
+Nothing to do.
+### opam upgrade b
+The following actions will be faked:
+=== downgrade 1 package
+  - downgrade a 3 to 2 (deprecated) [required by b]
+=== upgrade 1 package
+  - upgrade   b 1 to 2
+
+<><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><><><>
+Faking installation of a.2
+Faking installation of b.2
+Done.
+
+<><> a.2 installed successfully <><><><><><><><><><><><><><><><><><><><><><><><>
+=> Note: This package is deprecated.
+### opam upgrade
+The following actions will be faked:
+=== downgrade 1 package
+  - downgrade b 2 to 1              [uses a]
+=== upgrade 1 package
+  - upgrade   a 2 (deprecated) to 3
+
+<><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><><><>
+Faking installation of a.3
+Faking installation of b.1
+Done.
+### <pkg:a.4>
+opam-version: "2.0"
+flags: deprecated
+### <pkg:b.3>
+opam-version: "2.0"
+flags: deprecated
+### opam upgrade
+Everything as up-to-date as possible (run with --verbose to show unavailable upgrades).
+
+The following packages are not being upgraded because the new versions conflict with other installed packages:
+  - a.4
+  - b.3
+However, you may "opam upgrade" these packages explicitly, which will ask permission to downgrade or uninstall the conflicting packages.
+Nothing to do.
+### opam upgrade b.3
+The following actions will be faked:
+=== upgrade 1 package
+  - upgrade b 1 to 3 (deprecated)
+
+<><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><><><>
+Faking installation of b.3
+Done.
+
+<><> b.3 installed successfully <><><><><><><><><><><><><><><><><><><><><><><><>
+=> Note: This package is deprecated.
+### opam install a.2
+The following actions will be faked:
+=== downgrade 1 package
+  - downgrade a 3 to 2 (deprecated)
+
+<><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><><><>
+Faking installation of a.2
+Done.
+
+<><> a.2 installed successfully <><><><><><><><><><><><><><><><><><><><><><><><>
+=> Note: This package is deprecated.
+### opam upgrade
+The following actions will be faked:
+=== upgrade 1 package
+  - upgrade a 2 (deprecated) to 4 (deprecated)
+
+<><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><><><>
+Faking installation of a.4
+Done.
+
+<><> a.4 installed successfully <><><><><><><><><><><><><><><><><><><><><><><><>
+=> Note: This package is deprecated.

tests/reftests/dune.inc

@@ -186,6 +186,23 @@
    %{targets}
    (run ./run.exe %{bin:opam} %{dep:cudf-preprocess.test} %{read-lines:testing-env}))))
 
+(rule
+ (alias reftest-deprecated)
+ (action
+  (diff deprecated.test deprecated.out)))
+
+(alias
+ (name reftest)
+ (deps (alias reftest-deprecated)))
+
+(rule
+ (targets deprecated.out)
+ (deps root-N0REP0)
+ (action
+  (with-stdout-to
+   %{targets}
+   (run ./run.exe %{bin:opam} %{dep:deprecated.test} %{read-lines:testing-env}))))
+
 (rule
  (alias reftest-dot-install)
  (action