Add some internal documentation for flake support objects.

This commit is contained in:
Kevin Quick 2020-09-26 14:32:58 -07:00
parent 8b4a542d17
commit bd5328814f
No known key found for this signature in database
GPG key ID: E6D7733599CC0A21
3 changed files with 56 additions and 4 deletions

View file

@ -17,20 +17,41 @@ struct FlakeInput;
typedef std::map<FlakeId, FlakeInput> FlakeInputs; typedef std::map<FlakeId, FlakeInput> FlakeInputs;
// FlakeInput is the flake-level parsed form of the "input" entries in
// the flake file.
//
// A FlakeInput is normally constructed by initially
// first constructing a FlakeRef (a fetcher, the fetcher-specific
// representation of the input specification, and the fetched local
// store path result) and then creating this FlakeInput to hold that
// FlakeRef, along with anything that might override that FlakeRef
// (like command-line overrides or "follows" specifications).
//
// A FlakeInput is also sometimes constructed directly from a FlakeRef
// instead of starting at the flake-file input specification
// (e.g. overrides, follows, and implicit inputs).
//
// A FlakeInput will usually have one of either "ref" or "follows"
// set. If not otherwise specified, a "ref" will be generated to a
// 'type="indirect"' flake, which is treated as simply the name of a
// flake to be resolved in the registry.
struct FlakeInput struct FlakeInput
{ {
std::optional<FlakeRef> ref; std::optional<FlakeRef> ref;
bool isFlake = true; bool isFlake = true; // true = process flake to get outputs, false = (fetched) static source path
std::optional<InputPath> follows; std::optional<InputPath> follows;
bool absolute = false; // whether 'follows' is relative to the flake root bool absolute = false; // whether 'follows' is relative to the flake root
FlakeInputs overrides; FlakeInputs overrides;
}; };
// The Flake structure is the main internal representation of a flake.nix file.
struct Flake struct Flake
{ {
FlakeRef originalRef; FlakeRef originalRef; // the original flake specification (by the user)
FlakeRef resolvedRef; FlakeRef resolvedRef; // registry references and caching resolved to the specific underlying flake
FlakeRef lockedRef; FlakeRef lockedRef; // the specific local store result of invoking the fetcher
std::optional<std::string> description; std::optional<std::string> description;
std::shared_ptr<const fetchers::Tree> sourceInfo; std::shared_ptr<const fetchers::Tree> sourceInfo;
FlakeInputs inputs; FlakeInputs inputs;

View file

@ -12,10 +12,25 @@ class Store;
typedef std::string FlakeId; typedef std::string FlakeId;
// The FlakeRef represents a local nix store reference to a flake
// input for a Flake (it may be helpful to think of this object by the
// alternate name of "InputRefForFlake"). It is constructed by
// starting with an input description (usually the attrs or a url from
// the flake file), locating a fetcher for that input, and then
// capturing the Input object that fetcher generates (usually via
// FlakeRef::fromAttrs(attrs) or parseFlakeRef(url) calls).
//
// The actual fetch not have been performed yet (i.e. a FlakeRef may
// 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 struct FlakeRef
{ {
// fetcher-specific representation of the input, sufficient to
// perform the fetch operation.
fetchers::Input input; fetchers::Input input;
// sub-path within the fetched input that represents this input
Path subdir; Path subdir;
bool operator==(const FlakeRef & other) const; bool operator==(const FlakeRef & other) const;

View file

@ -21,6 +21,13 @@ struct Tree
struct InputScheme; struct InputScheme;
// The Input object is generated by a specific fetcher, based on the
// user-supplied input attribute in the flake.nix file, and contians
// the information that the specific fetcher needs to perform the
// actual fetch. The Input object is most commonly created via the
// "fromURL()" or "fromAttrs()" static functions which are provided the
// url or attrset specified in the flake file.
struct Input struct Input
{ {
friend struct InputScheme; friend struct InputScheme;
@ -82,6 +89,15 @@ public:
std::optional<time_t> getLastModified() const; std::optional<time_t> getLastModified() const;
}; };
// The InputScheme represents a type of fetcher. Each fetcher
// registers with nix at startup time. When processing an input for a
// flake, each scheme is given an opportunity to "recognize" that
// input from the url or attributes in the flake file's specification
// and return an Input object to represent the input if it is
// recognized. The Input object contains the information the fetcher
// needs to actually perform the "fetch()" when called.
struct InputScheme struct InputScheme
{ {
virtual std::optional<Input> inputFromURL(const ParsedURL & url) = 0; virtual std::optional<Input> inputFromURL(const ParsedURL & url) = 0;