lib.derivations: add warnOnInstantiate

lib/default.nix

@@ -121,7 +121,7 @@ let
     inherit (self.customisation) overrideDerivation makeOverridable
       callPackageWith callPackagesWith extendDerivation hydraJob
       makeScope makeScopeWithSplicing makeScopeWithSplicing';
-    inherit (self.derivations) lazyDerivation optionalDrvAttr;
+    inherit (self.derivations) lazyDerivation optionalDrvAttr warnOnInstantiate;
     inherit (self.meta) addMetaAttrs dontDistribute setName updateName
       appendToName mapDerivationAttrset setPrio lowPrio lowPrioSet hiPrio
       hiPrioSet licensesSpdx getLicenseFromSpdxId getLicenseFromSpdxIdOr

lib/derivations.nix

@@ -2,8 +2,10 @@
 
 let
   inherit (lib)
+    filterAttrs
     genAttrs
     isString
+    mapAttrs
     throwIfNot
     ;
 
@@ -206,4 +208,38 @@ in
   optionalDrvAttr =
     cond:
     value: if cond then value else null;
+
+  /**
+    Wrap a derivation such that instantiating it produces a warning.
+
+    All attributes apart from `meta`, `name`, and `type` (which are used by
+    `nix search`) will be wrapped in `lib.warn`.
+
+    # Inputs
+
+    `msg`
+    : The warning message to emit (via `lib.warn`).
+
+    `drv`
+    : The derivation to wrap.
+
+    # Examples
+    :::{.example}
+    ## `lib.derivations.warnOnInstantiate` usage example
+
+    ```nix
+    {
+      myPackage = warnOnInstantiate "myPackage has been renamed to my-package" my-package;
+    }
+    ```
+
+    :::
+  */
+  warnOnInstantiate =
+    msg: drv:
+    let
+      drvToWrap = filterAttrs (name: value: !builtins.elem name [ "meta" "name" "type" ]) drv;
+    in
+    drv
+    // mapAttrs (_: lib.warn msg) drvToWrap;
 }