Merge changes I462a8cf0,I3b0bcea3,I2acd56e7,Ifc149764,I9e2ef170 into main

* changes:
  docs: linkify nix3-build mention in nix-build.md
  build: make internal-api-docs PHONY
  cleanup lookupFileArg
  add docstring to lookupFileArg
  add libcmd test for lookupFileArg

2 files changed, 38 insertions, 16 deletions

diff --git a/src/libcmd/common-eval-args.cc b/src/libcmd/common-eval-args.cc
index 94a4b7922..9beea5aa2 100644
--- a/src/libcmd/common-eval-args.cc
+++ b/src/libcmd/common-eval-args.cc
@@ -164,28 +164,30 @@ Bindings * MixEvalArgs::getAutoArgs(EvalState & state)
     return res.finish();
 }
 
-SourcePath lookupFileArg(EvalState & state, std::string_view s)
+SourcePath lookupFileArg(EvalState & state, std::string_view fileArg)
 {
-    if (EvalSettings::isPseudoUrl(s)) {
-        auto storePath = fetchers::downloadTarball(
-            state.store, EvalSettings::resolvePseudoUrl(s), "source", false).tree.storePath;
+    if (EvalSettings::isPseudoUrl(fileArg)) {
+        auto const url = EvalSettings::resolvePseudoUrl(fileArg);
+        auto const downloaded = fetchers::downloadTarball(
+            state.store,
+            url,
+            /* name */ "source",
+            /* locked */ false
+        );
+        StorePath const storePath = downloaded.tree.storePath;
         return state.rootPath(CanonPath(state.store->toRealPath(storePath)));
-    }
-
-    else if (s.starts_with("flake:")) {
+    } else if (fileArg.starts_with("flake:")) {
         experimentalFeatureSettings.require(Xp::Flakes);
-        auto flakeRef = parseFlakeRef(std::string(s.substr(6)), {}, true, false);
+        static constexpr size_t FLAKE_LEN = std::string_view("flake:").size();
+        auto flakeRef = parseFlakeRef(std::string(fileArg.substr(FLAKE_LEN)), {}, true, false);
         auto storePath = flakeRef.resolve(state.store).fetchTree(state.store).first.storePath;
         return state.rootPath(CanonPath(state.store->toRealPath(storePath)));
-    }
-
-    else if (s.size() > 2 && s.at(0) == '<' && s.at(s.size() - 1) == '>') {
-        Path p(s.substr(1, s.size() - 2));
+    } else if (fileArg.size() > 2 && fileArg.at(0) == '<' && fileArg.at(fileArg.size() - 1) == '>') {
+        Path p(fileArg.substr(1, fileArg.size() - 2));
         return state.findFile(p);
+    } else {
+        return state.rootPath(CanonPath::fromCwd(fileArg));
     }
-
-    else
-        return state.rootPath(CanonPath::fromCwd(s));
 }
 
 }
diff --git a/src/libcmd/common-eval-args.hh b/src/libcmd/common-eval-args.hh
index 6359b2579..08a4b65e4 100644
--- a/src/libcmd/common-eval-args.hh
+++ b/src/libcmd/common-eval-args.hh
@@ -28,6 +28,26 @@ private:
     std::map<std::string, std::string> autoArgs;
 };
 
-SourcePath lookupFileArg(EvalState & state, std::string_view s);
+/** @brief Resolve an argument that is generally a file, but could be something that
+ * is easy to resolve to a file, like a <lookup path> or a tarball URL.
+ *
+ * In particular, this will resolve and fetch pseudo-URLs starting with
+ * @c channel:, flakerefs starting with @c flake:, and anything that
+ * @ref nix::fetchers::downloadTarball() can take.
+ *
+ * Non-absolute files are looked up relative to the current directory(?)
+ * FIXME: the process's current directory or EvalState's current directory?
+ *
+ * @param state The nix::EvalState to base settings, store, and nixPath from.
+ *
+ * @param fileArg The the path-ish to resolve.
+ *
+ * @return A nix::SourcePath to the resolved and fetched file.
+ *
+ * @exception nix::FileTransferError from nix::fetchers::downloadTarball(). Probably others.
+ *
+ * @exception nix::ThrownError for failed search path lookup. Probably others.
+ */
+SourcePath lookupFileArg(EvalState & state, std::string_view fileArg);
 
 }