From bd5328814fe8055b3f832a087afcf3ef11b06372 Mon Sep 17 00:00:00 2001 From: Kevin Quick Date: Sat, 26 Sep 2020 14:32:58 -0700 Subject: [PATCH 1/5] Add some internal documentation for flake support objects. --- src/libexpr/flake/flake.hh | 29 +++++++++++++++++++++++++---- src/libexpr/flake/flakeref.hh | 15 +++++++++++++++ src/libfetchers/fetchers.hh | 16 ++++++++++++++++ 3 files changed, 56 insertions(+), 4 deletions(-) diff --git a/src/libexpr/flake/flake.hh b/src/libexpr/flake/flake.hh index 69c779af8..40476a137 100644 --- a/src/libexpr/flake/flake.hh +++ b/src/libexpr/flake/flake.hh @@ -17,20 +17,41 @@ struct FlakeInput; typedef std::map 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 { std::optional ref; - bool isFlake = true; + bool isFlake = true; // true = process flake to get outputs, false = (fetched) static source path std::optional follows; bool absolute = false; // whether 'follows' is relative to the flake root FlakeInputs overrides; }; +// The Flake structure is the main internal representation of a flake.nix file. + struct Flake { - FlakeRef originalRef; - FlakeRef resolvedRef; - FlakeRef lockedRef; + 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 std::optional description; std::shared_ptr sourceInfo; FlakeInputs inputs; diff --git a/src/libexpr/flake/flakeref.hh b/src/libexpr/flake/flakeref.hh index f4eb825a6..ac68cde0e 100644 --- a/src/libexpr/flake/flakeref.hh +++ b/src/libexpr/flake/flakeref.hh @@ -12,10 +12,25 @@ class Store; 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 { + // 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 Path subdir; bool operator==(const FlakeRef & other) const; diff --git a/src/libfetchers/fetchers.hh b/src/libfetchers/fetchers.hh index 89b1e6e7d..f361edf17 100644 --- a/src/libfetchers/fetchers.hh +++ b/src/libfetchers/fetchers.hh @@ -21,6 +21,13 @@ struct Tree 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 { friend struct InputScheme; @@ -82,6 +89,15 @@ public: std::optional 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 { virtual std::optional inputFromURL(const ParsedURL & url) = 0; From bcb3da3b6b510bd24f2bc973b39bf43d92fad7ce Mon Sep 17 00:00:00 2001 From: Kevin Quick Date: Mon, 28 Sep 2020 08:58:14 -0700 Subject: [PATCH 2/5] Fix spelling error. --- src/libfetchers/fetchers.hh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libfetchers/fetchers.hh b/src/libfetchers/fetchers.hh index f361edf17..6aa8a3422 100644 --- a/src/libfetchers/fetchers.hh +++ b/src/libfetchers/fetchers.hh @@ -22,7 +22,7 @@ struct Tree 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 +// user-supplied input attribute in the flake.nix file, and contains // 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 From 5ae164b7cf2dd7ca1846f349b57131913aa7cf55 Mon Sep 17 00:00:00 2001 From: Kevin Quick Date: Mon, 28 Sep 2020 09:23:05 -0700 Subject: [PATCH 3/5] Update description of FlakeRef, incorporating suggestion. --- src/libexpr/flake/flakeref.hh | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/src/libexpr/flake/flakeref.hh b/src/libexpr/flake/flakeref.hh index ac68cde0e..2596dd18e 100644 --- a/src/libexpr/flake/flakeref.hh +++ b/src/libexpr/flake/flakeref.hh @@ -12,12 +12,19 @@ class Store; 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 +// 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 +// path. +// +// Each flake will have a number of FlakeRef objects: one for each +// input to the flake. +// +// The normal method of constructing a FlakeRef is 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 From 128c98ab0961ba234774508663f591758d3a2178 Mon Sep 17 00:00:00 2001 From: Kevin Quick Date: Mon, 28 Sep 2020 09:34:23 -0700 Subject: [PATCH 4/5] Clarification in the description of the FlakeInput. --- src/libexpr/flake/flake.hh | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/src/libexpr/flake/flake.hh b/src/libexpr/flake/flake.hh index 40476a137..44cf636b5 100644 --- a/src/libexpr/flake/flake.hh +++ b/src/libexpr/flake/flake.hh @@ -17,15 +17,16 @@ struct FlakeInput; typedef std::map FlakeInputs; -// FlakeInput is the flake-level parsed form of the "input" entries in +// 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 normally constructed by the 'parseFlakeInput' +// function which parses the input specification in the '.flake' file +// to create a 'FlakeRef' (a fetcher, the fetcher-specific +// representation of the input specification, and possibly 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 From 887be7b6f233822f03d156dafa156276d59162fd Mon Sep 17 00:00:00 2001 From: Kevin Quick Date: Mon, 28 Sep 2020 09:37:26 -0700 Subject: [PATCH 5/5] Switch comment format from '// ...' to '/* ... */' for consistency. --- src/libexpr/flake/flake.hh | 39 +++++++++++++++---------------- src/libexpr/flake/flakeref.hh | 43 ++++++++++++++++++----------------- src/libfetchers/fetchers.hh | 28 ++++++++++++----------- 3 files changed, 57 insertions(+), 53 deletions(-) diff --git a/src/libexpr/flake/flake.hh b/src/libexpr/flake/flake.hh index 44cf636b5..cf62c7741 100644 --- a/src/libexpr/flake/flake.hh +++ b/src/libexpr/flake/flake.hh @@ -17,25 +17,26 @@ struct FlakeInput; typedef std::map FlakeInputs; -// FlakeInput is the 'Flake'-level parsed form of the "input" entries in -// the flake file. -// -// A FlakeInput is normally constructed by the 'parseFlakeInput' -// function which parses the input specification in the '.flake' file -// to create a 'FlakeRef' (a fetcher, the fetcher-specific -// representation of the input specification, and possibly 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. +/* FlakeInput is the 'Flake'-level parsed form of the "input" entries + * in the flake file. + * + * A FlakeInput is normally constructed by the 'parseFlakeInput' + * function which parses the input specification in the '.flake' file + * to create a 'FlakeRef' (a fetcher, the fetcher-specific + * representation of the input specification, and possibly 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 { diff --git a/src/libexpr/flake/flakeref.hh b/src/libexpr/flake/flakeref.hh index 2596dd18e..0292eb210 100644 --- a/src/libexpr/flake/flakeref.hh +++ b/src/libexpr/flake/flakeref.hh @@ -12,32 +12,33 @@ class Store; typedef std::string FlakeId; -// 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 -// path. -// -// Each flake will have a number of FlakeRef objects: one for each -// input to the flake. -// -// The normal method of constructing a FlakeRef is 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. +/* 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 + * path. + * + * Each flake will have a number of FlakeRef objects: one for each + * input to the flake. + * + * The normal method of constructing a FlakeRef is 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 { - // 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; diff --git a/src/libfetchers/fetchers.hh b/src/libfetchers/fetchers.hh index 6aa8a3422..84c954899 100644 --- a/src/libfetchers/fetchers.hh +++ b/src/libfetchers/fetchers.hh @@ -21,12 +21,13 @@ struct Tree struct InputScheme; -// The Input object is generated by a specific fetcher, based on the -// user-supplied input attribute in the flake.nix file, and contains -// 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. +/* The Input object is generated by a specific fetcher, based on the + * user-supplied input attribute in the flake.nix file, and contains + * 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 { @@ -90,13 +91,14 @@ public: }; -// 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. +/* 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 {