aboutsummaryrefslogtreecommitdiff
path: root/src/libutil
diff options
context:
space:
mode:
Diffstat (limited to 'src/libutil')
-rw-r--r--src/libutil/ansicolor.hh7
-rw-r--r--src/libutil/archive.hh52
-rw-r--r--src/libutil/args.cc17
-rw-r--r--src/libutil/args.hh2
-rw-r--r--src/libutil/canon-path.hh6
-rw-r--r--src/libutil/comparator.hh10
-rw-r--r--src/libutil/compression.cc6
-rw-r--r--src/libutil/compression.hh2
-rw-r--r--src/libutil/config.cc20
-rw-r--r--src/libutil/config.hh19
-rw-r--r--src/libutil/error.hh32
-rw-r--r--src/libutil/experimental-features.cc231
-rw-r--r--src/libutil/experimental-features.hh37
-rw-r--r--src/libutil/hash.cc2
-rw-r--r--src/libutil/hash.hh2
-rw-r--r--src/libutil/logging.cc5
-rw-r--r--src/libutil/logging.hh23
-rw-r--r--src/libutil/serialise.cc45
-rw-r--r--src/libutil/serialise.hh14
-rw-r--r--src/libutil/tests/config.cc48
-rw-r--r--src/libutil/thread-pool.hh16
-rw-r--r--src/libutil/util.hh488
22 files changed, 802 insertions, 282 deletions
diff --git a/src/libutil/ansicolor.hh b/src/libutil/ansicolor.hh
index 54721649c..86becafa6 100644
--- a/src/libutil/ansicolor.hh
+++ b/src/libutil/ansicolor.hh
@@ -1,9 +1,12 @@
#pragma once
-///@file
+/**
+ * @file
+ *
+ * @brief Some ANSI escape sequences.
+ */
namespace nix {
-/* Some ANSI escape sequences. */
#define ANSI_NORMAL "\e[0m"
#define ANSI_BOLD "\e[1m"
#define ANSI_FAINT "\e[2m"
diff --git a/src/libutil/archive.hh b/src/libutil/archive.hh
index 60e33dd40..2cf164a41 100644
--- a/src/libutil/archive.hh
+++ b/src/libutil/archive.hh
@@ -20,39 +20,41 @@ namespace nix {
*
* The format is as follows:
*
- * IF path points to a REGULAR FILE:
- * dump(path) = attrs(
- * [ ("type", "regular")
- * , ("contents", contents(path))
- * ])
+ * ```
+ * IF path points to a REGULAR FILE:
+ * dump(path) = attrs(
+ * [ ("type", "regular")
+ * , ("contents", contents(path))
+ * ])
*
- * IF path points to a DIRECTORY:
- * dump(path) = attrs(
- * [ ("type", "directory")
- * , ("entries", concat(map(f, sort(entries(path)))))
- * ])
- * where f(fn) = attrs(
- * [ ("name", fn)
- * , ("file", dump(path + "/" + fn))
- * ])
+ * IF path points to a DIRECTORY:
+ * dump(path) = attrs(
+ * [ ("type", "directory")
+ * , ("entries", concat(map(f, sort(entries(path)))))
+ * ])
+ * where f(fn) = attrs(
+ * [ ("name", fn)
+ * , ("file", dump(path + "/" + fn))
+ * ])
*
- * where:
+ * where:
*
- * attrs(as) = concat(map(attr, as)) + encN(0)
- * attrs((a, b)) = encS(a) + encS(b)
+ * attrs(as) = concat(map(attr, as)) + encN(0)
+ * attrs((a, b)) = encS(a) + encS(b)
*
- * encS(s) = encN(len(s)) + s + (padding until next 64-bit boundary)
+ * encS(s) = encN(len(s)) + s + (padding until next 64-bit boundary)
*
- * encN(n) = 64-bit little-endian encoding of n.
+ * encN(n) = 64-bit little-endian encoding of n.
*
- * contents(path) = the contents of a regular file.
+ * contents(path) = the contents of a regular file.
*
- * sort(strings) = lexicographic sort by 8-bit value (strcmp).
+ * sort(strings) = lexicographic sort by 8-bit value (strcmp).
*
- * entries(path) = the entries of a directory, without `.' and
- * `..'.
+ * entries(path) = the entries of a directory, without `.` and
+ * `..`.
*
- * `+' denotes string concatenation.
+ * `+` denotes string concatenation.
+ * ```
*/
void dumpPath(const Path & path, Sink & sink,
PathFilter & filter = defaultPathFilter);
@@ -88,7 +90,7 @@ struct ParseSink
/**
* If the NAR archive contains a single file at top-level, then save
- * the contents of the file to `s'. Otherwise barf.
+ * the contents of the file to `s`. Otherwise barf.
*/
struct RetrieveRegularNARSink : ParseSink
{
diff --git a/src/libutil/args.cc b/src/libutil/args.cc
index fc009592c..081dbeb28 100644
--- a/src/libutil/args.cc
+++ b/src/libutil/args.cc
@@ -236,8 +236,6 @@ nlohmann::json Args::toJSON()
auto flags = nlohmann::json::object();
for (auto & [name, flag] : longFlags) {
- /* Skip experimental flags when listing flags. */
- if (!experimentalFeatureSettings.isEnabled(flag->experimentalFeature)) continue;
auto j = nlohmann::json::object();
if (flag->aliases.count(name)) continue;
if (flag->shortName)
@@ -249,6 +247,11 @@ nlohmann::json Args::toJSON()
j["arity"] = flag->handler.arity;
if (!flag->labels.empty())
j["labels"] = flag->labels;
+ // TODO With C++23 use `std::optional::tranform`
+ if (auto & xp = flag->experimentalFeature)
+ j["experimental-feature"] = showExperimentalFeature(*xp);
+ else
+ j["experimental-feature"] = nullptr;
flags[name] = std::move(j);
}
@@ -345,6 +348,11 @@ Strings argvToStrings(int argc, char * * argv)
return args;
}
+std::optional<ExperimentalFeature> Command::experimentalFeature ()
+{
+ return { Xp::NixCommand };
+}
+
MultiCommand::MultiCommand(const Commands & commands_)
: commands(commands_)
{
@@ -408,6 +416,11 @@ nlohmann::json MultiCommand::toJSON()
cat["id"] = command->category();
cat["description"] = trim(categories[command->category()]);
j["category"] = std::move(cat);
+ // TODO With C++23 use `std::optional::tranform`
+ if (auto xp = command->experimentalFeature())
+ cat["experimental-feature"] = showExperimentalFeature(*xp);
+ else
+ cat["experimental-feature"] = nullptr;
cmds[name] = std::move(j);
}
diff --git a/src/libutil/args.hh b/src/libutil/args.hh
index 07d0d8eae..d90129796 100644
--- a/src/libutil/args.hh
+++ b/src/libutil/args.hh
@@ -236,6 +236,8 @@ struct Command : virtual public Args
static constexpr Category catDefault = 0;
+ virtual std::optional<ExperimentalFeature> experimentalFeature ();
+
virtual Category category() { return catDefault; }
};
diff --git a/src/libutil/canon-path.hh b/src/libutil/canon-path.hh
index 30f43b5a4..eefe05ed5 100644
--- a/src/libutil/canon-path.hh
+++ b/src/libutil/canon-path.hh
@@ -194,8 +194,10 @@ public:
*/
bool isAllowed(const std::set<CanonPath> & allowed) const;
- /* Return a representation `x` of `path` relative to `this`, i.e.
- `CanonPath(this.makeRelative(x), this) == path`. */
+ /**
+ * Return a representation `x` of `path` relative to `this`, i.e.
+ * `CanonPath(this.makeRelative(x), this) == path`.
+ */
std::string makeRelative(const CanonPath & path) const;
};
diff --git a/src/libutil/comparator.hh b/src/libutil/comparator.hh
index 2b5424b3d..9f661c5c3 100644
--- a/src/libutil/comparator.hh
+++ b/src/libutil/comparator.hh
@@ -17,12 +17,12 @@
* }
* ```
*/
-#define GENERATE_ONE_CMP(COMPARATOR, MY_TYPE, FIELDS...) \
+#define GENERATE_ONE_CMP(COMPARATOR, MY_TYPE, ...) \
bool operator COMPARATOR(const MY_TYPE& other) const { \
- const MY_TYPE* me = this; \
- auto fields1 = std::make_tuple( FIELDS ); \
- me = &other; \
- auto fields2 = std::make_tuple( FIELDS ); \
+ __VA_OPT__(const MY_TYPE* me = this;) \
+ auto fields1 = std::make_tuple( __VA_ARGS__ ); \
+ __VA_OPT__(me = &other;) \
+ auto fields2 = std::make_tuple( __VA_ARGS__ ); \
return fields1 COMPARATOR fields2; \
}
#define GENERATE_EQUAL(args...) GENERATE_ONE_CMP(==, args)
diff --git a/src/libutil/compression.cc b/src/libutil/compression.cc
index 89180e7a7..ba0847cde 100644
--- a/src/libutil/compression.cc
+++ b/src/libutil/compression.cc
@@ -23,7 +23,7 @@ struct ChunkedCompressionSink : CompressionSink
{
uint8_t outbuf[32 * 1024];
- void write(std::string_view data) override
+ void writeUnbuffered(std::string_view data) override
{
const size_t CHUNK_SIZE = sizeof(outbuf) << 2;
while (!data.empty()) {
@@ -103,7 +103,7 @@ struct ArchiveCompressionSink : CompressionSink
throw Error(reason, archive_error_string(this->archive));
}
- void write(std::string_view data) override
+ void writeUnbuffered(std::string_view data) override
{
ssize_t result = archive_write_data(archive, data.data(), data.length());
if (result <= 0) check(result);
@@ -136,7 +136,7 @@ struct NoneSink : CompressionSink
warn("requested compression level '%d' not supported by compression method 'none'", level);
}
void finish() override { flush(); }
- void write(std::string_view data) override { nextSink(data); }
+ void writeUnbuffered(std::string_view data) override { nextSink(data); }
};
struct BrotliDecompressionSink : ChunkedCompressionSink
diff --git a/src/libutil/compression.hh b/src/libutil/compression.hh
index 3892831c2..4e53a7b3c 100644
--- a/src/libutil/compression.hh
+++ b/src/libutil/compression.hh
@@ -12,7 +12,7 @@ namespace nix {
struct CompressionSink : BufferedSink, FinishSink
{
using BufferedSink::operator ();
- using BufferedSink::write;
+ using BufferedSink::writeUnbuffered;
using FinishSink::finish;
};
diff --git a/src/libutil/config.cc b/src/libutil/config.cc
index 8d63536d6..a42f3a849 100644
--- a/src/libutil/config.cc
+++ b/src/libutil/config.cc
@@ -70,17 +70,10 @@ void AbstractConfig::reapplyUnknownSettings()
set(s.first, s.second);
}
-// Whether we should process the option. Excludes aliases, which are handled elsewhere, and disabled features.
-static bool applicable(const Config::SettingData & sd)
-{
- return !sd.isAlias
- && experimentalFeatureSettings.isEnabled(sd.setting->experimentalFeature);
-}
-
void Config::getSettings(std::map<std::string, SettingInfo> & res, bool overriddenOnly)
{
for (auto & opt : _settings)
- if (applicable(opt.second) && (!overriddenOnly || opt.second.setting->overridden))
+ if (!opt.second.isAlias && (!overriddenOnly || opt.second.setting->overridden))
res.emplace(opt.first, SettingInfo{opt.second.setting->to_string(), opt.second.setting->description});
}
@@ -154,7 +147,7 @@ nlohmann::json Config::toJSON()
{
auto res = nlohmann::json::object();
for (auto & s : _settings)
- if (applicable(s.second))
+ if (!s.second.isAlias)
res.emplace(s.first, s.second.setting->toJSON());
return res;
}
@@ -163,7 +156,7 @@ std::string Config::toKeyValue()
{
auto res = std::string();
for (auto & s : _settings)
- if (applicable(s.second))
+ if (s.second.isAlias)
res += fmt("%s = %s\n", s.first, s.second.setting->to_string());
return res;
}
@@ -171,9 +164,6 @@ std::string Config::toKeyValue()
void Config::convertToArgs(Args & args, const std::string & category)
{
for (auto & s : _settings) {
- /* We do include args for settings gated on disabled
- experimental-features. The args themselves however will also be
- gated on any experimental feature the underlying setting is. */
if (!s.second.isAlias)
s.second.setting->convertToArg(args, category);
}
@@ -201,6 +191,10 @@ std::map<std::string, nlohmann::json> AbstractSetting::toJSONObject()
std::map<std::string, nlohmann::json> obj;
obj.emplace("description", description);
obj.emplace("aliases", aliases);
+ if (experimentalFeature)
+ obj.emplace("experimentalFeature", *experimentalFeature);
+ else
+ obj.emplace("experimentalFeature", nullptr);
return obj;
}
diff --git a/src/libutil/config.hh b/src/libutil/config.hh
index 3c1d70294..162626791 100644
--- a/src/libutil/config.hh
+++ b/src/libutil/config.hh
@@ -371,8 +371,23 @@ extern GlobalConfig globalConfig;
struct ExperimentalFeatureSettings : Config {
- Setting<std::set<ExperimentalFeature>> experimentalFeatures{this, {}, "experimental-features",
- "Experimental Nix features to enable."};
+ Setting<std::set<ExperimentalFeature>> experimentalFeatures{
+ this, {}, "experimental-features",
+ R"(
+ Experimental features that are enabled.
+
+ Example:
+
+ ```
+ experimental-features = nix-command flakes
+ ```
+
+ The following experimental features are available:
+
+ {{#include experimental-features-shortlist.md}}
+
+ Experimental features are [further documented in the manual](@docroot@/contributing/experimental-features.md).
+ )"};
/**
* Check whether the given experimental feature is enabled.
diff --git a/src/libutil/error.hh b/src/libutil/error.hh
index eafc6a540..6a0923081 100644
--- a/src/libutil/error.hh
+++ b/src/libutil/error.hh
@@ -1,5 +1,19 @@
#pragma once
-///@file
+/**
+ * @file
+ *
+ * @brief This file defines two main structs/classes used in nix error handling.
+ *
+ * ErrorInfo provides a standard payload of error information, with conversion to string
+ * happening in the logger rather than at the call site.
+ *
+ * BaseError is the ancestor of nix specific exceptions (and Interrupted), and contains
+ * an ErrorInfo.
+ *
+ * ErrorInfo structs are sent to the logger as part of an exception, or directly with the
+ * logError or logWarning macros.
+ * See libutil/tests/logging.cc for usage examples.
+ */
#include "suggestions.hh"
#include "ref.hh"
@@ -27,22 +41,6 @@
namespace nix {
-/*
-
- This file defines two main structs/classes used in nix error handling.
-
- ErrorInfo provides a standard payload of error information, with conversion to string
- happening in the logger rather than at the call site.
-
- BaseError is the ancestor of nix specific exceptions (and Interrupted), and contains
- an ErrorInfo.
-
- ErrorInfo structs are sent to the logger as part of an exception, or directly with the
- logError or logWarning macros.
-
- See libutil/tests/logging.cc for usage examples.
-
- */
typedef enum {
lvlError = 0,
diff --git a/src/libutil/experimental-features.cc b/src/libutil/experimental-features.cc
index 58d762ebb..5b4418714 100644
--- a/src/libutil/experimental-features.cc
+++ b/src/libutil/experimental-features.cc
@@ -5,29 +5,209 @@
namespace nix {
-std::map<ExperimentalFeature, std::string> stringifiedXpFeatures = {
- { Xp::CaDerivations, "ca-derivations" },
- { Xp::ImpureDerivations, "impure-derivations" },
- { Xp::Flakes, "flakes" },
- { Xp::NixCommand, "nix-command" },
- { Xp::RecursiveNix, "recursive-nix" },
- { Xp::NoUrlLiterals, "no-url-literals" },
- { Xp::FetchClosure, "fetch-closure" },
- { Xp::ReplFlake, "repl-flake" },
- { Xp::AutoAllocateUids, "auto-allocate-uids" },
- { Xp::Cgroups, "cgroups" },
- { Xp::DiscardReferences, "discard-references" },
+struct ExperimentalFeatureDetails
+{
+ ExperimentalFeature tag;
+ std::string_view name;
+ std::string_view description;
};
+constexpr std::array<ExperimentalFeatureDetails, 11> xpFeatureDetails = {{
+ {
+ .tag = Xp::CaDerivations,
+ .name = "ca-derivations",
+ .description = R"(
+ Allow derivations to be content-addressed in order to prevent
+ rebuilds when changes to the derivation do not result in changes to
+ the derivation's output. See
+ [__contentAddressed](@docroot@/language/advanced-attributes.md#adv-attr-__contentAddressed)
+ for details.
+ )",
+ },
+ {
+ .tag = Xp::ImpureDerivations,
+ .name = "impure-derivations",
+ .description = R"(
+ Allow derivations to produce non-fixed outputs by setting the
+ `__impure` derivation attribute to `true`. An impure derivation can
+ have differing outputs each time it is built.
+
+ Example:
+
+ ```
+ derivation {
+ name = "impure";
+ builder = /bin/sh;
+ __impure = true; # mark this derivation as impure
+ args = [ "-c" "read -n 10 random < /dev/random; echo $random > $out" ];
+ system = builtins.currentSystem;
+ }
+ ```
+
+ Each time this derivation is built, it can produce a different
+ output (as the builder outputs random bytes to `$out`). Impure
+ derivations also have access to the network, and only fixed-output
+ or other impure derivations can rely on impure derivations. Finally,
+ an impure derivation cannot also be
+ [content-addressed](#xp-feature-ca-derivations).
+ )",
+ },
+ {
+ .tag = Xp::Flakes,
+ .name = "flakes",
+ .description = R"(
+ Enable flakes. See the manual entry for [`nix
+ flake`](@docroot@/command-ref/new-cli/nix3-flake.md) for details.
+ )",
+ },
+ {
+ .tag = Xp::NixCommand,
+ .name = "nix-command",
+ .description = R"(
+ Enable the new `nix` subcommands. See the manual on
+ [`nix`](@docroot@/command-ref/new-cli/nix.md) for details.
+ )",
+ },
+ {
+ .tag = Xp::RecursiveNix,
+ .name = "recursive-nix",
+ .description = R"(
+ Allow derivation builders to call Nix, and thus build derivations
+ recursively.
+
+ Example:
+
+ ```
+ with import <nixpkgs> {};
+
+ runCommand "foo"
+ {
+ buildInputs = [ nix jq ];
+ NIX_PATH = "nixpkgs=${<nixpkgs>}";
+ }
+ ''
+ hello=$(nix-build -E '(import <nixpkgs> {}).hello.overrideDerivation (args: { name = "recursive-hello"; })')
+
+ mkdir -p $out/bin
+ ln -s $hello/bin/hello $out/bin/hello
+ ''
+ ```
+
+ An important restriction on recursive builders is disallowing
+ arbitrary substitutions. For example, running
+
+ ```
+ nix-store -r /nix/store/kmwd1hq55akdb9sc7l3finr175dajlby-hello-2.10
+ ```
+
+ in the above `runCommand` script would be disallowed, as this could
+ lead to derivations with hidden dependencies or breaking
+ reproducibility by relying on the current state of the Nix store. An
+ exception would be if
+ `/nix/store/kmwd1hq55akdb9sc7l3finr175dajlby-hello-2.10` were
+ already in the build inputs or built by a previous recursive Nix
+ call.
+ )",
+ },
+ {
+ .tag = Xp::NoUrlLiterals,
+ .name = "no-url-literals",
+ .description = R"(
+ Disallow unquoted URLs as part of the Nix language syntax. The Nix
+ language allows for URL literals, like so:
+
+ ```
+ $ nix repl
+ Welcome to Nix 2.15.0. Type :? for help.
+
+ nix-repl> http://foo
+ "http://foo"
+ ```
+
+ But enabling this experimental feature will cause the Nix parser to
+ throw an error when encountering a URL literal:
+
+ ```
+ $ nix repl --extra-experimental-features 'no-url-literals'
+ Welcome to Nix 2.15.0. Type :? for help.
+
+ nix-repl> http://foo
+ error: URL literals are disabled
+
+ at «string»:1:1:
+
+ 1| http://foo
+ | ^
+
+ ```
+
+ While this is currently an experimental feature, unquoted URLs are
+ being deprecated and their usage is discouraged.
+
+ The reason is that, as opposed to path literals, URLs have no
+ special properties that distinguish them from regular strings, URLs
+ containing parameters have to be quoted anyway, and unquoted URLs
+ may confuse external tooling.
+ )",
+ },
+ {
+ .tag = Xp::FetchClosure,
+ .name = "fetch-closure",
+ .description = R"(
+ Enable the use of the [`fetchClosure`](@docroot@/language/builtins.md#builtins-fetchClosure) built-in function in the Nix language.
+ )",
+ },
+ {
+ .tag = Xp::ReplFlake,
+ .name = "repl-flake",
+ .description = R"(
+ Allow passing [installables](@docroot@/command-ref/new-cli/nix.md#installables) to `nix repl`, making its interface consistent with the other experimental commands.
+ )",
+ },
+ {
+ .tag = Xp::AutoAllocateUids,
+ .name = "auto-allocate-uids",
+ .description = R"(
+ Allows Nix to automatically pick UIDs for builds, rather than creating
+ `nixbld*` user accounts. See the [`auto-allocate-uids`](#conf-auto-allocate-uids) setting for details.
+ )",
+ },
+ {
+ .tag = Xp::Cgroups,
+ .name = "cgroups",
+ .description = R"(
+ Allows Nix to execute builds inside cgroups. See
+ the [`use-cgroups`](#conf-use-cgroups) setting for details.
+ )",
+ },
+ {
+ .tag = Xp::DiscardReferences,
+ .name = "discard-references",
+ .description = R"(
+ Allow the use of the [`unsafeDiscardReferences`](@docroot@/language/advanced-attributes.html#adv-attr-unsafeDiscardReferences) attribute in derivations
+ that use [structured attributes](@docroot@/language/advanced-attributes.html#adv-attr-structuredAttrs). This disables scanning of outputs for
+ runtime dependencies.
+ )",
+ },
+}};
+
+static_assert(
+ []() constexpr {
+ for (auto [index, feature] : enumerate(xpFeatureDetails))
+ if (index != (size_t)feature.tag)
+ return false;
+ return true;
+ }(),
+ "array order does not match enum tag order");
+
const std::optional<ExperimentalFeature> parseExperimentalFeature(const std::string_view & name)
{
using ReverseXpMap = std::map<std::string_view, ExperimentalFeature>;
- static auto reverseXpMap = []()
- {
+ static std::unique_ptr<ReverseXpMap> reverseXpMap = []() {
auto reverseXpMap = std::make_unique<ReverseXpMap>();
- for (auto & [feature, name] : stringifiedXpFeatures)
- (*reverseXpMap)[name] = feature;
+ for (auto & xpFeature : xpFeatureDetails)
+ (*reverseXpMap)[xpFeature.name] = xpFeature.tag;
return reverseXpMap;
}();
@@ -37,20 +217,27 @@ const std::optional<ExperimentalFeature> parseExperimentalFeature(const std::str
return std::nullopt;
}
-std::string_view showExperimentalFeature(const ExperimentalFeature feature)
+std::string_view showExperimentalFeature(const ExperimentalFeature tag)
+{
+ assert((size_t)tag < xpFeatureDetails.size());
+ return xpFeatureDetails[(size_t)tag].name;
+}
+
+nlohmann::json documentExperimentalFeatures()
{
- const auto ret = get(stringifiedXpFeatures, feature);
- assert(ret);
- return *ret;
+ StringMap res;
+ for (auto & xpFeature : xpFeatureDetails)
+ res[std::string { xpFeature.name }] =
+ trim(stripIndentation(xpFeature.description));
+ return (nlohmann::json) res;
}
std::set<ExperimentalFeature> parseFeatures(const std::set<std::string> & rawFeatures)
{
std::set<ExperimentalFeature> res;
- for (auto & rawFeature : rawFeatures) {
+ for (auto & rawFeature : rawFeatures)
if (auto feature = parseExperimentalFeature(rawFeature))
res.insert(*feature);
- }
return res;
}
diff --git a/src/libutil/experimental-features.hh b/src/libutil/experimental-features.hh
index 5948ad7ad..8ef66263a 100644
--- a/src/libutil/experimental-features.hh
+++ b/src/libutil/experimental-features.hh
@@ -11,8 +11,9 @@ namespace nix {
/**
* The list of available experimental features.
*
- * If you update this, don’t forget to also change the map defining their
- * string representation in the corresponding `.cc` file.
+ * If you update this, don’t forget to also change the map defining
+ * their string representation and documentation in the corresponding
+ * `.cc` file as well.
*/
enum struct ExperimentalFeature
{
@@ -34,26 +35,52 @@ enum struct ExperimentalFeature
*/
using Xp = ExperimentalFeature;
+/**
+ * Parse an experimental feature (enum value) from its name. Experimental
+ * feature flag names are hyphenated and do not contain spaces.
+ */
const std::optional<ExperimentalFeature> parseExperimentalFeature(
const std::string_view & name);
+
+/**
+ * Show the name of an experimental feature. This is the opposite of
+ * parseExperimentalFeature().
+ */
std::string_view showExperimentalFeature(const ExperimentalFeature);
+/**
+ * Compute the documentation of all experimental features.
+ *
+ * See `doc/manual` for how this information is used.
+ */
+nlohmann::json documentExperimentalFeatures();
+
+/**
+ * Shorthand for `str << showExperimentalFeature(feature)`.
+ */
std::ostream & operator<<(
std::ostream & str,
const ExperimentalFeature & feature);
/**
- * Parse a set of strings to the corresponding set of experimental features,
- * ignoring (but warning for) any unkwown feature.
+ * Parse a set of strings to the corresponding set of experimental
+ * features, ignoring (but warning for) any unknown feature.
*/
std::set<ExperimentalFeature> parseFeatures(const std::set<std::string> &);
+/**
+ * An experimental feature was required for some (experimental)
+ * operation, but was not enabled.
+ */
class MissingExperimentalFeature : public Error
{
public:
+ /**
+ * The experimental feature that was required but not enabled.
+ */
ExperimentalFeature missingFeature;
- MissingExperimentalFeature(ExperimentalFeature);
+ MissingExperimentalFeature(ExperimentalFeature missingFeature);
};
/**
diff --git a/src/libutil/hash.cc b/src/libutil/hash.cc
index 5735e4715..0c8f5727d 100644
--- a/src/libutil/hash.cc
+++ b/src/libutil/hash.cc
@@ -343,7 +343,7 @@ HashSink::~HashSink()
delete ctx;
}
-void HashSink::write(std::string_view data)
+void HashSink::writeUnbuffered(std::string_view data)
{
bytes += data.size();
update(ht, *ctx, data);
diff --git a/src/libutil/hash.hh b/src/libutil/hash.hh
index be1fdba2a..ae3ee40f4 100644
--- a/src/libutil/hash.hh
+++ b/src/libutil/hash.hh
@@ -197,7 +197,7 @@ public:
HashSink(HashType ht);
HashSink(const HashSink & h);
~HashSink();
- void write(std::string_view data) override;
+ void writeUnbuffered(std::string_view data) override;
HashResult finish() override;
HashResult currentHash();
};
diff --git a/src/libutil/logging.cc b/src/libutil/logging.cc
index 7cac75ce1..5a2dd99af 100644
--- a/src/libutil/logging.cc
+++ b/src/libutil/logging.cc
@@ -65,9 +65,10 @@ public:
switch (lvl) {
case lvlError: c = '3'; break;
case lvlWarn: c = '4'; break;
- case lvlInfo: c = '5'; break;
+ case lvlNotice: case lvlInfo: c = '5'; break;
case lvlTalkative: case lvlChatty: c = '6'; break;
- default: c = '7';
+ case lvlDebug: case lvlVomit: c = '7';
+ default: c = '7'; break; // should not happen, and missing enum case is reported by -Werror=switch-enum
}
prefix = std::string("<") + c + ">";
}
diff --git a/src/libutil/logging.hh b/src/libutil/logging.hh
index 576068c22..5aa6bee95 100644
--- a/src/libutil/logging.hh
+++ b/src/libutil/logging.hh
@@ -183,12 +183,17 @@ bool handleJSONLogMessage(const std::string & msg,
const Activity & act, std::map<ActivityId, Activity> & activities,
bool trusted);
-extern Verbosity verbosity; /* suppress msgs > this */
+/**
+ * suppress msgs > this
+ */
+extern Verbosity verbosity;
-/* Print a message with the standard ErrorInfo format.
- In general, use these 'log' macros for reporting problems that may require user
- intervention or that need more explanation. Use the 'print' macros for more
- lightweight status messages. */
+/**
+ * Print a message with the standard ErrorInfo format.
+ * In general, use these 'log' macros for reporting problems that may require user
+ * intervention or that need more explanation. Use the 'print' macros for more
+ * lightweight status messages.
+ */
#define logErrorInfo(level, errorInfo...) \
do { \
if ((level) <= nix::verbosity) { \
@@ -199,9 +204,11 @@ extern Verbosity verbosity; /* suppress msgs > this */
#define logError(errorInfo...) logErrorInfo(lvlError, errorInfo)
#define logWarning(errorInfo...) logErrorInfo(lvlWarn, errorInfo)
-/* Print a string message if the current log level is at least the specified
- level. Note that this has to be implemented as a macro to ensure that the
- arguments are evaluated lazily. */
+/**
+ * Print a string message if the current log level is at least the specified
+ * level. Note that this has to be implemented as a macro to ensure that the
+ * arguments are evaluated lazily.
+ */
#define printMsgUsing(loggerParam, level, args...) \
do { \
auto __lvl = level; \
diff --git a/src/libutil/serialise.cc b/src/libutil/serialise.cc
index 7476e6f6c..3d5121a19 100644
--- a/src/libutil/serialise.cc
+++ b/src/libutil/serialise.cc
@@ -20,7 +20,7 @@ void BufferedSink::operator () (std::string_view data)
buffer size. */
if (bufPos + data.size() >= bufSize) {
flush();
- write(data);
+ writeUnbuffered(data);
break;
}
/* Otherwise, copy the bytes to the buffer. Flush the buffer
@@ -38,7 +38,7 @@ void BufferedSink::flush()
if (bufPos == 0) return;
size_t n = bufPos;
bufPos = 0; // don't trigger the assert() in ~BufferedSink()
- write({buffer.get(), n});
+ writeUnbuffered({buffer.get(), n});
}
@@ -48,7 +48,7 @@ FdSink::~FdSink()
}
-void FdSink::write(std::string_view data)
+void FdSink::writeUnbuffered(std::string_view data)
{
written += data.size();
try {
@@ -186,6 +186,22 @@ static DefaultStackAllocator defaultAllocatorSingleton;
StackAllocator *StackAllocator::defaultAllocator = &defaultAllocatorSingleton;
+std::shared_ptr<void> (*create_coro_gc_hook)() = []() -> std::shared_ptr<void> {
+ return {};
+};
+
+/* This class is used for entry and exit hooks on coroutines */
+class CoroutineContext {
+ /* Disable GC when entering the coroutine without the boehm patch,
+ * since it doesn't find the main thread stack in this case.
+ * std::shared_ptr<void> performs type-erasure, so it will call the right
+ * deleter. */
+ const std::shared_ptr<void> coro_gc_hook = create_coro_gc_hook();
+public:
+ CoroutineContext() {};
+ ~CoroutineContext() {};
+};
+
std::unique_ptr<FinishSink> sourceToSink(std::function<void(Source &)> fun)
{
struct SourceToSink : FinishSink
@@ -206,7 +222,8 @@ std::unique_ptr<FinishSink> sourceToSink(std::function<void(Source &)> fun)
if (in.empty()) return;
cur = in;
- if (!coro)
+ if (!coro) {
+ CoroutineContext ctx;
coro = coro_t::push_type(VirtualStackAllocator{}, [&](coro_t::pull_type & yield) {
LambdaSource source([&](char *out, size_t out_len) {
if (cur.empty()) {
@@ -223,17 +240,24 @@ std::unique_ptr<FinishSink> sourceToSink(std::function<void(Source &)> fun)
});
fun(source);
});
+ }
if (!*coro) { abort(); }
- if (!cur.empty()) (*coro)(false);
+ if (!cur.empty()) {
+ CoroutineContext ctx;
+ (*coro)(false);
+ }
}
void finish() override
{
if (!coro) return;
if (!*coro) abort();
- (*coro)(true);
+ {
+ CoroutineContext ctx;
+ (*coro)(true);
+ }
if (*coro) abort();
}
};
@@ -264,18 +288,23 @@ std::unique_ptr<Source> sinkToSource(
size_t read(char * data, size_t len) override
{
- if (!coro)
+ if (!coro) {
+ CoroutineContext ctx;
coro = coro_t::pull_type(VirtualStackAllocator{}, [&](coro_t::push_type & yield) {
LambdaSink sink([&](std::string_view data) {
if (!data.empty()) yield(std::string(data));
});
fun(sink);
});
+ }
if (!*coro) { eof(); abort(); }
if (pos == cur.size()) {
- if (!cur.empty()) (*coro)();
+ if (!cur.empty()) {
+ CoroutineContext ctx;
+ (*coro)();
+ }
cur = coro->get();
pos = 0;
}
diff --git a/src/libutil/serialise.hh b/src/libutil/serialise.hh
index 2cf527023..333c254ea 100644
--- a/src/libutil/serialise.hh
+++ b/src/libutil/serialise.hh
@@ -53,7 +53,9 @@ struct BufferedSink : virtual Sink
void flush();
- virtual void write(std::string_view data) = 0;
+protected:
+
+ virtual void writeUnbuffered(std::string_view data) = 0;
};
@@ -133,7 +135,7 @@ struct FdSink : BufferedSink
~FdSink();
- void write(std::string_view data) override;
+ void writeUnbuffered(std::string_view data) override;
bool good() override;
@@ -520,7 +522,7 @@ struct FramedSink : nix::BufferedSink
}
}
- void write(std::string_view data) override
+ void writeUnbuffered(std::string_view data) override
{
/* Don't send more data if the remote has
encountered an error. */
@@ -551,4 +553,10 @@ struct StackAllocator {
static StackAllocator *defaultAllocator;
};
+/* Disabling GC when entering a coroutine (without the boehm patch).
+ mutable to avoid boehm gc dependency in libutil.
+ */
+extern std::shared_ptr<void> (*create_coro_gc_hook)();
+
+
}
diff --git a/src/libutil/tests/config.cc b/src/libutil/tests/config.cc
index 8be6730dd..f250e934e 100644
--- a/src/libutil/tests/config.cc
+++ b/src/libutil/tests/config.cc
@@ -156,12 +156,54 @@ namespace nix {
}
TEST(Config, toJSONOnNonEmptyConfig) {
+ using nlohmann::literals::operator "" _json;
Config config;
- std::map<std::string, Config::SettingInfo> settings;
- Setting<std::string> setting{&config, "", "name-of-the-setting", "description"};
+ Setting<std::string> setting{
+ &config,
+ "",
+ "name-of-the-setting",
+ "description",
+ };
+ setting.assign("value");
+
+ ASSERT_EQ(config.toJSON(),
+ R"#({
+ "name-of-the-setting": {
+ "aliases": [],
+ "defaultValue": "",
+ "description": "description\n",
+ "documentDefault": true,
+ "value": "value",
+ "experimentalFeature": null
+ }
+ })#"_json);
+ }
+
+ TEST(Config, toJSONOnNonEmptyConfigWithExperimentalSetting) {
+ using nlohmann::literals::operator "" _json;
+ Config config;
+ Setting<std::string> setting{
+ &config,
+ "",
+ "name-of-the-setting",
+ "description",
+ {},
+ true,
+ Xp::Flakes,
+ };
setting.assign("value");
- ASSERT_EQ(config.toJSON().dump(), R"#({"name-of-the-setting":{"aliases":[],"defaultValue":"","description":"description\n","documentDefault":true,"value":"value"}})#");
+ ASSERT_EQ(config.toJSON(),
+ R"#({
+ "name-of-the-setting": {
+ "aliases": [],
+ "defaultValue": "",
+ "description": "description\n",
+ "documentDefault": true,
+ "value": "value",
+ "experimentalFeature": "flakes"
+ }
+ })#"_json);
}
TEST(Config, setSettingAlias) {
diff --git a/src/libutil/thread-pool.hh b/src/libutil/thread-pool.hh
index 14b32279c..0e09fae97 100644
--- a/src/libutil/thread-pool.hh
+++ b/src/libutil/thread-pool.hh
@@ -40,15 +40,15 @@ public:
/**
* Execute work items until the queue is empty.
- *
- * \note Note that work items are allowed to add new items to the
- * queue; this is handled correctly.
*
- * Queue processing stops prematurely if any work item throws an
- * exception. This exception is propagated to the calling thread. If
- * multiple work items throw an exception concurrently, only one
- * item is propagated; the others are printed on stderr and
- * otherwise ignored.
+ * \note Note that work items are allowed to add new items to the
+ * queue; this is handled correctly.
+ *
+ * Queue processing stops prematurely if any work item throws an
+ * exception. This exception is propagated to the calling thread. If
+ * multiple work items throw an exception concurrently, only one
+ * item is propagated; the others are printed on stderr and
+ * otherwise ignored.
*/
void process();
diff --git a/src/libutil/util.hh b/src/libutil/util.hh
index 6c2706cc1..85ab77b1b 100644
--- a/src/libutil/util.hh
+++ b/src/libutil/util.hh
@@ -33,77 +33,112 @@ struct Sink;
struct Source;
-/* The system for which Nix is compiled. */
+/**
+ * The system for which Nix is compiled.
+ */
extern const std::string nativeSystem;
-/* Return an environment variable. */
+/**
+ * @return an environment variable.
+ */
std::optional<std::string> getEnv(const std::string & key);
-/* Return a non empty environment variable. Returns nullopt if the env
-variable is set to "" */
+/**
+ * @return a non empty environment variable. Returns nullopt if the env
+ * variable is set to ""
+ */
std::optional<std::string> getEnvNonEmpty(const std::string & key);
-/* Get the entire environment. */
+/**
+ * Get the entire environment.
+ */
std::map<std::string, std::string> getEnv();
-/* Clear the environment. */
+/**
+ * Clear the environment.
+ */
void clearEnv();
-/* Return an absolutized path, resolving paths relative to the
- specified directory, or the current directory otherwise. The path
- is also canonicalised. */
+/**
+ * @return An absolutized path, resolving paths relative to the
+ * specified directory, or the current directory otherwise. The path
+ * is also canonicalised.
+ */
Path absPath(Path path,
std::optional<PathView> dir = {},
bool resolveSymlinks = false);
-/* Canonicalise a path by removing all `.' or `..' components and
- double or trailing slashes. Optionally resolves all symlink
- components such that each component of the resulting path is *not*
- a symbolic link. */
+/**
+ * Canonicalise a path by removing all `.` or `..` components and
+ * double or trailing slashes. Optionally resolves all symlink
+ * components such that each component of the resulting path is *not*
+ * a symbolic link.
+ */
Path canonPath(PathView path, bool resolveSymlinks = false);
-/* Return the directory part of the given canonical path, i.e.,
- everything before the final `/'. If the path is the root or an
- immediate child thereof (e.g., `/foo'), this means `/'
- is returned.*/
+/**
+ * @return The directory part of the given canonical path, i.e.,
+ * everything before the final `/`. If the path is the root or an
+ * immediate child thereof (e.g., `/foo`), this means `/`
+ * is returned.
+ */
Path dirOf(const PathView path);
-/* Return the base name of the given canonical path, i.e., everything
- following the final `/' (trailing slashes are removed). */
+/**
+ * @return the base name of the given canonical path, i.e., everything
+ * following the final `/` (trailing slashes are removed).
+ */
std::string_view baseNameOf(std::string_view path);
-/* Perform tilde expansion on a path. */
+/**
+ * Perform tilde expansion on a path.
+ */
std::string expandTilde(std::string_view path);
-/* Check whether 'path' is a descendant of 'dir'. Both paths must be
- canonicalized. */
+/**
+ * Check whether 'path' is a descendant of 'dir'. Both paths must be
+ * canonicalized.
+ */
bool isInDir(std::string_view path, std::string_view dir);
-/* Check whether 'path' is equal to 'dir' or a descendant of
- 'dir'. Both paths must be canonicalized. */
+/**
+ * Check whether 'path' is equal to 'dir' or a descendant of
+ * 'dir'. Both paths must be canonicalized.
+ */
bool isDirOrInDir(std::string_view path, std::string_view dir);
-/* Get status of `path'. */
+/**
+ * Get status of `path`.
+ */
struct stat stat(const Path & path);
struct stat lstat(const Path & path);
-/* Return true iff the given path exists. */
+/**
+ * @return true iff the given path exists.
+ */
bool pathExists(const Path & path);
-/* Read the contents (target) of a symbolic link. The result is not
- in any way canonicalised. */
+/**
+ * Read the contents (target) of a symbolic link. The result is not
+ * in any way canonicalised.
+ */
Path readLink(const Path & path);
bool isLink(const Path & path);
-/* Read the contents of a directory. The entries `.' and `..' are
- removed. */
+/**
+ * Read the contents of a directory. The entries `.` and `..` are
+ * removed.
+ */
struct DirEntry
{
std::string name;
ino_t ino;
- unsigned char type; // one of DT_*
+ /**
+ * one of DT_*
+ */
+ unsigned char type;
DirEntry(std::string name, ino_t ino, unsigned char type)
: name(std::move(name)), ino(ino), type(type) { }
};
@@ -114,74 +149,110 @@ DirEntries readDirectory(const Path & path);
unsigned char getFileType(const Path & path);
-/* Read the contents of a file into a string. */
+/**
+ * Read the contents of a file into a string.
+ */
std::string readFile(int fd);
std::string readFile(const Path & path);
void readFile(const Path & path, Sink & sink);
-/* Write a string to a file. */
+/**
+ * Write a string to a file.
+ */
void writeFile(const Path & path, std::string_view s, mode_t mode = 0666, bool sync = false);
void writeFile(const Path & path, Source & source, mode_t mode = 0666, bool sync = false);
-/* Flush a file's parent directory to disk */
+/**
+ * Flush a file's parent directory to disk
+ */
void syncParent(const Path & path);
-/* Read a line from a file descriptor. */
+/**
+ * Read a line from a file descriptor.
+ */
std::string readLine(int fd);
-/* Write a line to a file descriptor. */
+/**
+ * Write a line to a file descriptor.
+ */
void writeLine(int fd, std::string s);
-/* Delete a path; i.e., in the case of a directory, it is deleted
- recursively. It's not an error if the path does not exist. The
- second variant returns the number of bytes and blocks freed. */
+/**
+ * Delete a path; i.e., in the case of a directory, it is deleted
+ * recursively. It's not an error if the path does not exist. The
+ * second variant returns the number of bytes and blocks freed.
+ */
void deletePath(const Path & path);
void deletePath(const Path & path, uint64_t & bytesFreed);
std::string getUserName();
-/* Return the given user's home directory from /etc/passwd. */
+/**
+ * @return the given user's home directory from /etc/passwd.
+ */
Path getHomeOf(uid_t userId);
-/* Return $HOME or the user's home directory from /etc/passwd. */
+/**
+ * @return $HOME or the user's home directory from /etc/passwd.
+ */
Path getHome();
-/* Return $XDG_CACHE_HOME or $HOME/.cache. */
+/**
+ * @return $XDG_CACHE_HOME or $HOME/.cache.
+ */
Path getCacheDir();
-/* Return $XDG_CONFIG_HOME or $HOME/.config. */
+/**
+ * @return $XDG_CONFIG_HOME or $HOME/.config.
+ */
Path getConfigDir();
-/* Return the directories to search for user configuration files */
+/**
+ * @return the directories to search for user configuration files
+ */
std::vector<Path> getConfigDirs();
-/* Return $XDG_DATA_HOME or $HOME/.local/share. */
+/**
+ * @return $XDG_DATA_HOME or $HOME/.local/share.
+ */
Path getDataDir();
-/* Return the path of the current executable. */
+/**
+ * @return the path of the current executable.
+ */
std::optional<Path> getSelfExe();
-/* Return $XDG_STATE_HOME or $HOME/.local/state. */
+/**
+ * @return $XDG_STATE_HOME or $HOME/.local/state.
+ */
Path getStateDir();
-/* Create the Nix state directory and return the path to it. */
+/**
+ * Create the Nix state directory and return the path to it.
+ */
Path createNixStateDir();
-/* Create a directory and all its parents, if necessary. Returns the
- list of created directories, in order of creation. */
+/**
+ * Create a directory and all its parents, if necessary. Returns the
+ * list of created directories, in order of creation.
+ */
Paths createDirs(const Path & path);
inline Paths createDirs(PathView path)
{
return createDirs(Path(path));
}
-/* Create a symlink. */
+/**
+ * Create a symlink.
+ */
void createSymlink(const Path & target, const Path & link,
std::optional<time_t> mtime = {});
-/* Atomically create or replace a symlink. */
+/**
+ * Atomically create or replace a symlink.
+ */
void replaceSymlink(const Path & target, const Path & link,
std::optional<time_t> mtime = {});
@@ -197,24 +268,32 @@ void renameFile(const Path & src, const Path & dst);
void moveFile(const Path & src, const Path & dst);
-/* Wrappers arount read()/write() that read/write exactly the
- requested number of bytes. */
+/**
+ * Wrappers arount read()/write() that read/write exactly the
+ * requested number of bytes.
+ */
void readFull(int fd, char * buf, size_t count);
void writeFull(int fd, std::string_view s, bool allowInterrupts = true);
MakeError(EndOfFile, Error);
-/* Read a file descriptor until EOF occurs. */
+/**
+ * Read a file descriptor until EOF occurs.
+ */
std::string drainFD(int fd, bool block = true, const size_t reserveSize=0);
void drainFD(int fd, Sink & sink, bool block = true);
-/* If cgroups are active, attempt to calculate the number of CPUs available.
- If cgroups are unavailable or if cpu.max is set to "max", return 0. */
+/**
+ * If cgroups are active, attempt to calculate the number of CPUs available.
+ * If cgroups are unavailable or if cpu.max is set to "max", return 0.
+ */
unsigned int getMaxCPU();
-/* Automatic cleanup of resources. */
+/**
+ * Automatic cleanup of resources.
+ */
class AutoDelete
@@ -252,11 +331,15 @@ public:
};
-/* Create a temporary directory. */
+/**
+ * Create a temporary directory.
+ */
Path createTempDir(const Path & tmpRoot = "", const Path & prefix = "nix",
bool includePid = true, bool useGlobalCounter = true, mode_t mode = 0755);
-/* Create a temporary file, returning a file handle and its path. */
+/**
+ * Create a temporary file, returning a file handle and its path.
+ */
std::pair<AutoCloseFD, Path> createTempFile(const Path & prefix = "nix");
@@ -299,27 +382,36 @@ public:
};
-/* Kill all processes running under the specified uid by sending them
- a SIGKILL. */
+/**
+ * Kill all processes running under the specified uid by sending them
+ * a SIGKILL.
+ */
void killUser(uid_t uid);
-/* Fork a process that runs the given function, and return the child
- pid to the caller. */
+/**
+ * Fork a process that runs the given function, and return the child
+ * pid to the caller.
+ */
struct ProcessOptions
{
std::string errorPrefix = "";
bool dieWithParent = true;
bool runExitHandlers = false;
bool allowVfork = false;
- int cloneFlags = 0; // use clone() with the specified flags (Linux only)
+ /**
+ * use clone() with the specified flags (Linux only)
+ */
+ int cloneFlags = 0;
};
pid_t startProcess(std::function<void()> fun, const ProcessOptions & options = ProcessOptions());
-/* Run a program and return its stdout in a string (i.e., like the
- shell backtick operator). */
+/**
+ * Run a program and return its stdout in a string (i.e., like the
+ * shell backtick operator).
+ */
std::string runProgram(Path program, bool searchPath = false,
const Strings & args = Strings(),
const std::optional<std::string> & input = {});
@@ -344,25 +436,35 @@ std::pair<int, std::string> runProgram(RunOptions && options);
void runProgram2(const RunOptions & options);
-/* Change the stack size. */
+/**
+ * Change the stack size.
+ */
void setStackSize(size_t stackSize);
-/* Restore the original inherited Unix process context (such as signal
- masks, stack size). */
+/**
+ * Restore the original inherited Unix process context (such as signal
+ * masks, stack size).
+ */
void restoreProcessContext(bool restoreMounts = true);
-/* Save the current mount namespace. Ignored if called more than
- once. */
+/**
+ * Save the current mount namespace. Ignored if called more than
+ * once.
+ */
void saveMountNamespace();
-/* Restore the mount namespace saved by saveMountNamespace(). Ignored
- if saveMountNamespace() was never called. */
+/**
+ * Restore the mount namespace saved by saveMountNamespace(). Ignored
+ * if saveMountNamespace() was never called.
+ */
void restoreMountNamespace();
-/* Cause this thread to not share any FS attributes with the main
- thread, because this causes setns() in restoreMountNamespace() to
- fail. */
+/**
+ * Cause this thread to not share any FS attributes with the main
+ * thread, because this causes setns() in restoreMountNamespace() to
+ * fail.
+ */
void unshareFilesystem();
@@ -377,16 +479,22 @@ public:
{ }
};
-/* Convert a list of strings to a null-terminated vector of char
- *'s. The result must not be accessed beyond the lifetime of the
- list of strings. */
+/**
+ * Convert a list of strings to a null-terminated vector of `char
+ * *`s. The result must not be accessed beyond the lifetime of the
+ * list of strings.
+ */
std::vector<char *> stringsToCharPtrs(const Strings & ss);
-/* Close all file descriptors except those listed in the given set.
- Good practice in child processes. */
+/**
+ * Close all file descriptors except those listed in the given set.
+ * Good practice in child processes.
+ */
void closeMostFDs(const std::set<int> & exceptions);
-/* Set the close-on-exec flag for the given file descriptor. */
+/**
+ * Set the close-on-exec flag for the given file descriptor.
+ */
void closeOnExec(int fd);
@@ -412,12 +520,16 @@ MakeError(Interrupted, BaseError);
MakeError(FormatError, Error);
-/* String tokenizer. */
+/**
+ * String tokenizer.
+ */
template<class C> C tokenizeString(std::string_view s, std::string_view separators = " \t\n\r");
-/* Concatenate the given strings with a separator between the
- elements. */
+/**
+ * Concatenate the given strings with a separator between the
+ * elements.
+ */
template<class C>
std::string concatStringsSep(const std::string_view sep, const C & ss)
{
@@ -442,7 +554,9 @@ auto concatStrings(Parts && ... parts)
}
-/* Add quotes around a collection of strings. */
+/**
+ * Add quotes around a collection of strings.
+ */
template<class C> Strings quoteStrings(const C & c)
{
Strings res;
@@ -451,16 +565,23 @@ template<class C> Strings quoteStrings(const C & c)
return res;
}
-/* Remove trailing whitespace from a string. FIXME: return
- std::string_view. */
+/**
+ * Remove trailing whitespace from a string.
+ *
+ * \todo return std::string_view.
+ */
std::string chomp(std::string_view s);
-/* Remove whitespace from the start and end of a string. */
+/**
+ * Remove whitespace from the start and end of a string.
+ */
std::string trim(std::string_view s, std::string_view whitespace = " \n\r\t");
-/* Replace all occurrences of a string inside another string. */
+/**
+ * Replace all occurrences of a string inside another string.
+ */
std::string replaceStrings(
std::string s,
std::string_view from,
@@ -470,14 +591,18 @@ std::string replaceStrings(
std::string rewriteStrings(std::string s, const StringMap & rewrites);
-/* Convert the exit status of a child as returned by wait() into an
- error string. */
+/**
+ * Convert the exit status of a child as returned by wait() into an
+ * error string.
+ */
std::string statusToString(int status);
bool statusOk(int status);
-/* Parse a string into an integer. */
+/**
+ * Parse a string into an integer.
+ */
template<class N>
std::optional<N> string2Int(const std::string_view s)
{
@@ -490,8 +615,10 @@ std::optional<N> string2Int(const std::string_view s)
}
}
-/* Like string2Int(), but support an optional suffix 'K', 'M', 'G' or
- 'T' denoting a binary unit prefix. */
+/**
+ * Like string2Int(), but support an optional suffix 'K', 'M', 'G' or
+ * 'T' denoting a binary unit prefix.
+ */
template<class N>
N string2IntWithUnitPrefix(std::string_view s)
{
@@ -512,7 +639,9 @@ N string2IntWithUnitPrefix(std::string_view s)
throw UsageError("'%s' is not an integer", s);
}
-/* Parse a string into a float. */
+/**
+ * Parse a string into a float.
+ */
template<class N>
std::optional<N> string2Float(const std::string_view s)
{
@@ -524,7 +653,9 @@ std::optional<N> string2Float(const std::string_view s)
}
-/* Convert a little-endian integer to host order. */
+/**
+ * Convert a little-endian integer to host order.
+ */
template<typename T>
T readLittleEndian(unsigned char * p)
{
@@ -536,66 +667,90 @@ T readLittleEndian(unsigned char * p)
}
-/* Return true iff `s' starts with `prefix'. */
+/**
+ * @return true iff `s` starts with `prefix`.
+ */
bool hasPrefix(std::string_view s, std::string_view prefix);
-/* Return true iff `s' ends in `suffix'. */
+/**
+ * @return true iff `s` ends in `suffix`.
+ */
bool hasSuffix(std::string_view s, std::string_view suffix);
-/* Convert a string to lower case. */
+/**
+ * Convert a string to lower case.
+ */
std::string toLower(const std::string & s);
-/* Escape a string as a shell word. */
+/**
+ * Escape a string as a shell word.
+ */
std::string shellEscape(const std::string_view s);
-/* Exception handling in destructors: print an error message, then
- ignore the exception. */
+/**
+ * Exception handling in destructors: print an error message, then
+ * ignore the exception.
+ */
void ignoreException(Verbosity lvl = lvlError);
-/* Tree formatting. */
+/**
+ * Tree formatting.
+ */
constexpr char treeConn[] = "├───";
constexpr char treeLast[] = "└───";
constexpr char treeLine[] = "│ ";
constexpr char treeNull[] = " ";
-/* Determine whether ANSI escape sequences are appropriate for the
- present output. */
+/**
+ * Determine whether ANSI escape sequences are appropriate for the
+ * present output.
+ */
bool shouldANSI();
-/* Truncate a string to 'width' printable characters. If 'filterAll'
- is true, all ANSI escape sequences are filtered out. Otherwise,
- some escape sequences (such as colour setting) are copied but not
- included in the character count. Also, tabs are expanded to
- spaces. */
+/**
+ * Truncate a string to 'width' printable characters. If 'filterAll'
+ * is true, all ANSI escape sequences are filtered out. Otherwise,
+ * some escape sequences (such as colour setting) are copied but not
+ * included in the character count. Also, tabs are expanded to
+ * spaces.
+ */
std::string filterANSIEscapes(std::string_view s,
bool filterAll = false,
unsigned int width = std::numeric_limits<unsigned int>::max());
-/* Base64 encoding/decoding. */
+/**
+ * Base64 encoding/decoding.
+ */
std::string base64Encode(std::string_view s);
std::string base64Decode(std::string_view s);
-/* Remove common leading whitespace from the lines in the string
- 's'. For example, if every line is indented by at least 3 spaces,
- then we remove 3 spaces from the start of every line. */
+/**
+ * Remove common leading whitespace from the lines in the string
+ * 's'. For example, if every line is indented by at least 3 spaces,
+ * then we remove 3 spaces from the start of every line.
+ */
std::string stripIndentation(std::string_view s);
-/* Get the prefix of 's' up to and excluding the next line break (LF
- optionally preceded by CR), and the remainder following the line
- break. */
+/**
+ * Get the prefix of 's' up to and excluding the next line break (LF
+ * optionally preceded by CR), and the remainder following the line
+ * break.
+ */
std::pair<std::string_view, std::string_view> getLine(std::string_view s);
-/* Get a value for the specified key from an associate container. */
+/**
+ * Get a value for the specified key from an associate container.
+ */
template <class T>
const typename T::mapped_type * get(const T & map, const typename T::key_type & key)
{
@@ -612,7 +767,9 @@ typename T::mapped_type * get(T & map, const typename T::key_type & key)
return &i->second;
}
-/* Get a value for the specified key from an associate container, or a default value if the key isn't present. */
+/**
+ * Get a value for the specified key from an associate container, or a default value if the key isn't present.
+ */
template <class T>
const typename T::mapped_type & getOr(T & map,
const typename T::key_type & key,
@@ -623,7 +780,9 @@ const typename T::mapped_type & getOr(T & map,
return i->second;
}
-/* Remove and return the first item from a container. */
+/**
+ * Remove and return the first item from a container.
+ */
template <class T>
std::optional<typename T::value_type> remove_begin(T & c)
{
@@ -635,7 +794,9 @@ std::optional<typename T::value_type> remove_begin(T & c)
}
-/* Remove and return the first item from a container. */
+/**
+ * Remove and return the first item from a container.
+ */
template <class T>
std::optional<typename T::value_type> pop(T & c)
{
@@ -650,8 +811,10 @@ template<typename T>
class Callback;
-/* Start a thread that handles various signals. Also block those signals
- on the current thread (and thus any threads created by it). */
+/**
+ * Start a thread that handles various signals. Also block those signals
+ * on the current thread (and thus any threads created by it).
+ */
void startSignalHandlerThread();
struct InterruptCallback
@@ -659,16 +822,20 @@ struct InterruptCallback
virtual ~InterruptCallback() { };
};
-/* Register a function that gets called on SIGINT (in a non-signal
- context). */
+/**
+ * Register a function that gets called on SIGINT (in a non-signal
+ * context).
+ */
std::unique_ptr<InterruptCallback> createInterruptCallback(
std::function<void()> callback);
void triggerInterrupt();
-/* A RAII class that causes the current thread to receive SIGUSR1 when
- the signal handler thread receives SIGINT. That is, this allows
- SIGINT to be multiplexed to multiple threads. */
+/**
+ * A RAII class that causes the current thread to receive SIGUSR1 when
+ * the signal handler thread receives SIGINT. That is, this allows
+ * SIGINT to be multiplexed to multiple threads.
+ */
struct ReceiveInterrupts
{
pthread_t target;
@@ -682,8 +849,10 @@ struct ReceiveInterrupts
-/* A RAII helper that increments a counter on construction and
- decrements it on destruction. */
+/**
+ * A RAII helper that increments a counter on construction and
+ * decrements it on destruction.
+ */
template<typename T>
struct MaintainCount
{
@@ -694,33 +863,50 @@ struct MaintainCount
};
-/* Return the number of rows and columns of the terminal. */
+/**
+ * @return the number of rows and columns of the terminal.
+ */
std::pair<unsigned short, unsigned short> getWindowSize();
-/* Used in various places. */
+/**
+ * Used in various places.
+ */
typedef std::function<bool(const Path & path)> PathFilter;
extern PathFilter defaultPathFilter;
-/* Common initialisation performed in child processes. */
+/**
+ * Common initialisation performed in child processes.
+ */
void commonChildInit();
-/* Create a Unix domain socket. */
+/**
+ * Create a Unix domain socket.
+ */
AutoCloseFD createUnixDomainSocket();
-/* Create a Unix domain socket in listen mode. */
+/**
+ * Create a Unix domain socket in listen mode.
+ */
AutoCloseFD createUnixDomainSocket(const Path & path, mode_t mode);
-/* Bind a Unix domain socket to a path. */
+/**
+ * Bind a Unix domain socket to a path.
+ */
void bind(int fd, const std::string & path);
-/* Connect to a Unix domain socket. */
+/**
+ * Connect to a Unix domain socket.
+ */
void connect(int fd, const std::string & path);
-// A Rust/Python-like enumerate() iterator adapter.
-// Borrowed from http://reedbeta.com/blog/python-like-enumerate-in-cpp17.
+/**
+ * A Rust/Python-like enumerate() iterator adapter.
+ *
+ * Borrowed from http://reedbeta.com/blog/python-like-enumerate-in-cpp17.
+ */
template <typename T,
typename TIter = decltype(std::begin(std::declval<T>())),
typename = decltype(std::end(std::declval<T>()))>
@@ -730,23 +916,25 @@ constexpr auto enumerate(T && iterable)
{
size_t i;
TIter iter;
- bool operator != (const iterator & other) const { return iter != other.iter; }
- void operator ++ () { ++i; ++iter; }
- auto operator * () const { return std::tie(i, *iter); }
+ constexpr bool operator != (const iterator & other) const { return iter != other.iter; }
+ constexpr void operator ++ () { ++i; ++iter; }
+ constexpr auto operator * () const { return std::tie(i, *iter); }
};
struct iterable_wrapper
{
T iterable;
- auto begin() { return iterator{ 0, std::begin(iterable) }; }
- auto end() { return iterator{ 0, std::end(iterable) }; }
+ constexpr auto begin() { return iterator{ 0, std::begin(iterable) }; }
+ constexpr auto end() { return iterator{ 0, std::end(iterable) }; }
};
return iterable_wrapper{ std::forward<T>(iterable) };
}
-// C++17 std::visit boilerplate
+/**
+ * C++17 std::visit boilerplate
+ */
template<class... Ts> struct overloaded : Ts... { using Ts::operator()...; };
template<class... Ts> overloaded(Ts...) -> overloaded<Ts...>;
@@ -754,8 +942,10 @@ template<class... Ts> overloaded(Ts...) -> overloaded<Ts...>;
std::string showBytes(uint64_t bytes);
-/* Provide an addition operator between strings and string_views
- inexplicably omitted from the standard library. */
+/**
+ * Provide an addition operator between strings and string_views
+ * inexplicably omitted from the standard library.
+ */
inline std::string operator + (const std::string & s1, std::string_view s2)
{
auto s = s1;
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-22 19:16:08 +0000