diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix index 30152088d..a563c31f8 100644 --- a/doc/manual/generate-manpage.nix +++ b/doc/manual/generate-manpage.nix @@ -38,31 +38,39 @@ let + (if def ? doc then def.doc + "\n\n" else "") - + (let s = showFlags def.flags; in + + (let s = showOptions def.flags; in if s != "" - then "# Flags\n\n${s}" + then "# Options\n\n${s}" else "") ; appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name; - showFlags = flags: - concatStrings - (map (longName: - let flag = flags.${longName}; in - if flag.category or "" != "config" - then - " - `--${longName}`" - + (if flag ? shortName then " / `-${flag.shortName}`" else "") - + (if flag ? labels then " " + (concatStringsSep " " (map (s: "*${s}*") flag.labels)) else "") - + " \n" - + " " + flag.description + "\n\n" - else "") - (attrNames flags)); + showOptions = flags: + let + categories = sort builtins.lessThan (unique (map (cmd: cmd.category) (attrValues flags))); + in + concatStrings (map + (cat: + (if cat != "" + then "**${cat}:**\n\n" + else "") + + concatStrings + (map (longName: + let + flag = flags.${longName}; + in + " - `--${longName}`" + + (if flag ? shortName then " / `-${flag.shortName}`" else "") + + (if flag ? labels then " " + (concatStringsSep " " (map (s: "*${s}*") flag.labels)) else "") + + " \n" + + " " + flag.description + "\n\n" + ) (attrNames (filterAttrs (n: v: v.category == cat) flags)))) + categories); showSynopsis = { command, args }: - "`${command}` [*flags*...] ${concatStringsSep " " + "`${command}` [*option*...] ${concatStringsSep " " (map (arg: "*${arg.label}*" + (if arg ? arity then "" else "...")) args)}\n\n"; processCommand = { command, def, filename }: diff --git a/src/libexpr/common-eval-args.cc b/src/libexpr/common-eval-args.cc index ffe782454..aa14bf79b 100644 --- a/src/libexpr/common-eval-args.cc +++ b/src/libexpr/common-eval-args.cc @@ -12,9 +12,12 @@ namespace nix { MixEvalArgs::MixEvalArgs() { + auto category = "Common evaluation options"; + addFlag({ .longName = "arg", .description = "Pass the value *expr* as the argument *name* to Nix functions.", + .category = category, .labels = {"name", "expr"}, .handler = {[&](std::string name, std::string expr) { autoArgs[name] = 'E' + expr; }} }); @@ -22,6 +25,7 @@ MixEvalArgs::MixEvalArgs() addFlag({ .longName = "argstr", .description = "Pass the string *string* as the argument *name* to Nix functions.", + .category = category, .labels = {"name", "string"}, .handler = {[&](std::string name, std::string s) { autoArgs[name] = 'S' + s; }}, }); @@ -30,6 +34,7 @@ MixEvalArgs::MixEvalArgs() .longName = "include", .shortName = 'I', .description = "Add *path* to the list of locations used to look up `<...>` file names.", + .category = category, .labels = {"path"}, .handler = {[&](std::string s) { searchPath.push_back(s); }} }); @@ -37,6 +42,7 @@ MixEvalArgs::MixEvalArgs() addFlag({ .longName = "impure", .description = "Allow access to mutable paths and repositories.", + .category = category, .handler = {[&]() { evalSettings.pureEval = false; }}, @@ -45,6 +51,7 @@ MixEvalArgs::MixEvalArgs() addFlag({ .longName = "override-flake", .description = "Override the flake registries, redirecting *original-ref* to *resolved-ref*.", + .category = category, .labels = {"original-ref", "resolved-ref"}, .handler = {[&](std::string _from, std::string _to) { auto from = parseFlakeRef(_from, absPath(".")); diff --git a/src/libmain/common-args.cc b/src/libmain/common-args.cc index bd5573e5d..ff96ee7d5 100644 --- a/src/libmain/common-args.cc +++ b/src/libmain/common-args.cc @@ -11,18 +11,21 @@ MixCommonArgs::MixCommonArgs(const string & programName) .longName = "verbose", .shortName = 'v', .description = "Increase the logging verbosity level.", + .category = loggingCategory, .handler = {[]() { verbosity = (Verbosity) (verbosity + 1); }}, }); addFlag({ .longName = "quiet", .description = "Decrease the logging verbosity level.", + .category = loggingCategory, .handler = {[]() { verbosity = verbosity > lvlError ? (Verbosity) (verbosity - 1) : lvlError; }}, }); addFlag({ .longName = "debug", .description = "Set the logging verbosity level to 'debug'.", + .category = loggingCategory, .handler = {[]() { verbosity = lvlDebug; }}, }); @@ -52,6 +55,7 @@ MixCommonArgs::MixCommonArgs(const string & programName) addFlag({ .longName = "log-format", .description = "Set the format of log output; one of `raw`, `internal-json`, `bar` or `bar-with-logs`.", + .category = loggingCategory, .labels = {"format"}, .handler = {[](std::string format) { setLogFormat(format); }}, }); @@ -66,7 +70,7 @@ MixCommonArgs::MixCommonArgs(const string & programName) }} }); - std::string cat = "config"; + std::string cat = "Options to override configuration settings"; globalConfig.convertToArgs(*this, cat); // Backward compatibility hack: nix-env already had a --system flag. diff --git a/src/libmain/common-args.hh b/src/libmain/common-args.hh index 47f341619..8e53a7361 100644 --- a/src/libmain/common-args.hh +++ b/src/libmain/common-args.hh @@ -4,6 +4,9 @@ namespace nix { +//static constexpr auto commonArgsCategory = "Miscellaneous common options"; +static constexpr auto loggingCategory = "Logging-related options"; + struct MixCommonArgs : virtual Args { string programName; @@ -16,7 +19,12 @@ struct MixDryRun : virtual Args MixDryRun() { - mkFlag(0, "dry-run", "Show what this command would do without doing it.", &dryRun); + addFlag({ + .longName = "dry-run", + .description = "Show what this command would do without doing it.", + //.category = commonArgsCategory, + .handler = {&dryRun, true}, + }); } }; @@ -26,7 +34,12 @@ struct MixJSON : virtual Args MixJSON() { - mkFlag(0, "json", "Produce output in JSON format, suitable for consumption by another program.", &json); + addFlag({ + .longName = "json", + .description = "Produce output in JSON format, suitable for consumption by another program.", + //.category = commonArgsCategory, + .handler = {&json, true}, + }); } }; diff --git a/src/libutil/args.cc b/src/libutil/args.cc index 6d57e1a34..71bae0504 100644 --- a/src/libutil/args.cc +++ b/src/libutil/args.cc @@ -195,8 +195,7 @@ nlohmann::json Args::toJSON() j["shortName"] = std::string(1, flag->shortName); if (flag->description != "") j["description"] = flag->description; - if (flag->category != "") - j["category"] = flag->category; + j["category"] = flag->category; if (flag->handler.arity != ArityAny) j["arity"] = flag->handler.arity; if (!flag->labels.empty()) diff --git a/src/libutil/args.hh b/src/libutil/args.hh index fda7852cd..b1020b101 100644 --- a/src/libutil/args.hh +++ b/src/libutil/args.hh @@ -91,7 +91,7 @@ protected: { } }; - /* Flags. */ + /* Options. */ struct Flag { typedef std::shared_ptr ptr; diff --git a/src/nix/command.cc b/src/nix/command.cc index 20eeefe91..614dee788 100644 --- a/src/nix/command.cc +++ b/src/nix/command.cc @@ -61,6 +61,7 @@ StorePathsCommand::StorePathsCommand(bool recursive) addFlag({ .longName = "no-recursive", .description = "Apply operation to specified paths only.", + .category = installablesCategory, .handler = {&this->recursive, false}, }); else @@ -68,10 +69,16 @@ StorePathsCommand::StorePathsCommand(bool recursive) .longName = "recursive", .shortName = 'r', .description = "Apply operation to closure of the specified paths.", + .category = installablesCategory, .handler = {&this->recursive, true}, }); - mkFlag(0, "all", "Apply the operation to every store path.", &all); + addFlag({ + .longName = "all", + .description = "Apply the operation to every store path.", + .category = installablesCategory, + .handler = {&all, true}, + }); } void StorePathsCommand::run(ref store) diff --git a/src/nix/command.hh b/src/nix/command.hh index 791dd0f1e..ed6980075 100644 --- a/src/nix/command.hh +++ b/src/nix/command.hh @@ -23,6 +23,8 @@ static constexpr Command::Category catSecondary = 100; static constexpr Command::Category catUtility = 101; static constexpr Command::Category catNixInstallation = 102; +static constexpr auto installablesCategory = "Options that change the interpretation of installables"; + struct NixMultiCommand : virtual MultiCommand, virtual Command { nlohmann::json toJSON() override; diff --git a/src/nix/installables.cc b/src/nix/installables.cc index 34ee238bf..4e6bf4a9a 100644 --- a/src/nix/installables.cc +++ b/src/nix/installables.cc @@ -58,39 +58,47 @@ void completeFlakeInputPath( MixFlakeOptions::MixFlakeOptions() { + auto category = "Common flake-related options"; + addFlag({ .longName = "recreate-lock-file", .description = "Recreate the flake's lock file from scratch.", + .category = category, .handler = {&lockFlags.recreateLockFile, true} }); addFlag({ .longName = "no-update-lock-file", .description = "Do not allow any updates to the flake's lock file.", + .category = category, .handler = {&lockFlags.updateLockFile, false} }); addFlag({ .longName = "no-write-lock-file", .description = "Do not write the flake's newly generated lock file.", + .category = category, .handler = {&lockFlags.writeLockFile, false} }); addFlag({ .longName = "no-registries", .description = "Don't allow lookups in the flake registries.", + .category = category, .handler = {&lockFlags.useRegistries, false} }); addFlag({ .longName = "commit-lock-file", .description = "Commit changes to the flake's lock file.", + .category = category, .handler = {&lockFlags.commitLockFile, true} }); addFlag({ .longName = "update-input", .description = "Update a specific flake input (ignoring its previous entry in the lock file).", + .category = category, .labels = {"input-path"}, .handler = {[&](std::string s) { lockFlags.inputUpdates.insert(flake::parseInputPath(s)); @@ -104,6 +112,7 @@ MixFlakeOptions::MixFlakeOptions() addFlag({ .longName = "override-input", .description = "Override a specific flake input (e.g. `dwarffs/nixpkgs`).", + .category = category, .labels = {"input-path", "flake-url"}, .handler = {[&](std::string inputPath, std::string flakeRef) { lockFlags.inputOverrides.insert_or_assign( @@ -115,6 +124,7 @@ MixFlakeOptions::MixFlakeOptions() addFlag({ .longName = "inputs-from", .description = "Use the inputs of the specified flake as registry entries.", + .category = category, .labels = {"flake-url"}, .handler = {[&](std::string flakeRef) { auto evalState = getEvalState(); @@ -144,6 +154,7 @@ SourceExprCommand::SourceExprCommand() .longName = "file", .shortName = 'f', .description = "Interpret installables as attribute paths relative to the Nix expression stored in *file*.", + .category = installablesCategory, .labels = {"file"}, .handler = {&file}, .completer = completePath @@ -152,6 +163,7 @@ SourceExprCommand::SourceExprCommand() addFlag({ .longName = "expr", .description = "Interpret installables as attribute paths relative to the Nix expression *expr*.", + .category = installablesCategory, .labels = {"expr"}, .handler = {&expr} }); @@ -159,6 +171,7 @@ SourceExprCommand::SourceExprCommand() addFlag({ .longName = "derivation", .description = "Operate on the store derivation rather than its outputs.", + .category = installablesCategory, .handler = {&operateOn, OperateOn::Derivation}, }); } diff --git a/src/nix/main.cc b/src/nix/main.cc index 77a13c913..58b643cc5 100644 --- a/src/nix/main.cc +++ b/src/nix/main.cc @@ -80,6 +80,7 @@ struct NixArgs : virtual MultiCommand, virtual MixCommonArgs .longName = "print-build-logs", .shortName = 'L', .description = "Print full build logs on standard error.", + .category = loggingCategory, .handler = {[&]() {setLogFormat(LogFormat::barWithLogs); }}, }); diff --git a/src/nix/sigs.cc b/src/nix/sigs.cc index 3445182f2..c64b472b6 100644 --- a/src/nix/sigs.cc +++ b/src/nix/sigs.cc @@ -16,7 +16,7 @@ struct CmdCopySigs : StorePathsCommand addFlag({ .longName = "substituter", .shortName = 's', - .description = "Use signatures from specified store.", + .description = "Copy signatures from the specified store.", .labels = {"store-uri"}, .handler = {[&](std::string s) { substituterUris.push_back(s); }}, }); @@ -24,7 +24,7 @@ struct CmdCopySigs : StorePathsCommand std::string description() override { - return "copy path signatures from substituters (like binary caches)"; + return "copy store path signatures from substituters"; } void run(ref store, StorePaths storePaths) override @@ -110,7 +110,7 @@ struct CmdSign : StorePathsCommand std::string description() override { - return "sign the specified paths"; + return "sign store paths"; } void run(ref store, StorePaths storePaths) override