diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index 66e4628c0..88916bb50 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -295,6 +295,25 @@ [path]: ./language/values.md#type-path [attribute name]: ./language/values.md#attribute-set +- [base directory]{#gloss-base-directory} + + The location from which relative paths are resolved. + + - For expressions in a file, the base directory is the directory containing that file. + This is analogous to the directory of a [base URL](https://datatracker.ietf.org/doc/html/rfc1808#section-3.3). + + + + - For expressions written in command line arguments with [`--expr`](@docroot@/command-ref/opt-common.html#opt-expr), the base directory is the current working directory. + + [base directory]: #gloss-base-directory + - [experimental feature]{#gloss-experimental-feature} Not yet stabilized functionality guarded by named experimental feature flags. diff --git a/doc/manual/src/language/values.md b/doc/manual/src/language/values.md index 568542c0b..d4338e91e 100644 --- a/doc/manual/src/language/values.md +++ b/doc/manual/src/language/values.md @@ -97,8 +97,8 @@ is not a path: it's parsed as an expression that selects the attribute `sh` from the variable `builder`. If the file name is relative, i.e., if it does not begin with a slash, it is made - absolute at parse time relative to the directory of the Nix - expression that contained it. For instance, if a Nix expression in + absolute at parse time relative to the [base directory](@docroot@/glossary.md#gloss-base-directory). + For instance, if a Nix expression in `/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path is `/foo/xyzzy/fnord.nix`. @@ -107,7 +107,7 @@ e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user whose home directory is `/home/edolstra`. - For instance, evaluating `"${./foo.txt}"` will cause `foo.txt` in the current directory to be copied into the Nix store and result in the string `"/nix/store/-foo.txt"`. + For instance, evaluating `"${./foo.txt}"` will cause `foo.txt` in the base directory to be copied into the Nix store and result in the string `"/nix/store/-foo.txt"`. Note that the Nix language assumes that all input files will remain _unchanged_ while evaluating a Nix expression. For example, assume you used a file path in an interpolated string during a `nix repl` session. diff --git a/src/libcmd/common-eval-args.hh b/src/libcmd/common-eval-args.hh index 25ce5b9da..0cb9ddbca 100644 --- a/src/libcmd/common-eval-args.hh +++ b/src/libcmd/common-eval-args.hh @@ -38,6 +38,9 @@ private: std::map autoArgs; }; +/** + * @param baseDir Optional [base directory](https://nixos.org/manual/nix/unstable/glossary#gloss-base-directory) + */ SourcePath lookupFileArg(EvalState & state, std::string_view s, const Path * baseDir = nullptr); } diff --git a/src/libexpr/flake/flakeref.hh b/src/libexpr/flake/flakeref.hh index 5d78f49b6..04c812ed0 100644 --- a/src/libexpr/flake/flakeref.hh +++ b/src/libexpr/flake/flakeref.hh @@ -68,24 +68,39 @@ struct FlakeRef std::ostream & operator << (std::ostream & str, const FlakeRef & flakeRef); +/** + * @param baseDir Optional [base directory](https://nixos.org/manual/nix/unstable/glossary#gloss-base-directory) + */ FlakeRef parseFlakeRef( const std::string & url, const std::optional & baseDir = {}, bool allowMissing = false, bool isFlake = true); +/** + * @param baseDir Optional [base directory](https://nixos.org/manual/nix/unstable/glossary#gloss-base-directory) + */ std::optional maybeParseFlake( const std::string & url, const std::optional & baseDir = {}); +/** + * @param baseDir Optional [base directory](https://nixos.org/manual/nix/unstable/glossary#gloss-base-directory) + */ std::pair parseFlakeRefWithFragment( const std::string & url, const std::optional & baseDir = {}, bool allowMissing = false, bool isFlake = true); +/** + * @param baseDir Optional [base directory](https://nixos.org/manual/nix/unstable/glossary#gloss-base-directory) + */ std::optional> maybeParseFlakeRefWithFragment( const std::string & url, const std::optional & baseDir = {}); +/** + * @param baseDir Optional [base directory](https://nixos.org/manual/nix/unstable/glossary#gloss-base-directory) + */ std::tuple parseFlakeRefWithFragmentAndExtendedOutputsSpec( const std::string & url, const std::optional & baseDir = {}, diff --git a/src/libutil/args.hh b/src/libutil/args.hh index 4b2e1d960..7759b74a9 100644 --- a/src/libutil/args.hh +++ b/src/libutil/args.hh @@ -41,7 +41,7 @@ public: virtual std::string doc() { return ""; } /** - * @brief Get the base directory for the command. + * @brief Get the [base directory](https://nixos.org/manual/nix/unstable/glossary#gloss-base-directory) for the command. * * @return Generally the working directory, but in case of a shebang * interpreter, returns the directory of the script.