Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/+cli-help.doc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
The `--help` text matches what the commands do: the top-level help names exit status 78 from `stack admit`; the second `stack admit` example reads the quota and the scheduler inside `--lock` with `--quota-cmd` and `--live-jobs-cmd`, instead of expanding `squeue` before the lock; `campaign --help` shows `campaign run`; `stack generation --help` maps 2026.06 to 2026.1; and `stack batch --installed-modulerc` says it reads a module tree as well as a `.modulerc.lua` file.
7 changes: 4 additions & 3 deletions docs/orgmode/reference/cli.org
Original file line number Diff line number Diff line change
Expand Up @@ -525,7 +525,7 @@ eb-stack stack batch \
(--root FILE.eb... | --roots-file ROOTS.txt) \
--easyconfigs TREE [--easyconfigs OVERLAY]... \
[--commit-tree COMMIT=DIR]... \
--installed INSTALLED.txt [--installed-modulerc MODULERC]... \
--installed INSTALLED.txt [--installed-modulerc PATH]... \
[--open-prs OPEN.json]... [--open-repo EESSI/software-layer] \
--eessi-version 2026.06 --easybuild-version 5.4.1 --generation 2026.1 \
[--filter-deps NAME,NAME...] \
Expand Down Expand Up @@ -841,8 +841,9 @@ together; a root whose set meets an open pull request's waits for it.
Open pull requests come from ~--open-prs~ (~pr-overlap --pr~ JSON) and
~--open-repo~, which reads the open pull requests of that repository over
HTTPS. ~--commit-tree~ supplies the easyconfigs an open pull request pins
with ~from-commit~. ~--installed-modulerc~ adds ~module_version~ aliases to
the installed list. The rest are packed ~--size~ roots per pull request in
with ~from-commit~. ~--installed-modulerc~, a ~.modulerc.lua~ file or a
module tree, adds ~module_version~ aliases to the installed list. The rest
are packed ~--size~ roots per pull request in
a fixed order, so the same inputs give the same plan. With
~--easyconfigs-repo~, a root the ~--easybuild-version~ release lacks gets a
~from-commit~ pin. Each ~batch-NN~ directory holds the EESSI easystacks, a
Expand Down
7 changes: 4 additions & 3 deletions llms-full.txt
Original file line number Diff line number Diff line change
Expand Up @@ -7184,7 +7184,7 @@ eb-stack stack batch \
(--root FILE.eb... | --roots-file ROOTS.txt) \
--easyconfigs TREE [--easyconfigs OVERLAY]... \
[--commit-tree COMMIT=DIR]... \
--installed INSTALLED.txt [--installed-modulerc MODULERC]... \
--installed INSTALLED.txt [--installed-modulerc PATH]... \
[--open-prs OPEN.json]... [--open-repo EESSI/software-layer] \
--eessi-version 2026.06 --easybuild-version 5.4.1 --generation 2026.1 \
[--filter-deps NAME,NAME...] \
Expand Down Expand Up @@ -7500,8 +7500,9 @@ together; a root whose set meets an open pull request's waits for it.
Open pull requests come from `--open-prs` (`pr-overlap --pr` JSON) and
`--open-repo`, which reads the open pull requests of that repository over
HTTPS. `--commit-tree` supplies the easyconfigs an open pull request pins
with `from-commit`. `--installed-modulerc` adds `module_version` aliases to
the installed list. The rest are packed `--size` roots per pull request in
with `from-commit`. `--installed-modulerc`, a `.modulerc.lua` file or a
module tree, adds `module_version` aliases to the installed list. The rest
are packed `--size` roots per pull request in
a fixed order, so the same inputs give the same plan. With
`--easyconfigs-repo`, a root the `--easybuild-version` release lacks gets a
`from-commit` pin. Each `batch-NN` directory holds the EESSI easystacks, a
Expand Down
4 changes: 2 additions & 2 deletions src/generation_lint.rs
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
//! Toolchain generations an EESSI version carries, checked on a plan's easystacks.
//!
//! Each EESSI version is built on a fixed set of toolchain generations:
//! 2023.06 on 2022b, 2023a and 2023b, 2025.06 on 2024a, 2025a and 2025b.
//! `data/eessi-generations.toml` is that table. An easystack entry on a
//! 2023.06 on 2022b, 2023a and 2023b, 2025.06 on 2024a, 2025a and 2025b,
//! 2026.06 on 2026.1. `data/eessi-generations.toml` is that table. An easystack entry on a
//! toolchain outside its version's generations cannot go into that version:
//! software-layer #1472 put pv on GCCcore-12.3.0, which is 2023a, into a
//! 2025.06 easystack. The bot builds one EESSI version per pull request, so
Expand Down
18 changes: 11 additions & 7 deletions src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ fn is_usage(error: &anyhow::Error) -> bool {
name = "eb-stack",
version,
about = "Canonical SBOM, build-manifest, Resolvo, EasyBuild, and campaign workflows",
after_long_help = "Exit status is 0 when the command finished, 1 when the work failed, and 2 when the command line was rejected.\n\nA directory of artifacts is --out-dir. A single output file is --out.\n\nExamples:\n eb-stack package inspect --source recipe.yaml --format conda-forge --toolchain foss/2026.1 --out-dir bundle\n eb-stack --help"
after_long_help = "Exit status is 0 when the command finished, 1 when the work failed, and 2 when the command line was rejected. `stack admit` exits 78 when it refuses the job.\n\nA directory of artifacts is --out-dir. A single output file is --out.\n\nExamples:\n eb-stack package inspect --source recipe.yaml --format conda-forge --toolchain foss/2026.1 --out-dir bundle\n eb-stack --help"
)]
struct Cli {
#[command(subcommand)]
Expand Down Expand Up @@ -80,7 +80,9 @@ enum Command {
command: TargetCommand,
},
/// Run and inspect persisted build campaigns.
#[command(after_long_help = "Examples:\n eb-stack campaign status --state campaign.json")]
#[command(
after_long_help = "Examples:\n eb-stack campaign run --bundle bundle/ --config target.toml --target local --state campaign.json\n eb-stack campaign status --state campaign.json"
)]
Campaign {
#[command(subcommand)]
command: CampaignCommand,
Expand Down Expand Up @@ -1116,7 +1118,8 @@ struct BatchArgs {
/// Installed modules, one `Name/VersionFull` per line.
#[arg(long)]
installed: PathBuf,
/// Modulerc file with `module_version` aliases. Repeatable.
/// Lmod `.modulerc.lua` file with `module_version` aliases, or a module
/// tree to scan for them. Repeatable.
#[arg(long = "installed-modulerc")]
installed_modulerc: Vec<PathBuf>,
/// Open software-layer pull requests, `pr-overlap --pr` JSON. Repeatable.
Expand Down Expand Up @@ -1705,7 +1708,7 @@ enum StackCommand {
/// reservation is never counted. Prints one JSON line. Exits 0 when
/// admitted, 78 when refused.
#[command(
after_long_help = "Examples:\n eb-stack stack admit --quota-json quota.json --footprint 351000 --job 4411 --reservations reservations --live-jobs 4401,4402\n mmlsquota-json | eb-stack stack admit --quota-json - --footprint 61000 --job 4412 --reservations reservations --live-jobs \"$(squeue --all -h -o %i -u jenkins | paste -sd,)\""
after_long_help = "Examples:\n eb-stack stack admit --quota-json quota.json --footprint 351000 --job 4411 --reservations reservations --live-jobs 4401,4402\n eb-stack stack admit --lock reservations/admission.lock --quota-cmd mmlsquota-json --footprint 61000 --job 4412 --reservations reservations --live-jobs-cmd 'squeue --all -h -o %i -u jenkins'"
)]
Admit(Box<AdmitArgs>),
/// Refuse a plan an architecture cannot build, and flag shared entries
Expand Down Expand Up @@ -1816,9 +1819,10 @@ enum StackCommand {
///
/// `data/eessi-generations.toml` maps each EESSI version to its
/// generations: 2023.06 to 2022b, 2023a and 2023b, 2025.06 to 2024a,
/// 2025a and 2025b. The EESSI version comes from the easystack path. With
/// `--pr`, only the lines each pull request adds are checked, and the rest
/// of the file counts as already in the stack. Exits 1 on any finding.
/// 2025a and 2025b, and 2026.06 to 2026.1. The EESSI version comes from
/// the easystack path. With `--pr`, only the lines each pull request adds
/// are checked, and the rest of the file counts as already in the stack.
/// Exits 1 on any finding.
#[command(
after_long_help = "Examples:\n eb-stack stack generation --easystack easystacks/software.eessi.io/2025.06/eessi-2025.06-eb-5.4.1-2025b.yml\n eb-stack stack generation --pr pr-1472.json\n eb-stack stack generation --pr pr.json --deployed easystacks/software.eessi.io/2025.06 --allow-versions CMake@2025b"
)]
Expand Down
143 changes: 143 additions & 0 deletions tests/cli_ergonomics.rs
Original file line number Diff line number Diff line change
Expand Up @@ -328,6 +328,149 @@ fn stack_gap_help_example_paths_exist() {
);
}

#[test]
fn top_level_help_names_every_exit_status_the_reference_lists() {
let help = help_text(&[]);
let paragraph = help
.split("\n\n")
.find(|block| block.starts_with("Exit status"))
.expect("eb-stack --help states the exit status");
let named: Vec<&str> = paragraph.split(|c: char| !c.is_ascii_digit()).collect();
let reference = std::fs::read_to_string(
Path::new(env!("CARGO_MANIFEST_DIR")).join("docs/orgmode/reference/cli.org"),
)
.expect("read cli.org");
let codes: Vec<&str> = reference
.split_once("* Exit status")
.expect("cli.org has an exit status section")
.1
.lines()
.skip_while(|line| !line.starts_with('|'))
.take_while(|line| line.starts_with('|'))
.filter_map(|line| line.split('|').nth(1).map(str::trim))
.filter(|cell| !cell.is_empty() && cell.chars().all(|c| c.is_ascii_digit()))
.collect();
assert!(
codes.contains(&"78"),
"cli.org exit status table: {codes:?}"
);
for code in codes {
assert!(
named.contains(&code),
"eb-stack --help does not name exit status {code}:\n{paragraph}"
);
}
}

#[test]
fn stack_admit_help_examples_read_the_scheduler_inside_the_lock() {
let text = help_text(&["stack".into(), "admit".into()]);
let examples = text
.split_once("Examples:")
.expect("stack admit help has an example")
.1;
assert!(
!examples.contains("$("),
"a stack admit --help example expands a command before the lock:\n{examples}"
);
assert!(
examples.contains("--lock ") && examples.contains("--live-jobs-cmd "),
"stack admit --help should show the scheduler read inside --lock:\n{examples}"
);
}

#[test]
fn campaign_help_shows_how_to_start_a_campaign() {
let text = help_text(&["campaign".into()]);
let examples = text
.split_once("Examples:")
.expect("campaign help has an example")
.1;
assert!(
examples.contains("eb-stack campaign run "),
"campaign --help should show campaign run:\n{examples}"
);
}

#[test]
fn stack_generation_help_maps_every_bundled_eessi_version() {
let help = help_text(&["stack".into(), "generation".into()]);
let mapping = help
.split("\n\n")
.find(|block| block.contains("data/eessi-generations.toml"))
.expect("stack generation --help names the table");
let table = std::fs::read_to_string(
Path::new(env!("CARGO_MANIFEST_DIR")).join("data/eessi-generations.toml"),
)
.expect("read the bundled table");
let mut versions = 0;
let mut lines = table.lines();
while let Some(line) = lines.next() {
let Some(version) = line
.strip_prefix("eessi = \"")
.and_then(|rest| rest.strip_suffix('"'))
else {
continue;
};
let generations = lines
.next()
.and_then(|next| next.strip_prefix("generations = ["))
.expect("generations follow eessi");
assert!(
mapping.contains(&format!("{version} to ")),
"stack generation --help does not map EESSI {version}:\n{mapping}"
);
for generation in generations
.trim_end_matches(']')
.split(',')
.map(|generation| generation.trim().trim_matches('"'))
{
assert!(
mapping.contains(generation),
"stack generation --help does not name {generation} for {version}:\n{mapping}"
);
}
versions += 1;
}
assert!(versions >= 3, "read {versions} EESSI versions");
}

/// The lines clap prints under one long flag, joined.
fn flag_description(help: &str, flag: &str) -> Option<String> {
let mut lines = help
.lines()
.skip_while(|line| line.trim_start().split(' ').next() != Some(flag));
lines.next()?;
Some(
lines
.take_while(|line| !line.trim_start().starts_with('-'))
.map(str::trim)
.collect::<Vec<_>>()
.join(" "),
)
}

#[test]
fn every_installed_modulerc_help_says_a_module_tree_is_read() {
let mut checked = Vec::new();
for command in leaves() {
let help = help_text(&command);
let Some(description) = flag_description(&help, "--installed-modulerc") else {
continue;
};
assert!(
description.contains("module tree"),
"{} --installed-modulerc also reads a module tree:\n{description}",
command.join(" ")
);
checked.push(command.join(" "));
}
assert!(
checked.len() >= 3,
"commands with --installed-modulerc: {checked:?}"
);
}

#[test]
fn every_command_help_has_an_example_and_describes_every_flag() {
let commands = leaves();
Expand Down
Loading