Merge remote-tracking branch 'upstream/master' into path-info

Also improve content-address.hh API docs.

1 files changed, 101 insertions, 71 deletions

diff --git a/src/libcmd/installables.hh b/src/libcmd/installables.hh
index be77fdc81..b6efc0f17 100644
--- a/src/libcmd/installables.hh
+++ b/src/libcmd/installables.hh
@@ -4,9 +4,7 @@
 #include "path.hh"
 #include "outputs-spec.hh"
 #include "derived-path.hh"
-#include "eval.hh"
 #include "store-api.hh"
-#include "flake/flake.hh"
 #include "build-result.hh"
 
 #include <optional>
@@ -14,122 +12,156 @@
 namespace nix {
 
 struct DrvInfo;
-struct SourceExprCommand;
-
-namespace eval_cache { class EvalCache; class AttrCursor; }
-
-struct App
-{
-    std::vector<DerivedPath> context;
-    Path program;
-    // FIXME: add args, sandbox settings, metadata, ...
-};
-
-struct UnresolvedApp
-{
-    App unresolved;
-    App resolve(ref<Store> evalStore, ref<Store> store);
-};
 
 enum class Realise {
-    /* Build the derivation. Postcondition: the
-       derivation outputs exist. */
+    /**
+     * Build the derivation.
+     *
+     * Postcondition: the derivation outputs exist.
+     */
     Outputs,
-    /* Don't build the derivation. Postcondition: the store derivation
-       exists. */
+    /**
+     * Don't build the derivation.
+     *
+     * Postcondition: the store derivation exists.
+     */
     Derivation,
-    /* Evaluate in dry-run mode. Postcondition: nothing. */
-    // FIXME: currently unused, but could be revived if we can
-    // evaluate derivations in-memory.
+    /**
+     * Evaluate in dry-run mode.
+     *
+     * Postcondition: nothing.
+     *
+     * \todo currently unused, but could be revived if we can evaluate
+     * derivations in-memory.
+     */
     Nothing
 };
 
-/* How to handle derivations in commands that operate on store paths. */
+/**
+ * How to handle derivations in commands that operate on store paths.
+ */
 enum class OperateOn {
-    /* Operate on the output path. */
+    /**
+     * Operate on the output path.
+     */
     Output,
-    /* Operate on the .drv path. */
+    /**
+     * Operate on the .drv path.
+     */
     Derivation
 };
 
+/**
+ * Extra info about a DerivedPath
+ *
+ * Yes, this is empty, but that is intended. It will be sub-classed by
+ * the subclasses of Installable to allow those to provide more info.
+ * Certain commands will make use of this info.
+ */
 struct ExtraPathInfo
 {
-    std::optional<NixInt> priority;
-    std::optional<FlakeRef> originalRef;
-    std::optional<FlakeRef> resolvedRef;
-    std::optional<std::string> attrPath;
-    // FIXME: merge with DerivedPath's 'outputs' field?
-    std::optional<ExtendedOutputsSpec> extendedOutputsSpec;
+    virtual ~ExtraPathInfo() = default;
 };
 
-/* A derived path with any additional info that commands might
-   need from the derivation. */
+/**
+ * A DerivedPath with \ref ExtraPathInfo "any additional info" that
+ * commands might need from the derivation.
+ */
 struct DerivedPathWithInfo
 {
     DerivedPath path;
-    ExtraPathInfo info;
+    ref<ExtraPathInfo> info;
 };
 
+/**
+ * Like DerivedPathWithInfo but extending BuiltPath with \ref
+ * ExtraPathInfo "extra info" and also possibly the \ref BuildResult
+ * "result of building".
+ */
 struct BuiltPathWithResult
 {
     BuiltPath path;
-    ExtraPathInfo info;
+    ref<ExtraPathInfo> info;
     std::optional<BuildResult> result;
 };
 
+/**
+ * Shorthand, for less typing and helping us keep the choice of
+ * collection in sync.
+ */
 typedef std::vector<DerivedPathWithInfo> DerivedPathsWithInfo;
 
+struct Installable;
+
+/**
+ * Shorthand, for less typing and helping us keep the choice of
+ * collection in sync.
+ */
+typedef std::vector<ref<Installable>> Installables;
+
+/**
+ * Installables are the main positional arguments for the Nix
+ * Command-line.
+ *
+ * This base class is very flexible, and just assumes and the
+ * Installable refers to a collection of \ref DerivedPath "derived paths" with
+ * \ref ExtraPathInfo "extra info".
+ */
 struct Installable
 {
     virtual ~Installable() { }
 
+    /**
+     * What Installable is this?
+     *
+     * Prints back valid CLI syntax that would result in this same
+     * installable. It doesn't need to be exactly what the user wrote,
+     * just something that means the same thing.
+     */
     virtual std::string what() const = 0;
 
+    /**
+     * Get the collection of \ref DerivedPathWithInfo "derived paths
+     * with info" that this \ref Installable instalallable denotes.
+     *
+     * This is the main method of this class
+     */
     virtual DerivedPathsWithInfo toDerivedPaths() = 0;
 
+    /**
+     * A convenience wrapper of the above for when we expect an
+     * installable to produce a single \ref DerivedPath "derived path"
+     * only.
+     *
+     * If no or multiple \ref DerivedPath "derived paths" are produced,
+     * and error is raised.
+     */
     DerivedPathWithInfo toDerivedPath();
 
-    UnresolvedApp toApp(EvalState & state);
-
-    virtual std::pair<Value *, PosIdx> toValue(EvalState & state)
-    {
-        throw Error("argument '%s' cannot be evaluated", what());
-    }
-
-    /* Return a value only if this installable is a store path or a
-       symlink to it. */
+    /**
+     * Return a value only if this installable is a store path or a
+     * symlink to it.
+     *
+     * \todo should we move this to InstallableDerivedPath? It is only
+     * supposed to work there anyways. Can always downcast.
+     */
     virtual std::optional<StorePath> getStorePath()
     {
         return {};
     }
 
-    /* Get a cursor to each value this Installable could refer to. However
-       if none exists, throw exception instead of returning empty vector. */
-    virtual std::vector<ref<eval_cache::AttrCursor>>
-    getCursors(EvalState & state);
-
-    /* Get the first and most preferred cursor this Installable could refer
-       to, or throw an exception if none exists. */
-    virtual ref<eval_cache::AttrCursor>
-    getCursor(EvalState & state);
-
-    virtual FlakeRef nixpkgsFlakeRef() const
-    {
-        return FlakeRef::fromAttrs({{"type","indirect"}, {"id", "nixpkgs"}});
-    }
-
     static std::vector<BuiltPathWithResult> build(
         ref<Store> evalStore,
         ref<Store> store,
         Realise mode,
-        const std::vector<std::shared_ptr<Installable>> & installables,
+        const Installables & installables,
         BuildMode bMode = bmNormal);
 
-    static std::vector<std::pair<std::shared_ptr<Installable>, BuiltPathWithResult>> build2(
+    static std::vector<std::pair<ref<Installable>, BuiltPathWithResult>> build2(
         ref<Store> evalStore,
         ref<Store> store,
         Realise mode,
-        const std::vector<std::shared_ptr<Installable>> & installables,
+        const Installables & installables,
         BuildMode bMode = bmNormal);
 
     static std::set<StorePath> toStorePaths(
@@ -137,18 +169,18 @@ struct Installable
         ref<Store> store,
         Realise mode,
         OperateOn operateOn,
-        const std::vector<std::shared_ptr<Installable>> & installables);
+        const Installables & installables);
 
     static StorePath toStorePath(
         ref<Store> evalStore,
         ref<Store> store,
         Realise mode,
         OperateOn operateOn,
-        std::shared_ptr<Installable> installable);
+        ref<Installable> installable);
 
     static std::set<StorePath> toDerivations(
         ref<Store> store,
-        const std::vector<std::shared_ptr<Installable>> & installables,
+        const Installables & installables,
         bool useDeriver = false);
 
     static BuiltPaths toBuiltPaths(
@@ -156,9 +188,7 @@ struct Installable
         ref<Store> store,
         Realise mode,
         OperateOn operateOn,
-        const std::vector<std::shared_ptr<Installable>> & installables);
+        const Installables & installables);
 };
 
-typedef std::vector<std::shared_ptr<Installable>> Installables;
-
 }