From c5edfcc440f74525165b3e6b8f8fded0278d5bc8 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Tue, 17 Nov 2026 05:14:01 +0000 Subject: [PATCH 1/3] fix: refuse a modules.shell that cannot run the module wrapper The module wrapper is a script for a POSIX shell: it splits the unquoted EB_PIPELINE_MODULES at white space, under set -f. modules.shell took any string. zsh ran the script without splitting, so the modules of modules.init reached one module load as a single name, and csh, tcsh and fish failed to parse it when a step started. site::validate now accepts sh, bash, dash, ash, ksh, ksh93, mksh and yash, matched on the file name of the value so that a path works too, and reports anything else, so check and every other command that loads the site file refuse it. Each of those shells ran the wrapper here, and the wrapper test now runs a build through every one of them that is installed, bash and sh at least. The schema text, the site file and environment references, and the failures of the site file how-to say which shells are accepted, the last with the message from docs/examples/site-file.sh. --- changelog.d/+modules-shell.bugfix.md | 1 + docs/examples/site-file.sh | 5 +++ docs/orgmode/howto/write-a-site-file.org | 15 +++---- docs/orgmode/reference/environment.org | 3 +- docs/orgmode/reference/site-file.org | 16 ++++---- src/resolve.rs | 5 +++ src/schema.rs | 2 +- src/site.rs | 13 +++++- tests/run_stubs.rs | 13 +++++- tests/schema_and_plan.rs | 51 ++++++++++++++++++++++++ 10 files changed, 105 insertions(+), 19 deletions(-) create mode 100644 changelog.d/+modules-shell.bugfix.md diff --git a/changelog.d/+modules-shell.bugfix.md b/changelog.d/+modules-shell.bugfix.md new file mode 100644 index 0000000..9ccda6b --- /dev/null +++ b/changelog.d/+modules-shell.bugfix.md @@ -0,0 +1 @@ +`check`, and every command that loads the site file, refuses a `modules.shell` that cannot run the module wrapper. It accepts `sh`, `bash`, `dash`, `ash`, `ksh`, `ksh93`, `mksh` and `yash`, by name or by path. zsh ran the wrapper without splitting `EB_PIPELINE_MODULES`, so the modules of `modules.init` loaded as one name, and csh, tcsh and fish could not parse it. A site file that names zsh and loads one module, which worked, must name one of those shells. diff --git a/docs/examples/site-file.sh b/docs/examples/site-file.sh index b1e5ca7..b865860 100755 --- a/docs/examples/site-file.sh +++ b/docs/examples/site-file.sh @@ -55,6 +55,11 @@ run 'eb-pipeline check --site pbs.toml' expect_status 2 expect_line 'ERROR [check] example: scheduler.kind: expected slurm or local, found `pbs`' +sed '/^init = /a shell = "zsh"' site.toml >zsh.toml +run 'eb-pipeline check --site zsh.toml' +expect_status 2 +expect_line 'ERROR [check] example: modules.shell: expected a POSIX shell that runs the module wrapper, one of sh, bash, dash, ash, ksh, ksh93, mksh or yash, by name or by path, found `zsh`' + sed 's/^compress_after_days = 30/compress_after_days = 400/' site.toml >rotate.toml run 'eb-pipeline check --site rotate.toml' expect_status 2 diff --git a/docs/orgmode/howto/write-a-site-file.org b/docs/orgmode/howto/write-a-site-file.org index ce897fb..1c36f31 100644 --- a/docs/orgmode/howto/write-a-site-file.org +++ b/docs/orgmode/howto/write-a-site-file.org @@ -148,13 +148,14 @@ Each line is a command that =run= would start, after the phase it belongs to: =s Each of these makes =check= exit 2; the problems of a site file that parses end with =ERROR [main] -: N problem(s) in the site file=. -| Message | Cause | What to do | -|--------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+--------------------------------------------------------------------| -| =ERROR [main] -: invalid site file: TOML parse error at line 35, column 1=, then =unknown field `log_rot`, expected one of `scratch`, ...= | The section has no such key, here a misspelt =log_root=. | Correct the key; the message lists the keys of the section. | -| =ERROR [check] example: scheduler.kind: expected slurm or local, found `pbs`= | eb-pipeline launches commands with Slurm's =srun=, or runs them directly. | Set =slurm= or =local=. | -| =ERROR [check] example: logs.rotate.delete_after_days: must be greater than compress_after_days (400), found 365= | A log directory would be deleted before it is compressed. | Make =delete_after_days= the greater. | -| =ERROR [check] example: targets.zen4.build_lists: `zen4.list` not found in .= | A build list of the target is not in the =--lists-dir= directory. | Add the list, or correct its name in =build_lists=. | -| =ERROR [main] -: eb_keep_logs: cannot run `eb-keep-logs --version`: No such file or directory (os error 2)= | =--probe-tools= found no =eb-keep-logs= on =PATH=. | Install it, or name its path in =[site.tools.eb_keep_logs]= =bin=. | +| Message | Cause | What to do | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------| +| =ERROR [main] -: invalid site file: TOML parse error at line 35, column 1=, then =unknown field `log_rot`, expected one of `scratch`, ...= | The section has no such key, here a misspelt =log_root=. | Correct the key; the message lists the keys of the section. | +| =ERROR [check] example: scheduler.kind: expected slurm or local, found `pbs`= | eb-pipeline launches commands with Slurm's =srun=, or runs them directly. | Set =slurm= or =local=. | +| =ERROR [check] example: modules.shell: expected a POSIX shell that runs the module wrapper, one of sh, bash, dash, ash, ksh, ksh93, mksh or yash, by name or by path, found `zsh`= | The module wrapper is a script for a POSIX shell, and zsh would load the modules of =init= as one name. | Name one of those shells, or drop =shell= for the default, =bash=. | +| =ERROR [check] example: logs.rotate.delete_after_days: must be greater than compress_after_days (400), found 365= | A log directory would be deleted before it is compressed. | Make =delete_after_days= the greater. | +| =ERROR [check] example: targets.zen4.build_lists: `zen4.list` not found in .= | A build list of the target is not in the =--lists-dir= directory. | Add the list, or correct its name in =build_lists=. | +| =ERROR [main] -: eb_keep_logs: cannot run `eb-keep-logs --version`: No such file or directory (os error 2)= | =--probe-tools= found no =eb-keep-logs= on =PATH=. | Install it, or name its path in =[site.tools.eb_keep_logs]= =bin=. | The commands and their output on this page come from =docs/examples/site-file.sh=. diff --git a/docs/orgmode/reference/environment.org b/docs/orgmode/reference/environment.org index b9126b8..f821703 100644 --- a/docs/orgmode/reference/environment.org +++ b/docs/orgmode/reference/environment.org @@ -127,7 +127,8 @@ When =modules.init= is not empty, =modules.unuse_path= is =true= or =modules.she 3. =EB_PIPELINE_MODULES=: it runs =module purge=, then =module load= for each name in it, in order, then the command. It splits the variable at white space and gives each name to =module load= as written: a name with a pattern in it, such as =GCC/*=, is not matched against file names. -The wrapper is a script for a POSIX shell, such as =bash= or =sh=. +The wrapper is a script for a POSIX shell: =check= accepts =sh=, =bash=, =dash=, =ash=, =ksh=, =ksh93=, =mksh= and =yash= as =modules.shell=, by name or by path, and refuses any other. +zsh would load the names of =EB_PIPELINE_MODULES= as one, since it does not split an unquoted variable, and csh, tcsh and fish cannot parse the script. The admit and rotate commands start without it. ** See also diff --git a/docs/orgmode/reference/site-file.org b/docs/orgmode/reference/site-file.org index 162e06a..b9fbd5d 100644 --- a/docs/orgmode/reference/site-file.org +++ b/docs/orgmode/reference/site-file.org @@ -308,14 +308,14 @@ With =--disable-robot= in =extra_args=, a line fetches its own sources only: the ** =[modules]= -| Key | Type | Default | Meaning | -|---------------+-----------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| =init= | array of string | required | The modules to load, in order, after =module purge=, before the shard, prefetch, build, =eb-keep-logs failed= and cache commands; may be empty. | -| =unuse_path= | boolean | =false= | =true= empties =MODULEPATH= after =shell_init= and before =init= loads, so that the first module of =init= needs an absolute path; =check= warns when it has none. | -| =shell= | string | =bash= | The shell that runs the module wrapper, which is a script for a POSIX shell, such as =bash= or =sh=. | -| =shell_init= | string | none | A file to source before =module= is called, for a shell that does not define it. It is sourced without =set -e= and =set -u=; a =module= call that fails still stops the command. | -| =eessi= | table | none | The site layer of EESSI. | -| =package_env= | table of tables | ={}= | Variables per package name, =[modules.package_env.NAME]=, for the prefetch and build commands of the lines of that package. | +| Key | Type | Default | Meaning | +|---------------+-----------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =init= | array of string | required | The modules to load, in order, after =module purge=, before the shard, prefetch, build, =eb-keep-logs failed= and cache commands; may be empty. | +| =unuse_path= | boolean | =false= | =true= empties =MODULEPATH= after =shell_init= and before =init= loads, so that the first module of =init= needs an absolute path; =check= warns when it has none. | +| =shell= | string | =bash= | The shell that runs the module wrapper, a script for a POSIX shell, by name or by path: =sh=, =bash=, =dash=, =ash=, =ksh=, =ksh93=, =mksh= or =yash=. =check= refuses any other, such as =zsh=, which does not split the names of =init=. | +| =shell_init= | string | none | A file to source before =module= is called, for a shell that does not define it. It is sourced without =set -e= and =set -u=; a =module= call that fails still stops the command. | +| =eessi= | table | none | The site layer of EESSI. | +| =package_env= | table of tables | ={}= | Variables per package name, =[modules.package_env.NAME]=, for the prefetch and build commands of the lines of that package. | The module wrapper starts when =init= is not empty, =unuse_path= is =true= or =shell_init= is set; [[file:environment.org][Environment variables]] describes it. diff --git a/src/resolve.rs b/src/resolve.rs index 1647625..7f2e5a4 100644 --- a/src/resolve.rs +++ b/src/resolve.rs @@ -510,6 +510,11 @@ for m in ${EB_PIPELINE_MODULES:-}; do set +f; module load \"$m\"; done set +f exec \"$@\""; +/// Shells that `modules.shell` may name, by name or by path. The wrapper +/// needs a POSIX shell, which splits an unquoted expansion at white space and +/// takes `set -f`: zsh does neither, and csh, tcsh and fish cannot parse it. +pub const MODULE_SHELLS: &[&str] = &["sh", "bash", "dash", "ash", "ksh", "ksh93", "mksh", "yash"]; + /// Group that applies to a package, if any. A version that does not parse /// gets the group (fail closed). pub fn licence_group(l: &Licences, name: &str, version: Option<&str>) -> Option { diff --git a/src/schema.rs b/src/schema.rs index 4f1b5b2..6feb0ca 100644 --- a/src/schema.rs +++ b/src/schema.rs @@ -431,7 +431,7 @@ doc_struct! { unuse_path: bool => ("boolean", "false", false, "Clears MODULEPATH after `shell_init` and before loading `init`, so the first `init` module needs an absolute path."), #[serde(default = "d_shell")] shell: String => ("string", "bash", false, - "POSIX shell that runs the module wrapper, such as `bash` or `sh`."), + "POSIX shell that runs the module wrapper, by name or by path: `sh`, `bash`, `dash`, `ash`, `ksh`, `ksh93`, `mksh` or `yash`."), shell_init: Option => ("string", "none", false, "File sourced before `module` is called, for shells that do not define it. It is sourced without `set -e` or `set -u`; a `module` call that fails still stops the step."), eessi: Option => ("table", "none", false, "EESSI site layer."), diff --git a/src/site.rs b/src/site.rs index 14fa41b..6c9443a 100644 --- a/src/site.rs +++ b/src/site.rs @@ -1,7 +1,7 @@ //! Loading and validating site files. use crate::exit::Fail; -use crate::resolve::Scope; +use crate::resolve::{Scope, MODULE_SHELLS}; use crate::schema::*; use crate::util::parse_version; use std::collections::{BTreeMap, BTreeSet}; @@ -471,6 +471,17 @@ pub fn validate(site: &Site, lists_dir: Option<&Path>) -> Vec { e.push("shards.easyconfigs: at least one tree is required when count >= 2".into()); } } + let shell = &site.modules.shell; + let shell_name = Path::new(shell).file_name().and_then(|n| n.to_str()); + if !shell_name.is_some_and(|n| MODULE_SHELLS.contains(&n)) { + let (last, rest) = MODULE_SHELLS + .split_last() + .expect("MODULE_SHELLS is not empty"); + e.push(format!( + "modules.shell: expected a POSIX shell that runs the module wrapper, one of {} or {last}, by name or by path, found `{shell}`", + rest.join(", ") + )); + } // eb-staged-rebuild copies the one `target` of a ledger configuration into // every record it writes. if let Some(r) = site.rebuild_on() { diff --git a/tests/run_stubs.rs b/tests/run_stubs.rs index 55be2e6..31a50f6 100644 --- a/tests/run_stubs.rs +++ b/tests/run_stubs.rs @@ -2117,7 +2117,18 @@ fn a_command_that_runs_eb_pipeline_reads_the_site_file_of_the_run() { /// files it would name. #[test] fn the_module_wrapper_loads_each_name_as_written() { - for shell in ["bash", "sh"] { + // Each shell `modules.shell` may name, of those installed. + let path = std::env::var_os("PATH").unwrap_or_default(); + let shells: Vec<&str> = eb_pipeline::resolve::MODULE_SHELLS + .iter() + .copied() + .filter(|s| std::env::split_paths(&path).any(|d| d.join(s).is_file())) + .collect(); + assert!( + shells.contains(&"bash") && shells.contains(&"sh"), + "{shells:?}" + ); + for shell in shells { let env = setup(""); let root = env.dir.path(); let r = root.display().to_string(); diff --git a/tests/schema_and_plan.rs b/tests/schema_and_plan.rs index f99c675..c38bca4 100644 --- a/tests/schema_and_plan.rs +++ b/tests/schema_and_plan.rs @@ -1482,6 +1482,57 @@ fn a_target_name_is_a_directory_name() { assert!(site::validate(&site::parse(&text).unwrap(), None).is_empty()); } +#[test] +fn the_module_shell_splits_the_names_of_init() { + let with_shell = + |shell: &str| MINIMAL.replace("init = []", &format!("init = []\nshell = {shell:?}")); + let errs = |shell: &str| site::validate(&site::parse(&with_shell(shell)).unwrap(), None); + for ok in [ + "bash", + "sh", + "/bin/sh", + "/usr/local/bin/bash", + "dash", + "ksh", + "mksh", + ] { + assert!(errs(ok).is_empty(), "{ok}: {:?}", errs(ok)); + } + let refusal = |shell: &str| { + format!("modules.shell: expected a POSIX shell that runs the module wrapper, one of sh, bash, dash, ash, ksh, ksh93, mksh or yash, by name or by path, found `{shell}`") + }; + for bad in ["zsh", "/usr/bin/zsh", "fish", "csh", "tcsh", "bash -l", ""] { + assert_eq!(errs(bad), [refusal(bad)]); + } + let d = tempfile::tempdir().unwrap(); + let path = d.path().join("site.toml"); + std::fs::write(&path, with_shell("zsh")).unwrap(); + let list = d.path().join("l.txt"); + std::fs::write(&list, "Foo-1.0-foss-2025a.eb\n").unwrap(); + for args in [ + vec!["check", "--site"], + vec![ + "plan", + "--target", + "cpu", + "--build-type", + "production", + "--list", + list.to_str().unwrap(), + "--site", + ], + ] { + let o = bin().args(&args).arg(&path).output().unwrap(); + let err = String::from_utf8(o.stderr).unwrap(); + assert_eq!(o.status.code(), Some(2), "{args:?}: {err}"); + assert!( + err.lines() + .any(|l| l == format!("ERROR [check] t: {}", refusal("zsh"))), + "{args:?}: {err}" + ); + } +} + #[test] fn eessi_site_install_staged_targets_need_both_roots() { let errs = |text: &str| -> Vec { From 5846c014ff46c4274a3af5a0a0b385a0cf25002a Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Tue, 17 Nov 2026 05:16:30 +0000 Subject: [PATCH 2/3] fix: refuse a modules.init entry with white space The entries of modules.init reach the module wrapper joined with spaces in EB_PIPELINE_MODULES, and the wrapper splits that at white space. An entry with white space in it loaded as several modules: a pasted line, "module load EasyBuild", loaded module, load and EasyBuild. An entry is now one module name, and site::validate reports an entry with white space, so check and every other command that loads the site file refuse it. That follows how init lines are written, with white space between module names and none inside one. Lmod and Environment Modules would load a quoted name with a space, but EB_PIPELINE_MODULES, joined with spaces, cannot carry one, and loading the entry whole would turn a pasted line into a module load that fails at run time. The templates and the site files of the docs give one name per entry and still pass. The schema text, the site file and environment references, and the failures of the site file how-to describe the rule, the last with the message from docs/examples/site-file.sh. --- changelog.d/+modules-init-one-name.removal.md | 1 + docs/examples/site-file.sh | 5 +++ docs/orgmode/howto/write-a-site-file.org | 1 + docs/orgmode/reference/environment.org | 2 +- docs/orgmode/reference/site-file.org | 16 +++---- src/schema.rs | 2 +- src/site.rs | 10 +++++ tests/schema_and_plan.rs | 42 +++++++++++++++++++ 8 files changed, 69 insertions(+), 10 deletions(-) create mode 100644 changelog.d/+modules-init-one-name.removal.md diff --git a/changelog.d/+modules-init-one-name.removal.md b/changelog.d/+modules-init-one-name.removal.md new file mode 100644 index 0000000..5c5a27c --- /dev/null +++ b/changelog.d/+modules-init-one-name.removal.md @@ -0,0 +1 @@ +`check`, and every command that loads the site file, refuses a `modules.init` entry with white space, since an entry is one module name. The module wrapper split such an entry at the white space, so `init = ["A B"]` loaded `A` and `B`, and a pasted `module load A` line loaded `module`, `load` and `A`. Write `init = ["A", "B"]`. diff --git a/docs/examples/site-file.sh b/docs/examples/site-file.sh index b865860..5a18ecb 100755 --- a/docs/examples/site-file.sh +++ b/docs/examples/site-file.sh @@ -55,6 +55,11 @@ run 'eb-pipeline check --site pbs.toml' expect_status 2 expect_line 'ERROR [check] example: scheduler.kind: expected slurm or local, found `pbs`' +sed 's/^init = \["EasyBuild"\]/init = ["module load EasyBuild"]/' site.toml >init.toml +run 'eb-pipeline check --site init.toml' +expect_status 2 +expect_line 'ERROR [check] example: modules.init: `module load EasyBuild` has white space; an entry is one module name, so give each module its own entry' + sed '/^init = /a shell = "zsh"' site.toml >zsh.toml run 'eb-pipeline check --site zsh.toml' expect_status 2 diff --git a/docs/orgmode/howto/write-a-site-file.org b/docs/orgmode/howto/write-a-site-file.org index 1c36f31..31df74a 100644 --- a/docs/orgmode/howto/write-a-site-file.org +++ b/docs/orgmode/howto/write-a-site-file.org @@ -152,6 +152,7 @@ Each of these makes =check= exit 2; the problems of a site file that parses end |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------| | =ERROR [main] -: invalid site file: TOML parse error at line 35, column 1=, then =unknown field `log_rot`, expected one of `scratch`, ...= | The section has no such key, here a misspelt =log_root=. | Correct the key; the message lists the keys of the section. | | =ERROR [check] example: scheduler.kind: expected slurm or local, found `pbs`= | eb-pipeline launches commands with Slurm's =srun=, or runs them directly. | Set =slurm= or =local=. | +| =ERROR [check] example: modules.init: `module load EasyBuild` has white space; an entry is one module name, so give each module its own entry= | An entry is one module name, and this one holds a whole =module load= line. | Give each module its own entry, here =init = ["EasyBuild"]=. | | =ERROR [check] example: modules.shell: expected a POSIX shell that runs the module wrapper, one of sh, bash, dash, ash, ksh, ksh93, mksh or yash, by name or by path, found `zsh`= | The module wrapper is a script for a POSIX shell, and zsh would load the modules of =init= as one name. | Name one of those shells, or drop =shell= for the default, =bash=. | | =ERROR [check] example: logs.rotate.delete_after_days: must be greater than compress_after_days (400), found 365= | A log directory would be deleted before it is compressed. | Make =delete_after_days= the greater. | | =ERROR [check] example: targets.zen4.build_lists: `zen4.list` not found in .= | A build list of the target is not in the =--lists-dir= directory. | Add the list, or correct its name in =build_lists=. | diff --git a/docs/orgmode/reference/environment.org b/docs/orgmode/reference/environment.org index f821703..159a161 100644 --- a/docs/orgmode/reference/environment.org +++ b/docs/orgmode/reference/environment.org @@ -125,7 +125,7 @@ When =modules.init= is not empty, =modules.unuse_path= is =true= or =modules.she 1. =EB_PIPELINE_SHELL_INIT=: the file it sources first, when set. 2. =EB_PIPELINE_UNUSE_PATH=: when set, it empties =MODULEPATH=. 3. =EB_PIPELINE_MODULES=: it runs =module purge=, then =module load= for each name in it, in order, then the command. - It splits the variable at white space and gives each name to =module load= as written: a name with a pattern in it, such as =GCC/*=, is not matched against file names. + It splits the variable at white space, which =check= refuses in an entry of =modules.init=, and gives each name to =module load= as written: a name with a pattern in it, such as =GCC/*=, is not matched against file names. The wrapper is a script for a POSIX shell: =check= accepts =sh=, =bash=, =dash=, =ash=, =ksh=, =ksh93=, =mksh= and =yash= as =modules.shell=, by name or by path, and refuses any other. zsh would load the names of =EB_PIPELINE_MODULES= as one, since it does not split an unquoted variable, and csh, tcsh and fish cannot parse the script. diff --git a/docs/orgmode/reference/site-file.org b/docs/orgmode/reference/site-file.org index b9fbd5d..faa844a 100644 --- a/docs/orgmode/reference/site-file.org +++ b/docs/orgmode/reference/site-file.org @@ -308,14 +308,14 @@ With =--disable-robot= in =extra_args=, a line fetches its own sources only: the ** =[modules]= -| Key | Type | Default | Meaning | -|---------------+-----------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| =init= | array of string | required | The modules to load, in order, after =module purge=, before the shard, prefetch, build, =eb-keep-logs failed= and cache commands; may be empty. | -| =unuse_path= | boolean | =false= | =true= empties =MODULEPATH= after =shell_init= and before =init= loads, so that the first module of =init= needs an absolute path; =check= warns when it has none. | -| =shell= | string | =bash= | The shell that runs the module wrapper, a script for a POSIX shell, by name or by path: =sh=, =bash=, =dash=, =ash=, =ksh=, =ksh93=, =mksh= or =yash=. =check= refuses any other, such as =zsh=, which does not split the names of =init=. | -| =shell_init= | string | none | A file to source before =module= is called, for a shell that does not define it. It is sourced without =set -e= and =set -u=; a =module= call that fails still stops the command. | -| =eessi= | table | none | The site layer of EESSI. | -| =package_env= | table of tables | ={}= | Variables per package name, =[modules.package_env.NAME]=, for the prefetch and build commands of the lines of that package. | +| Key | Type | Default | Meaning | +|---------------+-----------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =init= | array of string | required | The modules to load, in order, after =module purge=, before the shard, prefetch, build, =eb-keep-logs failed= and cache commands; may be empty. An entry is one module name, so =module load A B= is =["A", "B"]=; =check= refuses an entry with white space. | +| =unuse_path= | boolean | =false= | =true= empties =MODULEPATH= after =shell_init= and before =init= loads, so that the first module of =init= needs an absolute path; =check= warns when it has none. | +| =shell= | string | =bash= | The shell that runs the module wrapper, a script for a POSIX shell, by name or by path: =sh=, =bash=, =dash=, =ash=, =ksh=, =ksh93=, =mksh= or =yash=. =check= refuses any other, such as =zsh=, which does not split the names of =init=. | +| =shell_init= | string | none | A file to source before =module= is called, for a shell that does not define it. It is sourced without =set -e= and =set -u=; a =module= call that fails still stops the command. | +| =eessi= | table | none | The site layer of EESSI. | +| =package_env= | table of tables | ={}= | Variables per package name, =[modules.package_env.NAME]=, for the prefetch and build commands of the lines of that package. | The module wrapper starts when =init= is not empty, =unuse_path= is =true= or =shell_init= is set; [[file:environment.org][Environment variables]] describes it. diff --git a/src/schema.rs b/src/schema.rs index 6feb0ca..14ef047 100644 --- a/src/schema.rs +++ b/src/schema.rs @@ -426,7 +426,7 @@ doc_struct! { /// Environment modules. Modules { init: Vec => ("array of string", "", true, - "Modules loaded, in order, after `module purge` in every EasyBuild phase and around `stack shard`. May be empty."), + "Modules loaded, in order, after `module purge` in every EasyBuild phase and around `stack shard`, one name per entry, without white space. May be empty."), #[serde(default)] unuse_path: bool => ("boolean", "false", false, "Clears MODULEPATH after `shell_init` and before loading `init`, so the first `init` module needs an absolute path."), #[serde(default = "d_shell")] diff --git a/src/site.rs b/src/site.rs index 6c9443a..68ef099 100644 --- a/src/site.rs +++ b/src/site.rs @@ -471,6 +471,16 @@ pub fn validate(site: &Site, lists_dir: Option<&Path>) -> Vec { e.push("shards.easyconfigs: at least one tree is required when count >= 2".into()); } } + for m in site + .modules + .init + .iter() + .filter(|m| m.contains(char::is_whitespace)) + { + e.push(format!( + "modules.init: `{m}` has white space; an entry is one module name, so give each module its own entry" + )); + } let shell = &site.modules.shell; let shell_name = Path::new(shell).file_name().and_then(|n| n.to_str()); if !shell_name.is_some_and(|n| MODULE_SHELLS.contains(&n)) { diff --git a/tests/schema_and_plan.rs b/tests/schema_and_plan.rs index c38bca4..770e7d0 100644 --- a/tests/schema_and_plan.rs +++ b/tests/schema_and_plan.rs @@ -1482,6 +1482,48 @@ fn a_target_name_is_a_directory_name() { assert!(site::validate(&site::parse(&text).unwrap(), None).is_empty()); } +#[test] +fn an_init_entry_is_one_module_name() { + let with_init = |init: &str| MINIMAL.replace("init = []", &format!("init = {init}")); + let errs = |init: &str| site::validate(&site::parse(&with_init(init)).unwrap(), None); + for ok in [ + r#"["EasyBuild"]"#, + r#"["Core/Stack/2026", "EasyBuild/5.1.2", "/opt/site/modules/Extend/1.0"]"#, + r#"["/", "EasyBuild", ""]"#, + ] { + assert!(errs(ok).is_empty(), "{ok}: {:?}", errs(ok)); + } + let refusal = |entry: &str| { + format!("modules.init: `{entry}` has white space; an entry is one module name, so give each module its own entry") + }; + assert_eq!( + errs(r#"["Core/Stack/2026 EasyBuild", "Other/2.0", "module load Extend"]"#), + [ + refusal("Core/Stack/2026 EasyBuild"), + refusal("module load Extend") + ] + ); + for (toml, entry) in [ + (r#""EasyBuild ""#, "EasyBuild "), + (r#""\tEasyBuild""#, "\tEasyBuild"), + (r#""Easy\u00A0Build""#, "Easy\u{a0}Build"), + (r#"" ""#, " "), + ] { + assert_eq!(errs(&format!("[{toml}]")), [refusal(entry)], "{toml}"); + } + let d = tempfile::tempdir().unwrap(); + let path = d.path().join("site.toml"); + std::fs::write(&path, with_init(r#"["Core/Stack/2026 EasyBuild"]"#)).unwrap(); + let o = bin().args(["check", "--site"]).arg(&path).output().unwrap(); + let err = String::from_utf8(o.stderr).unwrap(); + assert_eq!(o.status.code(), Some(2), "{err}"); + assert!( + err.lines() + .any(|l| l == format!("ERROR [check] t: {}", refusal("Core/Stack/2026 EasyBuild"))), + "{err}" + ); +} + #[test] fn the_module_shell_splits_the_names_of_init() { let with_shell = From 5e7fae831fc2ba34e05f6de2ab74de355d47cf8e Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Tue, 17 Nov 2026 05:21:27 +0000 Subject: [PATCH 3/3] fix: write code and verbatim text that starts with * as written ox-rst formats ~code~, =verbatim= and inline source blocks with its verb markup, which writes each leading * as \* inside a reStructuredText literal. A literal takes no backslash escapes, so the log rotation page showed *.log and *.txt as \*.log and \*.txt. docs/export.el now puts the plain ``%s`` format for code and verbatim ahead of ox-rst's own entries in org-rst-text-markup-alist. Exported before and after, the whole site differs only in the line of the log rotation page that holds those two literals. docs/tools/test_export.py exports a page of literals with export.el in a scratch directory and reads the result with docutils: each literal must match its Org text. The pixi task exporttest runs it, docbld depends on it, and the contributing page lists it. export.el is the documentation template's file; the template and the eessi-arch-guard docs carry the same file and need the same change. --- changelog.d/+literal-leading-star.doc.md | 1 + docs/export.el | 6 ++ docs/orgmode/contributing.org | 20 +++--- docs/tools/test_export.py | 81 ++++++++++++++++++++++++ pixi.toml | 5 +- 5 files changed, 103 insertions(+), 10 deletions(-) create mode 100644 changelog.d/+literal-leading-star.doc.md create mode 100644 docs/tools/test_export.py diff --git a/changelog.d/+literal-leading-star.doc.md b/changelog.d/+literal-leading-star.doc.md new file mode 100644 index 0000000..33a6033 --- /dev/null +++ b/changelog.d/+literal-leading-star.doc.md @@ -0,0 +1 @@ +Code and verbatim text that starts with `*` shows as written: the log rotation page showed `*.log` and `*.txt` as `\*.log` and `\*.txt`. `docs/export.el` writes such text as a plain reStructuredText literal, and `pixi run -e docs docbld` runs `docs/tools/test_export.py`, which exports a page of literals and checks each one. diff --git a/docs/export.el b/docs/export.el index 3253546..a91e42a 100644 --- a/docs/export.el +++ b/docs/export.el @@ -104,6 +104,12 @@ ;; x86_64 and EESSI_USER_INSTALL are names, not subscripts; only _{...} and ;; ^{...} are. (setq org-export-with-sub-superscripts '{}) +;; ox-rst writes a leading * of ~code~ and =verbatim= as \*, but a +;; reStructuredText literal takes no backslash escapes: =*.log= showed as +;; \*.log. +(setq org-rst-text-markup-alist + (append '((code . "``%s``") (verbatim . "``%s``")) + org-rst-text-markup-alist)) (defun stackhands-resolve-deferred (tree _backend _info) "Replace deferred properties in TREE with their values." diff --git a/docs/orgmode/contributing.org b/docs/orgmode/contributing.org index abffb83..93043a2 100644 --- a/docs/orgmode/contributing.org +++ b/docs/orgmode/contributing.org @@ -60,6 +60,7 @@ pixi run -e docs docbld The site is in =docs/build/html/=; open =docs/build/html/index.html=. The build fails on any Sphinx warning, any cross-reference that does not resolve, any rustdoc warning, any public item of the library without a doc comment, any internal link or anchor that does not exist, and, outside the changelog, any name of a real site's machines or paths. +It also fails when =docs/export.el= writes the code or verbatim text of a test page as a different literal, such as =\*.log= for =*.log=. The first build needs the network, to fetch the other stackhands sites' inventories; later builds reuse them for 30 days. External links are checked separately, as they need the network: @@ -72,15 +73,16 @@ pixi run -e docs linkcheck ** Where things are -| Path | What it holds | -|------------------------------+--------------------------------------------------------------------| -| =docs/orgmode/= | the pages, in Org: edit these | -| =docs/export.el= | the Org to reStructuredText export | -| =docs/source/conf.py= | the Sphinx configuration | -| =docs/source/_ext/= | the documentation template's Sphinx domain for Zig, unused here | -| =docs/tools/check_site.py= | checks internal links, anchors and forbidden names | -| =docs/tools/api-index.html= | the front page of the rustdoc site, which =cargo doc= does not write | -| =docs/examples/= | the scripts that print the output the pages show | +| Path | What it holds | +|-----------------------------+----------------------------------------------------------------------| +| =docs/orgmode/= | the pages, in Org: edit these | +| =docs/export.el= | the Org to reStructuredText export | +| =docs/source/conf.py= | the Sphinx configuration | +| =docs/source/_ext/= | the documentation template's Sphinx domain for Zig, unused here | +| =docs/tools/check_site.py= | checks internal links, anchors and forbidden names | +| =docs/tools/test_export.py= | checks the literals that =docs/export.el= writes | +| =docs/tools/api-index.html= | the front page of the rustdoc site, which =cargo doc= does not write | +| =docs/examples/= | the scripts that print the output the pages show | The =.rst= files under =docs/source/= and everything under =docs/build/= are generated and not committed. =pixi run -e docs rustdoc= runs =cargo doc= into =docs/build/cargo/= and copies the result to =docs/build/html/api/=. diff --git a/docs/tools/test_export.py b/docs/tools/test_export.py new file mode 100644 index 0000000..5e0891d --- /dev/null +++ b/docs/tools/test_export.py @@ -0,0 +1,81 @@ +#!/usr/bin/env python3 +"""Check docs/export.el on a page of its own: code and verbatim text. + + python docs/tools/test_export.py + +Exports one Org page with docs/export.el, as the pixi task mkrst does but in +a scratch directory, and reads the reStructuredText it writes with docutils. +Each ~code~, =verbatim= and inline source block of the page must come out as +a literal of the same text: a reStructuredText literal takes no backslash +escapes, so one that ox-rst writes as \\*.log shows as \\*.log. + +Exit status: 0 when every literal matches, 1 when one does not or the export +fails. +""" + +import pathlib +import subprocess +import sys +import tempfile + +import docutils.core +import docutils.nodes + +EXPORT = pathlib.Path(__file__).resolve().parent.parent / "export.el" + +# Each item of the page, in Org, and the literal it must come out as. +CASES = [ + ("=*.log=", "*.log"), + ("~*.txt~", "*.txt"), + ("=**/*.org=", "**/*.org"), + ("=*=", "*"), + ("src_sh{*.log}", "*.log"), + ("=GCC/*=", "GCC/*"), + ("~a\\b~", "a\\b"), +] + + +def export(page): + """The reStructuredText that export.el writes for PAGE, an Org text.""" + with tempfile.TemporaryDirectory() as tmp: + root = pathlib.Path(tmp) + (root / "orgmode").mkdir() + (root / "source").mkdir() + (root / "orgmode" / "index.org").write_text(page) + run = subprocess.run( + ["emacs", "-Q", "--batch", "--load", str(EXPORT)], + cwd=root, + capture_output=True, + text=True, + ) + rst = root / "source" / "index.rst" + if run.returncode != 0 or not rst.is_file(): + sys.stdout.write(run.stdout + run.stderr) + raise SystemExit(f"test_export: the export failed with exit status {run.returncode}") + return rst.read_text() + + +def literals(rst): + """The text of each literal in RST, in order.""" + doc = docutils.core.publish_doctree(rst, settings_overrides={"report_level": 5}) + return [node.astext() for node in doc.findall(docutils.nodes.literal)] + + +def main(): + page = "#+TITLE: Literals\n\n" + "".join(f"- {org}\n" for org, _ in CASES) + rst = export(page) + got = literals(rst) + if len(got) != len(CASES): + print(f"test_export: {len(got)} literals, expected {len(CASES)}, in:\n{rst}") + return 1 + problems = 0 + for (org, want), literal in zip(CASES, got): + if literal != want: + print(f"test_export: {org} comes out as {literal}, expected {want}") + problems += 1 + print(f"test_export: {len(CASES)} literals, {problems} problem(s)") + return 1 if problems else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/pixi.toml b/pixi.toml index 9d39470..8268a9b 100644 --- a/pixi.toml +++ b/pixi.toml @@ -24,6 +24,9 @@ sphinx-autoapi = "*" [feature.docs.tasks] # Org pages to reStructuredText, docs/orgmode -> docs/source. mkrst = { cmd = "emacs -Q --batch --load export.el", cwd = "docs" } +# export.el on a page of its own: each code and verbatim text comes out as a +# literal of the same text. +exporttest = { cmd = "python docs/tools/test_export.py" } sphinxbld = { cmd = "sphinx-build -W -n --keep-going -d docs/build/doctrees -b html docs/source docs/build/html", depends-on = ["mkrst"] } # The rustdoc site of the eb_pipeline library, served beside the Sphinx pages # at api/. Any rustdoc warning, such as a broken intra-doc link, fails it, and @@ -32,7 +35,7 @@ rustdoc = { cmd = "cargo doc --locked --no-deps --lib --target-dir docs/build/ca # Every internal link and anchor resolves, and no page names a site. The # changelog may name what a release removed; its links are still checked. doccheck = { cmd = "python docs/tools/check_site.py docs/build/html --sources docs/orgmode --exempt changelog.html", depends-on = ["rustdoc"] } -docbld = { depends-on = ["doccheck"] } +docbld = { depends-on = ["exporttest", "doccheck"] } # External links; needs the network, so CI runs it as its own step. linkcheck = { cmd = "lychee --config lychee.toml --no-progress 'docs/build/html/**/*.html'" } # Generated files are the ignored ones under docs/source (see .gitignore).