fails dedupe with `EAGAIN` when a send is in progress. bees handles
`EAGAIN` automatically via a retry loop.
+## Configuration debug options
+
+* `--show-builtin-config VERSION`
+
+ Write the built-in configuration for `VERSION` to standard output and exit.
+ `VERSION` may be a numeric config version accepted by this bees build, the
+ alias `CURRENT` or `STABLE`, or a release alias such as `v0.11`.
+
+ This command does not load a filesystem, global config file, local config
+ file, environment-derived paths, or `--config` / `--option` input. It is
+ intended for offline inspection of the compiled-in defaults.
+
+* `--show-config ROOT_PATH`
+
+ Load configuration for `ROOT_PATH`, write the merged configuration to
+ standard output, and exit without running deduplication. `ROOT_PATH` must
+ be the root of a btrfs filesystem tree (subvol id 5), the same as a normal
+ bees run.
+
+ The output is a self-documenting INI snapshot: each key is written with
+ the highest-priority non-blank documentation comment found anywhere in
+ the fallback chain, so the dumped file shows both the effective value and
+ the builtin documentation for each key. Keys are written in
+ alphabetical order within each section.
+
## Logging options
* `--timestamps` or `-t`
#include <cmath>
#include <sstream>
#include <sys/statfs.h>
+#include <vector>
unique_ptr<BeesConfig::DefaultMap> BeesConfig::s_defaults;
unique_ptr<BeesConfig::PreviousMap> BeesConfig::s_previous;
BeesConfig::set_version_defaults(Innie &target, const string &version)
{
BEESTRACE("resolving builtin config version '" << version << "'");
+ // Resolve through the alias table rather than through entries in
+ // s_defaults: this runs for --show-builtin-config, which never builds a
+ // BeesConfig because it has no filesystem to build one against.
const auto resolved = resolve_version(version);
if (!s_defaults || !s_defaults->count(resolved)) {
THROW_ERROR(invalid_argument,
return m_innie.sections(prefix);
}
+const Innie &
+BeesConfig::innie() const
+{
+ return m_innie;
+}
+
+/// Build a fresh Innie that captures the merged value and best comment for
+/// every key visible through @p merged. Used by bees_show_config to produce
+/// a self-documenting INI snapshot.
+///
+/// Top-level section names come from Innie::root_sections(), which walks
+/// the fallback chain and returns every immediate child of the root node
+/// (including namespace-only nodes). This keeps the dump schema-agnostic:
+/// user-defined top-level sections are captured along with builtin names.
+///
+/// For each (section, key) pair, the merged value and the highest-priority
+/// non-blank comment (from get_comment) are written into @p out. Section-
+/// header comments are also copied across so the dump preserves the prose
+/// that documents each [section] in the source config.
+void
+bees_build_dump_innie(const Innie &merged, Innie &out)
+{
+ BEESTRACE("bees_build_dump_innie");
+
+ // Copy keys, key-level comments, and the section-header comment for one
+ // concrete section (no recursion). sections() below enumerates every
+ // content-bearing descendant as a compound relative name, so a single
+ // call from each top-level section covers the full sub-hierarchy.
+ const auto dump_one_section = [&](const string §ion) {
+ BEESTRACE("dumping section " << section);
+ const string section_comment = merged.get_section_comment(section);
+ if (!section_comment.empty()) {
+ out.set_section_comment(section, section_comment);
+ }
+ for (const auto &key : merged.keys(section)) {
+ const string sk = section + "." + key;
+ out.set(sk, merged.get(sk));
+ const string comment = merged.get_comment(sk);
+ if (!comment.empty()) {
+ out.set_comment(sk, comment);
+ }
+ }
+ };
+
+ for (const auto &top : merged.root_sections()) {
+ dump_one_section(top);
+ // Content-bearing children are returned as compound relative
+ // names (e.g. "extent.128K" under "scan").
+ for (const auto &child : merged.sections(top)) {
+ dump_one_section(top + "." + child);
+ }
+ }
+}
+
+void
+bees_show_builtin_config(const string &version)
+{
+ // What a version resolves to is not the same as the text it registered
+ // once inheritance is involved, and Innie::write() dumps a single rep.
+ // Build the resolved view and dump it the way --show-config does.
+ Innie resolved;
+ BeesConfig::set_version_defaults(resolved, version);
+ Innie out;
+ out.set_origin("builtin version " + version);
+ bees_build_dump_innie(resolved, out);
+ out.write(cout);
+}
+
+void
+bees_show_config(const BeesConfig &cfg)
+{
+ BEESTRACE("dumping merged config to stdout");
+ Innie out;
+ out.set_origin("merged view");
+ bees_build_dump_innie(cfg.innie(), out);
+ out.write(cout);
+}
+
bool
bees_parse_bool(const string& str)
{
/// Return the set of section-name suffixes immediately under @p prefix.
/// E.g. sections("scan.extent") returns {"128K", "512K", ...}.
set<string> sections(const string &prefix) const;
+ /// Return the merged Innie for direct key/section access. Used by the
+ /// config dump helpers below, which walk every visible section rather
+ /// than looking up known keys through the typed get() template.
+ const Innie &innie() const;
/**
* Look up @p section_and_key (e.g. @c "scanner/threads") in the merged
throw;
}
}
-
};
+/// @name Configuration dump helpers
+/// @{
+
+/// Build a merged INI snapshot into @p out. For each (section, key) visible
+/// in @p merged, write the merged value and the highest-priority non-blank
+/// comment into @p out. Exposed for unit testing; production code calls
+/// bees_show_config() which wraps this.
+void bees_build_dump_innie(const Innie &merged, Innie &out);
+
+/// Write the merged config to stdout.
+void bees_show_config(const BeesConfig &cfg);
+
+/// Write the resolved defaults for a builtin config version to stdout, without
+/// loading filesystem or user configuration. Accepts any name in
+/// version_aliases(), including release aliases such as "v0.11".
+void bees_show_builtin_config(const string &version);
+
+/// @}
+
/// @name Configuration value parsing helpers
/// @{
--config FILE Read configuration options from FILE
-o, --option Set one configuration option in `key=value` format
+Configuration debug options:
+ --show-builtin-config VERSION
+ Write builtin config VERSION to stdout and exit.
+ --show-config ROOT_PATH
+ Write the merged config for ROOT_PATH to stdout.
+ See `docs/options.md` for details.
+
Load management options:
-c, --thread-count Exact worker thread count (overrides factor)
[thread.thread-max]
THROW_CHECK1(invalid_argument, argc, argc >= 0);
+ string show_builtin_config_version;
+ bool show_merged_config = false;
+ string show_config_root_path;
+ int show_config_option_count = 0;
+
+ // --config and --option are recorded here and applied further down,
+ // rather than acted on as getopt_long reaches them. --show-builtin-config
+ // promises to read nothing, and option order is the caller's to choose:
+ // applied inline, `--config f.conf --show-builtin-config 2` would have
+ // already read f.conf by the time the early exit ran.
+ struct ConfigInput {
+ enum class Type {
+ File,
+ Option,
+ };
+ Type type;
+ string text;
+ };
+ vector<ConfigInput> config_inputs;
+
// Construct an Innie
Innie bconfig;
},
{ .name = "config", .has_arg = required_argument,
.fn = [&]() {
- ifstream ifs(optarg);
- if (!ifs.is_open()) {
- THROW_ERRNO("cannot open config file '" << optarg << "' for reading");
- }
- bconfig.read(ifs);
+ config_inputs.push_back({ ConfigInput::Type::File, optarg });
}
},
{ .name = "option", .has_arg = required_argument, .val = 'o',
- .fn = [&]() { bconfig.read(optarg); }
+ .fn = [&]() {
+ config_inputs.push_back({ ConfigInput::Type::Option, optarg });
+ }
+ },
+ { .name = "show-builtin-config", .has_arg = required_argument,
+ .fn = [&]() {
+ ++show_config_option_count;
+ show_builtin_config_version = optarg;
+ }
+ },
+ { .name = "show-config", .has_arg = required_argument,
+ .fn = [&]() {
+ ++show_config_option_count;
+ show_merged_config = true;
+ show_config_root_path = optarg;
+ }
},
{ .name = "help", .has_arg = no_argument, .val = 'h',
.fn = [&]() {
// Log verbosity has been set, so now we can start setting things up
- if (optind + 1 != argc) {
+ const bool show_builtin_config = !show_builtin_config_version.empty();
+ if (show_config_option_count > 1) {
+ BEESLOGERR("Only one --show-*-config option may be used");
+ return EXIT_FAILURE;
+ }
+ if (show_builtin_config) {
+ if (optind != argc) {
+ BEESLOGERR("--show-builtin-config does not take a filesystem path");
+ return EXIT_FAILURE;
+ }
+ bees_show_builtin_config(show_builtin_config_version);
+ return EXIT_SUCCESS;
+ }
+
+ string root_path;
+ if (show_merged_config) {
+ if (optind != argc) {
+ BEESLOGERR("--show-config takes ROOT_PATH as its option argument");
+ return EXIT_FAILURE;
+ }
+ root_path = show_config_root_path;
+ } else if (optind + 1 == argc) {
+ root_path = argv[optind++];
+ } else {
BEESLOGERR("Exactly one filesystem path required");
return EXIT_FAILURE;
}
+ for (const auto &input : config_inputs) {
+ if (input.type == ConfigInput::Type::File) {
+ ifstream ifs(input.text);
+ if (!ifs.is_open()) {
+ THROW_ERRNO("cannot open config file '" << input.text << "' for reading");
+ }
+ bconfig.read(ifs);
+ } else {
+ bconfig.read(input.text);
+ }
+ }
+
const char *base_dir = getenv("BEESHOME");
if (base_dir) {
bconfig.set("path.home", base_dir);
BEESTRACE("context constructed");
// Set root path and open root FD
- string root_path = argv[optind++];
bc->set_root_path(root_path);
// Set configuration
bc->set_config(bconfig);
+ // If --show-config was requested, write the merged view and exit.
+ if (show_merged_config) {
+ BEESTRACE("showing config and exiting");
+ bees_show_config(bc->get_config());
+ return EXIT_SUCCESS;
+ }
+
// Start each scanner independently based on config.
// --scan-mode only sets the config keys; it does not directly select the scanner.
// Both subvol and extent scanners may run simultaneously if both are enabled.