mirror of
https://github.com/NixOS/nix
synced 2025-06-28 22:01:15 +02:00
Finish converting existing comments for internal API docs (#8146)
* Finish converting existing comments for internal API docs 99% of this was just reformatting existing comments. Only two exceptions: - Expanded upon `BuildResult::status` compat note - Split up file-level `symbol-table.hh` doc comments to get per-definition docs Also fixed a few whitespace goofs, turning leading tabs to spaces and removing trailing spaces. Picking up from #8133 * Fix two things from comments * Use triple-backtick not indent for `dumpPath` * Convert GNU-style `\`..'` quotes to markdown style in API docs This will render correctly.
This commit is contained in:
John Ericson
GitHub
parent
54b3b6ebc6
commit
0746951be1
53 changed files with 1907 additions and 938 deletions
|
|
@ -18,7 +18,8 @@ struct FlakeInput;
|
|||
|
||||
typedef std::map<FlakeId, FlakeInput> FlakeInputs;
|
||||
|
||||
/* FlakeInput is the 'Flake'-level parsed form of the "input" entries
|
||||
/**
|
||||
* FlakeInput is the 'Flake'-level parsed form of the "input" entries
|
||||
* in the flake file.
|
||||
*
|
||||
* A FlakeInput is normally constructed by the 'parseFlakeInput'
|
||||
|
|
@ -42,7 +43,12 @@ typedef std::map<FlakeId, FlakeInput> FlakeInputs;
|
|||
struct FlakeInput
|
||||
{
|
||||
std::optional<FlakeRef> ref;
|
||||
bool isFlake = true; // true = process flake to get outputs, false = (fetched) static source path
|
||||
/**
|
||||
* true = process flake to get outputs
|
||||
*
|
||||
* false = (fetched) static source path
|
||||
*/
|
||||
bool isFlake = true;
|
||||
std::optional<InputPath> follows;
|
||||
FlakeInputs overrides;
|
||||
};
|
||||
|
|
@ -56,23 +62,42 @@ struct ConfigFile
|
|||
void apply();
|
||||
};
|
||||
|
||||
/* The contents of a flake.nix file. */
|
||||
/**
|
||||
* The contents of a flake.nix file.
|
||||
*/
|
||||
struct Flake
|
||||
{
|
||||
FlakeRef originalRef; // the original flake specification (by the user)
|
||||
FlakeRef resolvedRef; // registry references and caching resolved to the specific underlying flake
|
||||
FlakeRef lockedRef; // the specific local store result of invoking the fetcher
|
||||
bool forceDirty = false; // pretend that 'lockedRef' is dirty
|
||||
/**
|
||||
* The original flake specification (by the user)
|
||||
*/
|
||||
FlakeRef originalRef;
|
||||
/**
|
||||
* registry references and caching resolved to the specific underlying flake
|
||||
*/
|
||||
FlakeRef resolvedRef;
|
||||
/**
|
||||
* the specific local store result of invoking the fetcher
|
||||
*/
|
||||
FlakeRef lockedRef;
|
||||
/**
|
||||
* pretend that 'lockedRef' is dirty
|
||||
*/
|
||||
bool forceDirty = false;
|
||||
std::optional<std::string> description;
|
||||
std::shared_ptr<const fetchers::Tree> sourceInfo;
|
||||
FlakeInputs inputs;
|
||||
ConfigFile config; // 'nixConfig' attribute
|
||||
/**
|
||||
* 'nixConfig' attribute
|
||||
*/
|
||||
ConfigFile config;
|
||||
~Flake();
|
||||
};
|
||||
|
||||
Flake getFlake(EvalState & state, const FlakeRef & flakeRef, bool allowLookup);
|
||||
|
||||
/* Fingerprint of a locked flake; used as a cache key. */
|
||||
/**
|
||||
* Fingerprint of a locked flake; used as a cache key.
|
||||
*/
|
||||
typedef Hash Fingerprint;
|
||||
|
||||
struct LockedFlake
|
||||
|
|
@ -85,50 +110,72 @@ struct LockedFlake
|
|||
|
||||
struct LockFlags
|
||||
{
|
||||
/* Whether to ignore the existing lock file, creating a new one
|
||||
from scratch. */
|
||||
/**
|
||||
* Whether to ignore the existing lock file, creating a new one
|
||||
* from scratch.
|
||||
*/
|
||||
bool recreateLockFile = false;
|
||||
|
||||
/* Whether to update the lock file at all. If set to false, if any
|
||||
change to the lock file is needed (e.g. when an input has been
|
||||
added to flake.nix), you get a fatal error. */
|
||||
/**
|
||||
* Whether to update the lock file at all. If set to false, if any
|
||||
* change to the lock file is needed (e.g. when an input has been
|
||||
* added to flake.nix), you get a fatal error.
|
||||
*/
|
||||
bool updateLockFile = true;
|
||||
|
||||
/* Whether to write the lock file to disk. If set to true, if the
|
||||
any changes to the lock file are needed and the flake is not
|
||||
writable (i.e. is not a local Git working tree or similar), you
|
||||
get a fatal error. If set to false, Nix will use the modified
|
||||
lock file in memory only, without writing it to disk. */
|
||||
/**
|
||||
* Whether to write the lock file to disk. If set to true, if the
|
||||
* any changes to the lock file are needed and the flake is not
|
||||
* writable (i.e. is not a local Git working tree or similar), you
|
||||
* get a fatal error. If set to false, Nix will use the modified
|
||||
* lock file in memory only, without writing it to disk.
|
||||
*/
|
||||
bool writeLockFile = true;
|
||||
|
||||
/* Whether to use the registries to lookup indirect flake
|
||||
references like 'nixpkgs'. */
|
||||
/**
|
||||
* Whether to use the registries to lookup indirect flake
|
||||
* references like 'nixpkgs'.
|
||||
*/
|
||||
std::optional<bool> useRegistries = std::nullopt;
|
||||
|
||||
/* Whether to apply flake's nixConfig attribute to the configuration */
|
||||
/**
|
||||
* Whether to apply flake's nixConfig attribute to the configuration
|
||||
*/
|
||||
|
||||
bool applyNixConfig = false;
|
||||
|
||||
/* Whether unlocked flake references (i.e. those without a Git
|
||||
revision or similar) without a corresponding lock are
|
||||
allowed. Unlocked flake references with a lock are always
|
||||
allowed. */
|
||||
/**
|
||||
* Whether unlocked flake references (i.e. those without a Git
|
||||
* revision or similar) without a corresponding lock are
|
||||
* allowed. Unlocked flake references with a lock are always
|
||||
* allowed.
|
||||
*/
|
||||
bool allowUnlocked = true;
|
||||
|
||||
/* Whether to commit changes to flake.lock. */
|
||||
/**
|
||||
* Whether to commit changes to flake.lock.
|
||||
*/
|
||||
bool commitLockFile = false;
|
||||
|
||||
/* The path to a lock file to read instead of the `flake.lock` file in the top-level flake */
|
||||
/**
|
||||
* The path to a lock file to read instead of the `flake.lock` file in the top-level flake
|
||||
*/
|
||||
std::optional<std::string> referenceLockFilePath;
|
||||
|
||||
/* The path to a lock file to write to instead of the `flake.lock` file in the top-level flake */
|
||||
/**
|
||||
* The path to a lock file to write to instead of the `flake.lock` file in the top-level flake
|
||||
*/
|
||||
std::optional<Path> outputLockFilePath;
|
||||
|
||||
/* Flake inputs to be overridden. */
|
||||
/**
|
||||
* Flake inputs to be overridden.
|
||||
*/
|
||||
std::map<InputPath, FlakeRef> inputOverrides;
|
||||
|
||||
/* Flake inputs to be updated. This means that any existing lock
|
||||
for those inputs will be ignored. */
|
||||
/**
|
||||
* Flake inputs to be updated. This means that any existing lock
|
||||
* for those inputs will be ignored.
|
||||
*/
|
||||
std::set<InputPath> inputUpdates;
|
||||
};
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,8 @@ class Store;
|
|||
|
||||
typedef std::string FlakeId;
|
||||
|
||||
/* A flake reference specifies how to fetch a flake or raw source
|
||||
/**
|
||||
* A flake reference specifies how to fetch a flake or raw source
|
||||
* (e.g. from a Git repository). It is created from a URL-like syntax
|
||||
* (e.g. 'github:NixOS/patchelf'), an attrset representation (e.g. '{
|
||||
* type="github"; owner = "NixOS"; repo = "patchelf"; }'), or a local
|
||||
|
|
@ -33,14 +34,17 @@ typedef std::string FlakeId;
|
|||
* be lazy), but the fetcher can be invoked at any time via the
|
||||
* FlakeRef to ensure the store is populated with this input.
|
||||
*/
|
||||
|
||||
struct FlakeRef
|
||||
{
|
||||
/* Fetcher-specific representation of the input, sufficient to
|
||||
perform the fetch operation. */
|
||||
/**
|
||||
* Fetcher-specific representation of the input, sufficient to
|
||||
* perform the fetch operation.
|
||||
*/
|
||||
fetchers::Input input;
|
||||
|
||||
/* sub-path within the fetched input that represents this input */
|
||||
/**
|
||||
* sub-path within the fetched input that represents this input
|
||||
*/
|
||||
Path subdir;
|
||||
|
||||
bool operator==(const FlakeRef & other) const;
|
||||
|
|
|
|||
|
|
@ -16,9 +16,11 @@ typedef std::vector<FlakeId> InputPath;
|
|||
|
||||
struct LockedNode;
|
||||
|
||||
/* A node in the lock file. It has outgoing edges to other nodes (its
|
||||
inputs). Only the root node has this type; all other nodes have
|
||||
type LockedNode. */
|
||||
/**
|
||||
* A node in the lock file. It has outgoing edges to other nodes (its
|
||||
* inputs). Only the root node has this type; all other nodes have
|
||||
* type LockedNode.
|
||||
*/
|
||||
struct Node : std::enable_shared_from_this<Node>
|
||||
{
|
||||
typedef std::variant<ref<LockedNode>, InputPath> Edge;
|
||||
|
|
@ -28,7 +30,9 @@ struct Node : std::enable_shared_from_this<Node>
|
|||
virtual ~Node() { }
|
||||
};
|
||||
|
||||
/* A non-root node in the lock file. */
|
||||
/**
|
||||
* A non-root node in the lock file.
|
||||
*/
|
||||
struct LockedNode : Node
|
||||
{
|
||||
FlakeRef lockedRef, originalRef;
|
||||
|
|
@ -63,7 +67,9 @@ struct LockFile
|
|||
|
||||
void write(const Path & path) const;
|
||||
|
||||
/* Check whether this lock file has any unlocked inputs. */
|
||||
/**
|
||||
* Check whether this lock file has any unlocked inputs.
|
||||
*/
|
||||
std::optional<FlakeRef> isUnlocked() const;
|
||||
|
||||
bool operator ==(const LockFile & other) const;
|
||||
|
|
@ -74,7 +80,9 @@ struct LockFile
|
|||
|
||||
static std::string diff(const LockFile & oldLocks, const LockFile & newLocks);
|
||||
|
||||
/* Check that every 'follows' input target exists. */
|
||||
/**
|
||||
* Check that every 'follows' input target exists.
|
||||
*/
|
||||
void check();
|
||||
};
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue