lix-project/lix-releng-staging
0
0
Fork 0
Code Packages Activity

Convert a bunch of comments in headers to Doxygen documentation

Browse source 
The internal API docs now contain more useful information.

Co-authored-by: Théophane Hufschmitt <7226587+thufschmitt@users.noreply.github.com>
This commit is contained in:
John Ericson 2023-03-25 19:12:44 -04:00
parent 10dc2e2e7c
commit 8cab89a94b
6 changed files with 756 additions and 394 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

72
src/libstore/content-address.hh
View file

@ -5,44 +5,75 @@
namespace nix {
/**
* An enumeration of the ways we can serialize file system objects.
*/
enum struct FileIngestionMethod : uint8_t {
/**
* Flat-file hashing. Directly ingest the contents of a single file
*/
Flat = false,
/**
* Recursive (or NAR) hashing. Serializes the file-system object in Nix
* Archive format and ingest that
*/
Recursive = true
};
/**
* Somewhat obscure, used by \ref Derivation derivations and
* `builtins.toFile` currently.
*/
struct TextHash {
/**
* Hash of the contents of the text/file.
*/
Hash hash;
};
/// Pair of a hash, and how the file system was ingested
/**
* For path computed by makeFixedOutputPath.
*/
struct FixedOutputHash {
/**
* How the file system objects are serialized
*/
FileIngestionMethod method;
/**
* Hash of that serialization
*/
Hash hash;
std::string printMethodAlgo() const;
};
/*
We've accumulated several types of content-addressed paths over the years;
fixed-output derivations support multiple hash algorithms and serialisation
methods (flat file vs NAR). Thus, ‘ca’ has one of the following forms:
* ‘text:sha256:<sha256 hash of file contents>’: For paths
computed by makeTextPath() / addTextToStore().
* ‘fixed:<r?>:<ht>:<h>’: For paths computed by
makeFixedOutputPath() / addToStore().
*/
/**
* We've accumulated several types of content-addressed paths over the
* years; fixed-output derivations support multiple hash algorithms and
* serialisation methods (flat file vs NAR). Thus, ‘ca’ has one of the
* following forms:
*
* - ‘text:sha256:<sha256 hash of file contents>’: For paths
* computed by Store::makeTextPath() / Store::addTextToStore().
*
* - ‘fixed:<r?>:<ht>:<h>’: For paths computed by
* Store::makeFixedOutputPath() / Store::addToStore().
*/
typedef std::variant<
TextHash, // for paths computed by makeTextPath() / addTextToStore
FixedOutputHash // for path computed by makeFixedOutputPath
TextHash,
FixedOutputHash
> ContentAddress;
/* Compute the prefix to the hash algorithm which indicates how the files were
ingested. */
/**
* Compute the prefix to the hash algorithm which indicates how the
* files were ingested.
*/
std::string makeFileIngestionPrefix(const FileIngestionMethod m);
/* Compute the content-addressability assertion (ValidPathInfo::ca)
for paths created by makeFixedOutputPath() / addToStore(). */
/**
* Compute the content-addressability assertion (ValidPathInfo::ca) for
* paths created by Store::makeFixedOutputPath() / Store::addToStore().
*/
std::string makeFixedOutputCA(FileIngestionMethod method, const Hash & hash);
std::string renderContentAddress(ContentAddress ca);
@ -65,6 +96,11 @@ struct FixedOutputHashMethod {
HashType hashType;
};
/**
* Ways of content addressing but not a complete ContentAddress.
*
* A ContentAddress without a Hash.
*/
typedef std::variant<
TextHashMethod,
FixedOutputHashMethod

348
src/libstore/derivations.hh
View file

@ -17,42 +17,72 @@ class Store;
/* Abstract syntax of derivations. */
/* The traditional non-fixed-output derivation type. */
/**
* The traditional non-fixed-output derivation type.
*/
struct DerivationOutputInputAddressed
{
StorePath path;
};
/* Fixed-output derivations, whose output paths are content addressed
according to that fixed output. */
/**
* Fixed-output derivations, whose output paths are content
* addressed according to that fixed output.
*/
struct DerivationOutputCAFixed
{
FixedOutputHash hash; /* hash used for expected hash computation */
/**
* hash used for expected hash computation
*/
FixedOutputHash hash;
/**
* Return the \ref StorePath "store path" corresponding to this output
*
* @param drvName The name of the derivation this is an output of, without the `.drv`.
* @param outputName The name of this output.
*/
StorePath path(const Store & store, std::string_view drvName, std::string_view outputName) const;
};
/* Floating-output derivations, whose output paths are content addressed, but
not fixed, and so are dynamically calculated from whatever the output ends
up being. */
/**
* Floating-output derivations, whose output paths are content
* addressed, but not fixed, and so are dynamically calculated from
* whatever the output ends up being.
* */
struct DerivationOutputCAFloating
{
/* information used for expected hash computation */
/**
* How the file system objects will be serialized for hashing
*/
FileIngestionMethod method;
/**
* How the serialization will be hashed
*/
HashType hashType;
};
/* Input-addressed output which depends on a (CA) derivation whose hash isn't
* known yet.
/**
* Input-addressed output which depends on a (CA) derivation whose hash
* isn't known yet.
*/
struct DerivationOutputDeferred {};
/* Impure output which is moved to a content-addressed location (like
CAFloating) but isn't registered as a realization.
/**
* Impure output which is moved to a content-addressed location (like
* CAFloating) but isn't registered as a realization.
*/
struct DerivationOutputImpure
{
/* information used for expected hash computation */
/**
* How the file system objects will be serialized for hashing
*/
FileIngestionMethod method;
/**
* How the serialization will be hashed
*/
HashType hashType;
};
@ -64,6 +94,9 @@ typedef std::variant<
DerivationOutputImpure
> _DerivationOutputRaw;
/**
* A single output of a BasicDerivation (and Derivation).
*/
struct DerivationOutput : _DerivationOutputRaw
{
using Raw = _DerivationOutputRaw;
@ -75,9 +108,12 @@ struct DerivationOutput : _DerivationOutputRaw
using Deferred = DerivationOutputDeferred;
using Impure = DerivationOutputImpure;
/* Note, when you use this function you should make sure that you're passing
the right derivation name. When in doubt, you should use the safer
interface provided by BasicDerivation::outputsAndOptPaths */
/**
* \note when you use this function you should make sure that you're
* passing the right derivation name. When in doubt, you should use
* the safer interface provided by
* BasicDerivation::outputsAndOptPaths
*/
std::optional<StorePath> path(const Store & store, std::string_view drvName, std::string_view outputName) const;
inline const Raw & raw() const {
@ -92,26 +128,61 @@ struct DerivationOutput : _DerivationOutputRaw
typedef std::map<std::string, DerivationOutput> DerivationOutputs;
/* These are analogues to the previous DerivationOutputs data type, but they
also contains, for each output, the (optional) store path in which it would
be written. To calculate values of these types, see the corresponding
functions in BasicDerivation */
/**
* These are analogues to the previous DerivationOutputs data type,
* but they also contains, for each output, the (optional) store
* path in which it would be written. To calculate values of these
* types, see the corresponding functions in BasicDerivation.
*/
typedef std::map<std::string, std::pair<DerivationOutput, std::optional<StorePath>>>
DerivationOutputsAndOptPaths;
/* For inputs that are sub-derivations, we specify exactly which
output IDs we are interested in. */
/**
* For inputs that are sub-derivations, we specify exactly which
* output IDs we are interested in.
*/
typedef std::map<StorePath, StringSet> DerivationInputs;
/**
* Input-addressed derivation types
*/
struct DerivationType_InputAddressed {
/**
* True iff the derivation type can't be determined statically,
* for instance because it (transitively) depends on a content-addressed
* derivation.
*/
bool deferred;
};
/**
* Content-addressed derivation types
*/
struct DerivationType_ContentAddressed {
/**
* Whether the derivation should be built safely inside a sandbox.
*/
bool sandboxed;
/**
* Whether the derivation's outputs' content-addresses are "fixed"
* or "floating.
*
* - Fixed: content-addresses are written down as part of the
* derivation itself. If the outputs don't end up matching the
* build fails.
*
* - Floating: content-addresses are not written down, we do not
* know them until we perform the build.
*/
bool fixed;
};
/**
* Impure derivation type
*
* This is similar at buil-time to the content addressed, not standboxed, not fixed
* type, but has some restrictions on its usage.
*/
struct DerivationType_Impure {
};
@ -128,30 +199,38 @@ struct DerivationType : _DerivationTypeRaw {
using ContentAddressed = DerivationType_ContentAddressed;
using Impure = DerivationType_Impure;
/* Do the outputs of the derivation have paths calculated from their content,
or from the derivation itself? */
/**
* Do the outputs of the derivation have paths calculated from their
* content, or from the derivation itself?
*/
bool isCA() const;
/* Is the content of the outputs fixed a-priori via a hash? Never true for
non-CA derivations. */
/**
* Is the content of the outputs fixed <em>a priori</em> via a hash?
* Never true for non-CA derivations.
*/
bool isFixed() const;
/* Whether the derivation is fully sandboxed. If false, the
sandbox is opened up, e.g. the derivation has access to the
network. Note that whether or not we actually sandbox the
derivation is controlled separately. Always true for non-CA
derivations. */
/**
* Whether the derivation is fully sandboxed. If false, the sandbox
* is opened up, e.g. the derivation has access to the network. Note
* that whether or not we actually sandbox the derivation is
* controlled separately. Always true for non-CA derivations.
*/
bool isSandboxed() const;
/* Whether the derivation is expected to produce the same result
every time, and therefore it only needs to be built once. This
is only false for derivations that have the attribute '__impure
= true'. */
/**
* Whether the derivation is expected to produce the same result
* every time, and therefore it only needs to be built once. This is
* only false for derivations that have the attribute '__impure =
* true'.
*/
bool isPure() const;
/* Does the derivation knows its own output paths?
Only true when there's no floating-ca derivation involved in the
closure, or if fixed output.
/**
* Does the derivation knows its own output paths?
* Only true when there's no floating-ca derivation involved in the
* closure, or if fixed output.
*/
bool hasKnownOutputPaths() const;
@ -175,15 +254,21 @@ struct BasicDerivation
bool isBuiltin() const;
/* Return true iff this is a fixed-output derivation. */
/**
* Return true iff this is a fixed-output derivation.
*/
DerivationType type() const;
/* Return the output names of a derivation. */
/**
* Return the output names of a derivation.
*/
StringSet outputNames() const;
/* Calculates the maps that contains all the DerivationOutputs, but
augmented with knowledge of the Store paths they would be written
into. */
/**
* Calculates the maps that contains all the DerivationOutputs, but
* augmented with knowledge of the Store paths they would be written
* into.
*/
DerivationOutputsAndOptPaths outputsAndOptPaths(const Store & store) const;
static std::string_view nameFromPath(const StorePath & storePath);
@ -191,23 +276,33 @@ struct BasicDerivation
struct Derivation : BasicDerivation
{
DerivationInputs inputDrvs; /* inputs that are sub-derivations */
/**
* inputs that are sub-derivations
*/
DerivationInputs inputDrvs;
/* Print a derivation. */
/**
* Print a derivation.
*/
std::string unparse(const Store & store, bool maskOutputs,
std::map<std::string, StringSet> * actualInputs = nullptr) const;
/* Return the underlying basic derivation but with these changes:
1. Input drvs are emptied, but the outputs of them that were used are
added directly to input sources.
2. Input placeholders are replaced with realized input store paths. */
/**
* Return the underlying basic derivation but with these changes:
*
* 1. Input drvs are emptied, but the outputs of them that were used
* are added directly to input sources.
*
* 2. Input placeholders are replaced with realized input store
* paths.
*/
std::optional<BasicDerivation> tryResolve(Store & store) const;
/* Like the above, but instead of querying the Nix database for
realisations, uses a given mapping from input derivation paths
+ output names to actual output store paths. */
/**
* Like the above, but instead of querying the Nix database for
* realisations, uses a given mapping from input derivation paths +
* output names to actual output store paths.
*/
std::optional<BasicDerivation> tryResolve(
Store & store,
const std::map<std::pair<StorePath, std::string>, StorePath> & inputDrvOutputs) const;
@ -222,81 +317,108 @@ struct Derivation : BasicDerivation
class Store;
/* Write a derivation to the Nix store, and return its path. */
/**
* Write a derivation to the Nix store, and return its path.
*/
StorePath writeDerivation(Store & store,
const Derivation & drv,
RepairFlag repair = NoRepair,
bool readOnly = false);
/* Read a derivation from a file. */
/**
* Read a derivation from a file.
*/
Derivation parseDerivation(const Store & store, std::string && s, std::string_view name);
// FIXME: remove
/**
* \todo Remove.
*
* Use Path::isDerivation instead.
*/
bool isDerivation(std::string_view fileName);
/* Calculate the name that will be used for the store path for this
output.
This is usually <drv-name>-<output-name>, but is just <drv-name> when
the output name is "out". */
/**
* Calculate the name that will be used for the store path for this
* output.
*
* This is usually <drv-name>-<output-name>, but is just <drv-name> when
* the output name is "out".
*/
std::string outputPathName(std::string_view drvName, std::string_view outputName);
// The hashes modulo of a derivation.
//
// Each output is given a hash, although in practice only the content-addressed
// derivations (fixed-output or not) will have a different hash for each
// output.
/**
* The hashes modulo of a derivation.
*
* Each output is given a hash, although in practice only the content-addressed
* derivations (fixed-output or not) will have a different hash for each
* output.
*/
struct DrvHash {
/**
* Map from output names to hashes
*/
std::map<std::string, Hash> hashes;
enum struct Kind : bool {
// Statically determined derivations.
// This hash will be directly used to compute the output paths
/**
* Statically determined derivations.
* This hash will be directly used to compute the output paths
*/
Regular,
// Floating-output derivations (and their reverse dependencies).
/**
* Floating-output derivations (and their reverse dependencies).
*/
Deferred,
};
/**
* The kind of derivation this is, simplified for just "derivation hash
* modulo" purposes.
*/
Kind kind;
};
void operator |= (DrvHash::Kind & self, const DrvHash::Kind & other) noexcept;
/* Returns hashes with the details of fixed-output subderivations
expunged.
A fixed-output derivation is a derivation whose outputs have a
specified content hash and hash algorithm. (Currently they must have
exactly one output (`out'), which is specified using the `outputHash'
and `outputHashAlgo' attributes, but the algorithm doesn't assume
this.) We don't want changes to such derivations to propagate upwards
through the dependency graph, changing output paths everywhere.
For instance, if we change the url in a call to the `fetchurl'
function, we do not want to rebuild everything depending on it---after
all, (the hash of) the file being downloaded is unchanged. So the
*output paths* should not change. On the other hand, the *derivation
paths* should change to reflect the new dependency graph.
For fixed-output derivations, this returns a map from the name of
each output to its hash, unique up to the output's contents.
For regular derivations, it returns a single hash of the derivation
ATerm, after subderivations have been likewise expunged from that
derivation.
/**
* Returns hashes with the details of fixed-output subderivations
* expunged.
*
* A fixed-output derivation is a derivation whose outputs have a
* specified content hash and hash algorithm. (Currently they must have
* exactly one output (`out'), which is specified using the `outputHash'
* and `outputHashAlgo' attributes, but the algorithm doesn't assume
* this.) We don't want changes to such derivations to propagate upwards
* through the dependency graph, changing output paths everywhere.
*
* For instance, if we change the url in a call to the `fetchurl'
* function, we do not want to rebuild everything depending on it---after
* all, (the hash of) the file being downloaded is unchanged. So the
* *output paths* should not change. On the other hand, the *derivation
* paths* should change to reflect the new dependency graph.
*
* For fixed-output derivations, this returns a map from the name of
* each output to its hash, unique up to the output's contents.
*
* For regular derivations, it returns a single hash of the derivation
* ATerm, after subderivations have been likewise expunged from that
* derivation.
*/
DrvHash hashDerivationModulo(Store & store, const Derivation & drv, bool maskOutputs);
/*
Return a map associating each output to a hash that uniquely identifies its
derivation (modulo the self-references).
FIXME: what is the Hash in this map?
/**
* Return a map associating each output to a hash that uniquely identifies its
* derivation (modulo the self-references).
*
* \todo What is the Hash in this map?
*/
std::map<std::string, Hash> staticOutputHashes(Store & store, const Derivation & drv);
/* Memoisation of hashDerivationModulo(). */
/**
* Memoisation of hashDerivationModulo().
*/
typedef std::map<StorePath, DrvHash> DrvHashes;
// FIXME: global, though at least thread-safe.
@ -308,21 +430,25 @@ struct Sink;
Source & readDerivation(Source & in, const Store & store, BasicDerivation & drv, std::string_view name);
void writeDerivation(Sink & out, const Store & store, const BasicDerivation & drv);
/* This creates an opaque and almost certainly unique string
deterministically from the output name.
It is used as a placeholder to allow derivations to refer to their
own outputs without needing to use the hash of a derivation in
itself, making the hash near-impossible to calculate. */
/**
* This creates an opaque and almost certainly unique string
* deterministically from the output name.
*
* It is used as a placeholder to allow derivations to refer to their
* own outputs without needing to use the hash of a derivation in
* itself, making the hash near-impossible to calculate.
*/
std::string hashPlaceholder(const std::string_view outputName);
/* This creates an opaque and almost certainly unique string
deterministically from a derivation path and output name.
It is used as a placeholder to allow derivations to refer to
content-addressed paths whose content --- and thus the path
themselves --- isn't yet known. This occurs when a derivation has a
dependency which is a CA derivation. */
/**
* This creates an opaque and almost certainly unique string
* deterministically from a derivation path and output name.
*
* It is used as a placeholder to allow derivations to refer to
* content-addressed paths whose content --- and thus the path
* themselves --- isn't yet known. This occurs when a derivation has a
* dependency which is a CA derivation.
*/
std::string downstreamPlaceholder(const Store & store, const StorePath & drvPath, std::string_view outputName);
extern const Hash impureOutputHash;

2
src/libstore/derived-path.hh
View file

@ -105,7 +105,7 @@ using _BuiltPathRaw = std::variant<
>;
/**
* A built path. Similar to a `DerivedPath`, but enriched with the corresponding
* A built path. Similar to a DerivedPath, but enriched with the corresponding
* output path(s).
*/
struct BuiltPath : _BuiltPathRaw {

33
src/libstore/outputs-spec.hh
View file

@ -9,6 +9,9 @@
namespace nix {
/**
* A non-empty set of outputs, specified by name
*/
struct OutputNames : std::set<std::string> {
using std::set<std::string>::set;
@ -18,6 +21,9 @@ struct OutputNames : std::set<std::string> {
: std::set<std::string>(s)
{ assert(!empty()); }
/**
* Needs to be "inherited manually"
*/
OutputNames(std::set<std::string> && s)
: std::set<std::string>(s)
{ assert(!empty()); }
@ -28,6 +34,9 @@ struct OutputNames : std::set<std::string> {
OutputNames() = delete;
};
/**
* The set of all outputs, without needing to name them explicitly
*/
struct AllOutputs : std::monostate { };
typedef std::variant<AllOutputs, OutputNames> _OutputsSpecRaw;
@ -36,7 +45,9 @@ struct OutputsSpec : _OutputsSpecRaw {
using Raw = _OutputsSpecRaw;
using Raw::Raw;
/* Force choosing a variant */
/**
* Force choosing a variant
*/
OutputsSpec() = delete;
using Names = OutputNames;
@ -52,14 +63,20 @@ struct OutputsSpec : _OutputsSpecRaw {
bool contains(const std::string & output) const;
/* Create a new OutputsSpec which is the union of this and that. */
/**
* Create a new OutputsSpec which is the union of this and that.
*/
OutputsSpec union_(const OutputsSpec & that) const;
/* Whether this OutputsSpec is a subset of that. */
/**
* Whether this OutputsSpec is a subset of that.
*/
bool isSubsetOf(const OutputsSpec & outputs) const;
/* Parse a string of the form 'output1,...outputN' or
'*', returning the outputs spec. */
/**
* Parse a string of the form 'output1,...outputN' or '*', returning
* the outputs spec.
*/
static OutputsSpec parse(std::string_view s);
static std::optional<OutputsSpec> parseOpt(std::string_view s);
@ -81,8 +98,10 @@ struct ExtendedOutputsSpec : _ExtendedOutputsSpecRaw {
return static_cast<const Raw &>(*this);
}
/* Parse a string of the form 'prefix^output1,...outputN' or
'prefix^*', returning the prefix and the extended outputs spec. */
/**
* Parse a string of the form 'prefix^output1,...outputN' or
* 'prefix^*', returning the prefix and the extended outputs spec.
*/
static std::pair<std::string_view, ExtendedOutputsSpec> parse(std::string_view s);
static std::optional<std::pair<std::string_view, ExtendedOutputsSpec>> parseOpt(std::string_view s);

21
src/libstore/path.hh
View file

@ -8,13 +8,22 @@ namespace nix {
struct Hash;
/**
* \ref StorePath "Store path" is the fundamental reference type of Nix.
* A store paths refers to a Store object.
*
* See glossary.html#gloss-store-path for more information on a
* conceptual level.
*/
class StorePath
{
std::string baseName;
public:
/* Size of the hash part of store paths, in base-32 characters. */
/**
* Size of the hash part of store paths, in base-32 characters.
*/
constexpr static size_t HashLen = 32; // i.e. 160 bits
constexpr static size_t MaxPathLen = 211;
@ -45,8 +54,9 @@ public:
return baseName != other.baseName;
}
/* Check whether a file name ends with the extension for
derivations. */
/**
* Check whether a file name ends with the extension for derivations.
*/
bool isDerivation() const;
std::string_view name() const
@ -67,7 +77,10 @@ public:
typedef std::set<StorePath> StorePathSet;
typedef std::vector<StorePath> StorePaths;
/* Extension of derivations in the Nix store. */
/**
* The file extension of \ref Derivation derivations when serialized
* into store objects.
*/
const std::string drvExtension = ".drv";
}

674
src/libstore/store-api.hh
View file

@ -55,7 +55,10 @@ namespace nix {
*/
MakeError(SubstError, Error);
MakeError(BuildError, Error); // denotes a permanent build failure
/**
* denotes a permanent build failure
*/
MakeError(BuildError, Error);
MakeError(InvalidPath, Error);
MakeError(Unsupported, Error);
MakeError(SubstituteGone, Error);
@ -78,7 +81,9 @@ enum CheckSigsFlag : bool { NoCheckSigs = false, CheckSigs = true };
enum SubstituteFlag : bool { NoSubstitute = false, Substitute = true };
enum AllowInvalidFlag : bool { DisallowInvalid = false, AllowInvalid = true };
/* Magic header of exportPath() output (obsolete). */
/**
* Magic header of exportPath() output (obsolete).
*/
const uint32_t exportMagic = 0x4558494e;
@ -153,17 +158,26 @@ protected:
struct PathInfoCacheValue {
// Time of cache entry creation or update
/**
* Time of cache entry creation or update
*/
std::chrono::time_point<std::chrono::steady_clock> time_point = std::chrono::steady_clock::now();
// Null if missing
/**
* Null if missing
*/
std::shared_ptr<const ValidPathInfo> value;
// Whether the value is valid as a cache entry. The path may not exist.
/**
* Whether the value is valid as a cache entry. The path may not
* exist.
*/
bool isKnownNow();
// Past tense, because a path can only be assumed to exists when
// isKnownNow() && didExist()
/**
* Past tense, because a path can only be assumed to exists when
* isKnownNow() && didExist()
*/
inline bool didExist() {
return value != nullptr;
}
@ -197,35 +211,53 @@ public:
std::string printStorePath(const StorePath & path) const;
// FIXME: remove
/**
* Deprecated
*
* \todo remove
*/
StorePathSet parseStorePathSet(const PathSet & paths) const;
PathSet printStorePathSet(const StorePathSet & path) const;
/* Display a set of paths in human-readable form (i.e., between quotes
and separated by commas). */
/**
* Display a set of paths in human-readable form (i.e., between quotes
* and separated by commas).
*/
std::string showPaths(const StorePathSet & paths);
/* Return true if ‘path’ is in the Nix store (but not the Nix
store itself). */
/**
* @return true if ‘path’ is in the Nix store (but not the Nix
* store itself).
*/
bool isInStore(PathView path) const;
/* Return true if ‘path’ is a store path, i.e. a direct child of
the Nix store. */
/**
* @return true if ‘path’ is a store path, i.e. a direct child of the
* Nix store.
*/
bool isStorePath(std::string_view path) const;
/* Split a path like /nix/store/<hash>-<name>/<bla> into
/nix/store/<hash>-<name> and /<bla>. */
/**
* Split a path like /nix/store/<hash>-<name>/<bla> into
* /nix/store/<hash>-<name> and /<bla>.
*/
std::pair<StorePath, Path> toStorePath(PathView path) const;
/* Follow symlinks until we end up with a path in the Nix store. */
/**
* Follow symlinks until we end up with a path in the Nix store.
*/
Path followLinksToStore(std::string_view path) const;
/* Same as followLinksToStore(), but apply toStorePath() to the
result. */
/**
* Same as followLinksToStore(), but apply toStorePath() to the
* result.
*/
StorePath followLinksToStorePath(std::string_view path) const;
/* Constructs a unique store path name. */
/**
* Constructs a unique store path name.
*/
StorePath makeStorePath(std::string_view type,
std::string_view hash, std::string_view name) const;
StorePath makeStorePath(std::string_view type,
@ -246,33 +278,40 @@ public:
const StorePathSet & references = {},
bool hasSelfReference = false) const;
/* This is the preparatory part of addToStore(); it computes the
store path to which srcPath is to be copied. Returns the store
path and the cryptographic hash of the contents of srcPath. */
/**
* Preparatory part of addToStore().
*
* @return the store path to which srcPath is to be copied
* and the cryptographic hash of the contents of srcPath.
*/
std::pair<StorePath, Hash> computeStorePathForPath(std::string_view name,
const Path & srcPath, FileIngestionMethod method = FileIngestionMethod::Recursive,
HashType hashAlgo = htSHA256, PathFilter & filter = defaultPathFilter) const;
/* Preparatory part of addTextToStore().
!!! Computation of the path should take the references given to
addTextToStore() into account, otherwise we have a (relatively
minor) security hole: a caller can register a source file with
bogus references. If there are too many references, the path may
not be garbage collected when it has to be (not really a problem,
the caller could create a root anyway), or it may be garbage
collected when it shouldn't be (more serious).
Hashing the references would solve this (bogus references would
simply yield a different store path, so other users wouldn't be
affected), but it has some backwards compatibility issues (the
hashing scheme changes), so I'm not doing that for now. */
/**
* Preparatory part of addTextToStore().
*
* !!! Computation of the path should take the references given to
* addTextToStore() into account, otherwise we have a (relatively
* minor) security hole: a caller can register a source file with
* bogus references. If there are too many references, the path may
* not be garbage collected when it has to be (not really a problem,
* the caller could create a root anyway), or it may be garbage
* collected when it shouldn't be (more serious).
*
* Hashing the references would solve this (bogus references would
* simply yield a different store path, so other users wouldn't be
* affected), but it has some backwards compatibility issues (the
* hashing scheme changes), so I'm not doing that for now.
*/
StorePath computeStorePathForText(
std::string_view name,
std::string_view s,
const StorePathSet & references) const;
/* Check whether a path is valid. */
/**
* Check whether a path is valid.
*/
bool isValidPath(const StorePath & path);
protected:
@ -281,53 +320,68 @@ protected:
public:
/* If requested, substitute missing paths. This
implements nix-copy-closure's --use-substitutes
flag. */
/**
* If requested, substitute missing paths. This
* implements nix-copy-closure's --use-substitutes
* flag.
*/
void substitutePaths(const StorePathSet & paths);
/* Query which of the given paths is valid. Optionally, try to
substitute missing paths. */
/**
* Query which of the given paths is valid. Optionally, try to
* substitute missing paths.
*/
virtual StorePathSet queryValidPaths(const StorePathSet & paths,
SubstituteFlag maybeSubstitute = NoSubstitute);
/* Query the set of all valid paths. Note that for some store
backends, the name part of store paths may be replaced by 'x'
(i.e. you'll get /nix/store/<hash>-x rather than
/nix/store/<hash>-<name>). Use queryPathInfo() to obtain the
full store path. FIXME: should return a set of
std::variant<StorePath, HashPart> to get rid of this hack. */
/**
* Query the set of all valid paths. Note that for some store
* backends, the name part of store paths may be replaced by 'x'
* (i.e. you'll get /nix/store/<hash>-x rather than
* /nix/store/<hash>-<name>). Use queryPathInfo() to obtain the
* full store path. FIXME: should return a set of
* std::variant<StorePath, HashPart> to get rid of this hack.
*/
virtual StorePathSet queryAllValidPaths()
{ unsupported("queryAllValidPaths"); }
constexpr static const char * MissingName = "x";
/* Query information about a valid path. It is permitted to omit
the name part of the store path. */
/**
* Query information about a valid path. It is permitted to omit
* the name part of the store path.
*/
ref<const ValidPathInfo> queryPathInfo(const StorePath & path);
/* Asynchronous version of queryPathInfo(). */
/**
* Asynchronous version of queryPathInfo().
*/
void queryPathInfo(const StorePath & path,
Callback<ref<const ValidPathInfo>> callback) noexcept;
/* Query the information about a realisation. */
/**
* Query the information about a realisation.
*/
std::shared_ptr<const Realisation> queryRealisation(const DrvOutput &);
/* Asynchronous version of queryRealisation(). */
/**
* Asynchronous version of queryRealisation().
*/
void queryRealisation(const DrvOutput &,
Callback<std::shared_ptr<const Realisation>> callback) noexcept;
/* Check whether the given valid path info is sufficiently attested, by
either being signed by a trusted public key or content-addressed, in
order to be included in the given store.
These same checks would be performed in addToStore, but this allows an
earlier failure in the case where dependencies need to be added too, but
the addToStore wouldn't fail until those dependencies are added. Also,
we don't really want to add the dependencies listed in a nar info we
don't trust anyyways.
*/
/**
* Check whether the given valid path info is sufficiently attested, by
* either being signed by a trusted public key or content-addressed, in
* order to be included in the given store.
*
* These same checks would be performed in addToStore, but this allows an
* earlier failure in the case where dependencies need to be added too, but
* the addToStore wouldn't fail until those dependencies are added. Also,
* we don't really want to add the dependencies listed in a nar info we
* don't trust anyyways.
*/
virtual bool pathInfoIsUntrusted(const ValidPathInfo &)
{
return true;
@ -347,53 +401,77 @@ protected:
public:
/* Queries the set of incoming FS references for a store path.
The result is not cleared. */
/**
* Queries the set of incoming FS references for a store path.
* The result is not cleared.
*/
virtual void queryReferrers(const StorePath & path, StorePathSet & referrers)
{ unsupported("queryReferrers"); }
/* Return all currently valid derivations that have `path' as an
output. (Note that the result of `queryDeriver()' is the
derivation that was actually used to produce `path', which may
not exist anymore.) */
/**
* @return all currently valid derivations that have `path' as an
* output.
*
* (Note that the result of `queryDeriver()' is the derivation that
* was actually used to produce `path', which may not exist
* anymore.)
*/
virtual StorePathSet queryValidDerivers(const StorePath & path) { return {}; };
/* Query the outputs of the derivation denoted by `path'. */
/**
* Query the outputs of the derivation denoted by `path'.
*/
virtual StorePathSet queryDerivationOutputs(const StorePath & path);
/* Query the mapping outputName => outputPath for the given derivation. All
outputs are mentioned so ones mising the mapping are mapped to
`std::nullopt`. */
/**
* Query the mapping outputName => outputPath for the given
* derivation. All outputs are mentioned so ones mising the mapping
* are mapped to `std::nullopt`.
*/
virtual std::map<std::string, std::optional<StorePath>> queryPartialDerivationOutputMap(const StorePath & path);
/* Query the mapping outputName=>outputPath for the given derivation.
Assume every output has a mapping and throw an exception otherwise. */
/**
* Query the mapping outputName=>outputPath for the given derivation.
* Assume every output has a mapping and throw an exception otherwise.
*/
OutputPathMap queryDerivationOutputMap(const StorePath & path);
/* Query the full store path given the hash part of a valid store
path, or empty if the path doesn't exist. */
/**
* Query the full store path given the hash part of a valid store
* path, or empty if the path doesn't exist.
*/
virtual std::optional<StorePath> queryPathFromHashPart(const std::string & hashPart) = 0;
/* Query which of the given paths have substitutes. */
/**
* Query which of the given paths have substitutes.
*/
virtual StorePathSet querySubstitutablePaths(const StorePathSet & paths) { return {}; };
/* Query substitute info (i.e. references, derivers and download
sizes) of a map of paths to their optional ca values. The info
of the first succeeding substituter for each path will be
returned. If a path does not have substitute info, it's omitted
from the resulting ‘infos’ map. */
/**
* Query substitute info (i.e. references, derivers and download
* sizes) of a map of paths to their optional ca values. The info of
* the first succeeding substituter for each path will be returned.
* If a path does not have substitute info, it's omitted from the
* resulting ‘infos’ map.
*/
virtual void querySubstitutablePathInfos(const StorePathCAMap & paths,
SubstitutablePathInfos & infos) { return; };
/* Import a path into the store. */
/**
* Import a path into the store.
*/
virtual void addToStore(const ValidPathInfo & info, Source & narSource,
RepairFlag repair = NoRepair, CheckSigsFlag checkSigs = CheckSigs) = 0;
// A list of paths infos along with a source providing the content of the
// associated store path
/**
* A list of paths infos along with a source providing the content
* of the associated store path
*/
using PathsSource = std::vector<std::pair<ValidPathInfo, std::unique_ptr<Source>>>;
/* Import multiple paths into the store. */
/**
* Import multiple paths into the store.
*/
virtual void addMultipleToStore(
Source & source,
RepairFlag repair = NoRepair,
@ -405,10 +483,14 @@ public:
RepairFlag repair = NoRepair,
CheckSigsFlag checkSigs = CheckSigs);
/* Copy the contents of a path to the store and register the
validity the resulting path. The resulting path is returned.
The function object `filter' can be used to exclude files (see
libutil/archive.hh). */
/**
* Copy the contents of a path to the store and register the
* validity the resulting path.
*
* @return The resulting path is returned.
* @param filter This function can be used to exclude files (see
* libutil/archive.hh).
*/
virtual StorePath addToStore(
std::string_view name,
const Path & srcPath,
@ -418,26 +500,33 @@ public:
RepairFlag repair = NoRepair,
const StorePathSet & references = StorePathSet());
/* Copy the contents of a path to the store and register the
validity the resulting path, using a constant amount of
memory. */
/**
* Copy the contents of a path to the store and register the
* validity the resulting path, using a constant amount of
* memory.
*/
ValidPathInfo addToStoreSlow(std::string_view name, const Path & srcPath,
FileIngestionMethod method = FileIngestionMethod::Recursive, HashType hashAlgo = htSHA256,
std::optional<Hash> expectedCAHash = {});
/* Like addToStore(), but the contents of the path are contained
in `dump', which is either a NAR serialisation (if recursive ==
true) or simply the contents of a regular file (if recursive ==
false).
`dump` may be drained */
// FIXME: remove?
/**
* Like addToStore(), but the contents of the path are contained
* in `dump', which is either a NAR serialisation (if recursive ==
* true) or simply the contents of a regular file (if recursive ==
* false).
* `dump` may be drained
*
* \todo remove?
*/
virtual StorePath addToStoreFromDump(Source & dump, std::string_view name,
FileIngestionMethod method = FileIngestionMethod::Recursive, HashType hashAlgo = htSHA256, RepairFlag repair = NoRepair,
const StorePathSet & references = StorePathSet())
{ unsupported("addToStoreFromDump"); }
/* Like addToStore, but the contents written to the output path is
a regular file containing the given string. */
/**
* Like addToStore, but the contents written to the output path is a
* regular file containing the given string.
*/
virtual StorePath addTextToStore(
std::string_view name,
std::string_view s,
@ -458,140 +547,180 @@ public:
virtual void registerDrvOutput(const Realisation & output, CheckSigsFlag checkSigs)
{ return registerDrvOutput(output); }
/* Write a NAR dump of a store path. */
/**
* Write a NAR dump of a store path.
*/
virtual void narFromPath(const StorePath & path, Sink & sink) = 0;
/* For each path, if it's a derivation, build it. Building a
derivation means ensuring that the output paths are valid. If
they are already valid, this is a no-op. Otherwise, validity
can be reached in two ways. First, if the output paths is
substitutable, then build the path that way. Second, the
output paths can be created by running the builder, after
recursively building any sub-derivations. For inputs that are
not derivations, substitute them. */
/**
* For each path, if it's a derivation, build it. Building a
* derivation means ensuring that the output paths are valid. If
* they are already valid, this is a no-op. Otherwise, validity
* can be reached in two ways. First, if the output paths is
* substitutable, then build the path that way. Second, the
* output paths can be created by running the builder, after
* recursively building any sub-derivations. For inputs that are
* not derivations, substitute them.
*/
virtual void buildPaths(
const std::vector<DerivedPath> & paths,
BuildMode buildMode = bmNormal,
std::shared_ptr<Store> evalStore = nullptr);
/* Like `buildPaths()`, but return a vector of `BuildResult`s
corresponding to each element in `paths`. Note that in case of
a build/substitution error, this function won't throw an
exception, but return a `BuildResult` containing an error
message. */
/**
* Like buildPaths(), but return a vector of \ref BuildResult
* BuildResults corresponding to each element in paths. Note that in
* case of a build/substitution error, this function won't throw an
* exception, but return a BuildResult containing an error message.
*/
virtual std::vector<BuildResult> buildPathsWithResults(
const std::vector<DerivedPath> & paths,
BuildMode buildMode = bmNormal,
std::shared_ptr<Store> evalStore = nullptr);
/* Build a single non-materialized derivation (i.e. not from an
on-disk .drv file).
‘drvPath’ is used to deduplicate worker goals so it is imperative that
is correct. That said, it doesn't literally need to be store path that
would be calculated from writing this derivation to the store: it is OK
if it instead is that of a Derivation which would resolve to this (by
taking the outputs of it's input derivations and adding them as input
sources) such that the build time referenceable-paths are the same.
In the input-addressed case, we usually *do* use an "original"
unresolved derivations's path, as that is what will be used in the
`buildPaths` case. Also, the input-addressed output paths are verified
only by that contents of that specific unresolved derivation, so it is
nice to keep that information around so if the original derivation is
ever obtained later, it can be verified whether the trusted user in fact
used the proper output path.
In the content-addressed case, we want to always use the
resolved drv path calculated from the provided derivation. This serves
two purposes:
- It keeps the operation trustless, by ruling out a maliciously
invalid drv path corresponding to a non-resolution-equivalent
derivation.
- For the floating case in particular, it ensures that the derivation
to output mapping respects the resolution equivalence relation, so
one cannot choose different resolution-equivalent derivations to
subvert dependency coherence (i.e. the property that one doesn't end
up with multiple different versions of dependencies without
explicitly choosing to allow it).
*/
/**
* Build a single non-materialized derivation (i.e. not from an
* on-disk .drv file).
*
* @param drvPath This is used to deduplicate worker goals so it is
* imperative that is correct. That said, it doesn't literally need
* to be store path that would be calculated from writing this
* derivation to the store: it is OK if it instead is that of a
* Derivation which would resolve to this (by taking the outputs of
* it's input derivations and adding them as input sources) such
* that the build time referenceable-paths are the same.
*
* In the input-addressed case, we usually *do* use an "original"
* unresolved derivations's path, as that is what will be used in the
* buildPaths case. Also, the input-addressed output paths are verified
* only by that contents of that specific unresolved derivation, so it is
* nice to keep that information around so if the original derivation is
* ever obtained later, it can be verified whether the trusted user in fact
* used the proper output path.
*
* In the content-addressed case, we want to always use the resolved
* drv path calculated from the provided derivation. This serves two
* purposes:
*
* - It keeps the operation trustless, by ruling out a maliciously
* invalid drv path corresponding to a non-resolution-equivalent
* derivation.
*
* - For the floating case in particular, it ensures that the derivation
* to output mapping respects the resolution equivalence relation, so
* one cannot choose different resolution-equivalent derivations to
* subvert dependency coherence (i.e. the property that one doesn't end
* up with multiple different versions of dependencies without
* explicitly choosing to allow it).
*/
virtual BuildResult buildDerivation(const StorePath & drvPath, const BasicDerivation & drv,
BuildMode buildMode = bmNormal);
/* Ensure that a path is valid. If it is not currently valid, it
may be made valid by running a substitute (if defined for the
path). */
/**
* Ensure that a path is valid. If it is not currently valid, it
* may be made valid by running a substitute (if defined for the
* path).
*/
virtual void ensurePath(const StorePath & path);
/* Add a store path as a temporary root of the garbage collector.
The root disappears as soon as we exit. */
/**
* Add a store path as a temporary root of the garbage collector.
* The root disappears as soon as we exit.
*/
virtual void addTempRoot(const StorePath & path)
{ debug("not creating temporary root, store doesn't support GC"); }
/* Return a string representing information about the path that
can be loaded into the database using `nix-store --load-db' or
`nix-store --register-validity'. */
/**
* @return a string representing information about the path that
* can be loaded into the database using `nix-store --load-db' or
* `nix-store --register-validity'.
*/
std::string makeValidityRegistration(const StorePathSet & paths,
bool showDerivers, bool showHash);
/* Write a JSON representation of store path metadata, such as the
hash and the references. If ‘includeImpureInfo’ is true,
variable elements such as the registration time are
included. If ‘showClosureSize’ is true, the closure size of
each path is included. */
/**
* Write a JSON representation of store path metadata, such as the
* hash and the references.
*
* @param includeImpureInfo If true, variable elements such as the
* registration time are included.
*
* @param showClosureSize If true, the closure size of each path is
* included.
*/
nlohmann::json pathInfoToJSON(const StorePathSet & storePaths,
bool includeImpureInfo, bool showClosureSize,
Base hashBase = Base32,
AllowInvalidFlag allowInvalid = DisallowInvalid);
/* Return the size of the closure of the specified path, that is,
the sum of the size of the NAR serialisation of each path in
the closure. */
/**
* @return the size of the closure of the specified path, that is,
* the sum of the size of the NAR serialisation of each path in the
* closure.
*/
std::pair<uint64_t, uint64_t> getClosureSize(const StorePath & storePath);
/* Optimise the disk space usage of the Nix store by hard-linking files
with the same contents. */
/**
* Optimise the disk space usage of the Nix store by hard-linking files
* with the same contents.
*/
virtual void optimiseStore() { };
/* Check the integrity of the Nix store. Returns true if errors
remain. */
/**
* Check the integrity of the Nix store.
*
* @return true if errors remain.
*/
virtual bool verifyStore(bool checkContents, RepairFlag repair = NoRepair) { return false; };
/* Return an object to access files in the Nix store. */
/**
* @return An object to access files in the Nix store.
*/
virtual ref<FSAccessor> getFSAccessor()
{ unsupported("getFSAccessor"); }
/* Repair the contents of the given path by redownloading it using
a substituter (if available). */
/**
* Repair the contents of the given path by redownloading it using
* a substituter (if available).
*/
virtual void repairPath(const StorePath & path)
{ unsupported("repairPath"); }
/* Add signatures to the specified store path. The signatures are
not verified. */
/**
* Add signatures to the specified store path. The signatures are
* not verified.
*/
virtual void addSignatures(const StorePath & storePath, const StringSet & sigs)
{ unsupported("addSignatures"); }
/* Utility functions. */
/* Read a derivation, after ensuring its existence through
ensurePath(). */
/**
* Read a derivation, after ensuring its existence through
* ensurePath().
*/
Derivation derivationFromPath(const StorePath & drvPath);
/* Read a derivation (which must already be valid). */
/**
* Read a derivation (which must already be valid).
*/
Derivation readDerivation(const StorePath & drvPath);
/* Read a derivation from a potentially invalid path. */
/**
* Read a derivation from a potentially invalid path.
*/
Derivation readInvalidDerivation(const StorePath & drvPath);
/* Place in `out' the set of all store paths in the file system
closure of `storePath'; that is, all paths than can be directly
or indirectly reached from it. `out' is not cleared. If
`flipDirection' is true, the set of paths that can reach
`storePath' is returned; that is, the closures under the
`referrers' relation instead of the `references' relation is
returned. */
/**
* @param [out] out Place in here the set of all store paths in the
* file system closure of `storePath'; that is, all paths than can
* be directly or indirectly reached from it. `out' is not cleared.
*
* @param flipDirection If true, the set of paths that can reach
* `storePath' is returned; that is, the closures under the
* `referrers' relation instead of the `references' relation is
* returned.
*/
virtual void computeFSClosure(const StorePathSet & paths,
StorePathSet & out, bool flipDirection = false,
bool includeOutputs = false, bool includeDerivers = false);
@ -600,27 +729,34 @@ public:
StorePathSet & out, bool flipDirection = false,
bool includeOutputs = false, bool includeDerivers = false);
/* Given a set of paths that are to be built, return the set of
derivations that will be built, and the set of output paths
that will be substituted. */
/**
* Given a set of paths that are to be built, return the set of
* derivations that will be built, and the set of output paths that
* will be substituted.
*/
virtual void queryMissing(const std::vector<DerivedPath> & targets,
StorePathSet & willBuild, StorePathSet & willSubstitute, StorePathSet & unknown,
uint64_t & downloadSize, uint64_t & narSize);
/* Sort a set of paths topologically under the references
relation. If p refers to q, then p precedes q in this list. */
/**
* Sort a set of paths topologically under the references
* relation. If p refers to q, then p precedes q in this list.
*/
StorePaths topoSortPaths(const StorePathSet & paths);
/* Export multiple paths in the format expected by ‘nix-store
--import’. */
/**
* Export multiple paths in the format expected by ‘nix-store
* --import’.
*/
void exportPaths(const StorePathSet & paths, Sink & sink);
void exportPath(const StorePath & path, Sink & sink);
/* Import a sequence of NAR dumps created by exportPaths() into
the Nix store. Optionally, the contents of the NARs are
preloaded into the specified FS accessor to speed up subsequent
access. */
/**
* Import a sequence of NAR dumps created by exportPaths() into the
* Nix store. Optionally, the contents of the NARs are preloaded
* into the specified FS accessor to speed up subsequent access.
*/
StorePaths importPaths(Source & source, CheckSigsFlag checkSigs = CheckSigs);
struct Stats
@ -642,8 +778,9 @@ public:
const Stats & getStats();
/* Computes the full closure of of a set of store-paths for e.g.
derivations that need this information for `exportReferencesGraph`.
/**
* Computes the full closure of of a set of store-paths for e.g.
* derivations that need this information for `exportReferencesGraph`.
*/
StorePathSet exportReferences(const StorePathSet & storePaths, const StorePathSet & inputPaths);
@ -654,18 +791,24 @@ public:
*/
std::optional<StorePath> getBuildDerivationPath(const StorePath &);
/* Hack to allow long-running processes like hydra-queue-runner to
occasionally flush their path info cache. */
/**
* Hack to allow long-running processes like hydra-queue-runner to
* occasionally flush their path info cache.
*/
void clearPathInfoCache()
{
state.lock()->pathInfoCache.clear();
}
/* Establish a connection to the store, for store types that have
a notion of connection. Otherwise this is a no-op. */
/**
* Establish a connection to the store, for store types that have
* a notion of connection. Otherwise this is a no-op.
*/
virtual void connect() { };
/* Get the protocol version of this store or it's connection. */
/**
* Get the protocol version of this store or it's connection.
*/
virtual unsigned int getProtocol()
{
return 0;
@ -681,7 +824,7 @@ public:
return toRealPath(printStorePath(storePath));
}
/*
/**
* Synchronises the options of the client with those of the daemon
* (a no-op when there’s no daemon)
*/
@ -693,7 +836,13 @@ protected:
Stats stats;
/* Unsupported methods. */
/**
* Helper for methods that are not unsupported: this is used for
* default definitions for virtual methods that are meant to be overriden.
*
* \todo Using this should be a last resort. It is better to make
* the method "virtual pure" and/or move it to a subclass.
*/
[[noreturn]] void unsupported(const std::string & op)
{
throw Unsupported("operation '%s' is not supported by store '%s'", op, getUri());
@ -702,7 +851,9 @@ protected:
};
/* Copy a path from one store to another. */
/**
* Copy a path from one store to another.
*/
void copyStorePath(
Store & srcStore,
Store & dstStore,
@ -711,12 +862,14 @@ void copyStorePath(
CheckSigsFlag checkSigs = CheckSigs);
/* Copy store paths from one store to another. The paths may be copied
in parallel. They are copied in a topologically sorted order (i.e.
if A is a reference of B, then A is copied before B), but the set
of store paths is not automatically closed; use copyClosure() for
that. Returns a map of what each path was copied to the dstStore
as. */
/**
* Copy store paths from one store to another. The paths may be copied
* in parallel. They are copied in a topologically sorted order (i.e. if
* A is a reference of B, then A is copied before B), but the set of
* store paths is not automatically closed; use copyClosure() for that.
*
* @return a map of what each path was copied to the dstStore as.
*/
std::map<StorePath, StorePath> copyPaths(
Store & srcStore, Store & dstStore,
const RealisedPath::Set &,
@ -731,7 +884,9 @@ std::map<StorePath, StorePath> copyPaths(
CheckSigsFlag checkSigs = CheckSigs,
SubstituteFlag substitute = NoSubstitute);
/* Copy the closure of `paths` from `srcStore` to `dstStore`. */
/**
* Copy the closure of `paths` from `srcStore` to `dstStore`.
*/
void copyClosure(
Store & srcStore, Store & dstStore,
const RealisedPath::Set & paths,
@ -746,52 +901,61 @@ void copyClosure(
CheckSigsFlag checkSigs = CheckSigs,
SubstituteFlag substitute = NoSubstitute);
/* Remove the temporary roots file for this process. Any temporary
root becomes garbage after this point unless it has been registered
as a (permanent) root. */
/**
* Remove the temporary roots file for this process. Any temporary
* root becomes garbage after this point unless it has been registered
* as a (permanent) root.
*/
void removeTempRoots();
/* Resolve the derived path completely, failing if any derivation output
is unknown. */
/**
* Resolve the derived path completely, failing if any derivation output
* is unknown.
*/
OutputPathMap resolveDerivedPath(Store &, const DerivedPath::Built &, Store * evalStore = nullptr);
/* Return a Store object to access the Nix store denoted by
‘uri’ (slight misnomer...). Supported values are:
* ‘local’: The Nix store in /nix/store and database in
/nix/var/nix/db, accessed directly.
* ‘daemon’: The Nix store accessed via a Unix domain socket
connection to nix-daemon.
* ‘unix://<path>’: The Nix store accessed via a Unix domain socket
connection to nix-daemon, with the socket located at <path>.
* ‘auto’ or ‘’: Equivalent to ‘local’ or ‘daemon’ depending on
whether the user has write access to the local Nix
store/database.
* ‘file://<path>’: A binary cache stored in <path>.
* ‘https://<path>’: A binary cache accessed via HTTP.
* ‘s3://<path>’: A writable binary cache stored on Amazon's Simple
Storage Service.
* ‘ssh://[user@]<host>’: A remote Nix store accessed by running
‘nix-store --serve’ via SSH.
You can pass parameters to the store implementation by appending
‘?key=value&key=value&...’ to the URI.
*/
/**
* @return a Store object to access the Nix store denoted by
* ‘uri’ (slight misnomer...).
*
* @param uri Supported values are:
*
* - ‘local’: The Nix store in /nix/store and database in
* /nix/var/nix/db, accessed directly.
*
* - ‘daemon’: The Nix store accessed via a Unix domain socket
* connection to nix-daemon.
*
* - ‘unix://<path>’: The Nix store accessed via a Unix domain socket
* connection to nix-daemon, with the socket located at <path>.
*
* - ‘auto’ or ‘’: Equivalent to ‘local’ or ‘daemon’ depending on
* whether the user has write access to the local Nix
* store/database.
*
* - ‘file://<path>’: A binary cache stored in <path>.
*
* - ‘https://<path>’: A binary cache accessed via HTTP.
*
* - ‘s3://<path>’: A writable binary cache stored on Amazon's Simple
* Storage Service.
*
* - ‘ssh://[user@]<host>’: A remote Nix store accessed by running
* ‘nix-store --serve’ via SSH.
*
* You can pass parameters to the store implementation by appending
* ‘?key=value&key=value&...’ to the URI.
*/
ref<Store> openStore(const std::string & uri = settings.storeUri.get(),
const Store::Params & extraParams = Store::Params());
/* Return the default substituter stores, defined by the
‘substituters’ option and various legacy options. */
/**
* @return the default substituter stores, defined by the
* ‘substituters’ option and various legacy options.
*/
std::list<ref<Store>> getDefaultSubstituters();
struct StoreFactory
@ -834,8 +998,10 @@ struct RegisterStoreImplementation
};
/* Display a set of paths in human-readable form (i.e., between quotes
and separated by commas). */
/**
* Display a set of paths in human-readable form (i.e., between quotes
* and separated by commas).
*/
std::string showPaths(const PathSet & paths);
@ -844,7 +1010,9 @@ std::optional<ValidPathInfo> decodeValidPathInfo(
std::istream & str,
std::optional<HashResult> hashGiven = std::nullopt);
/* Split URI into protocol+hierarchy part and its parameter set. */
/**
* Split URI into protocol+hierarchy part and its parameter set.
*/
std::pair<std::string, Store::Params> splitUriAndParams(const std::string & uri);
std::optional<ContentAddress> getDerivationCA(const BasicDerivation & drv);