eb_pipeline/
resolve.rs

1//! Resolution of defaults and overrides into launch lines and environments.
2
3use crate::exit::Fail;
4use crate::schema::*;
5use crate::util::{package_of, split_args};
6use serde_json::{json, Value};
7use std::collections::BTreeMap;
8
9/// A phase role: which launch arguments a command takes from
10/// `[phase_defaults]` or the target's `phases`.
11#[derive(Clone, Copy, Debug, PartialEq, Eq)]
12pub enum Role {
13    /// The planning command, `stack shard`.
14    Plan,
15    /// The builds of the whole list, the prelude and each shard.
16    Build,
17    /// Admission, source prefetch and log handling.
18    Short,
19    /// The CPU-only prerequisite builds; the target's `route` wraps these.
20    Cpu,
21    /// The module cache command of the `caches` phase.
22    Cache,
23}
24
25impl Role {
26    /// Every role, in the order `[phase_defaults]` documents them.
27    pub const ALL: [Role; 5] = [Role::Plan, Role::Build, Role::Short, Role::Cpu, Role::Cache];
28    /// The role's key in `[phase_defaults]` and `phases`.
29    pub fn name(self) -> &'static str {
30        match self {
31            Role::Plan => "plan",
32            Role::Build => "build",
33            Role::Short => "short",
34            Role::Cpu => "cpu",
35            Role::Cache => "cache",
36        }
37    }
38}
39
40fn pick(a: &Option<PhaseArgs>, role: Role) -> Option<String> {
41    let a = a.as_ref()?;
42    match role {
43        Role::Plan => a.plan.clone(),
44        Role::Build => a.build.clone(),
45        Role::Short => a.short.clone(),
46        Role::Cpu => a.cpu.clone(),
47        Role::Cache => a.cache.clone(),
48    }
49}
50
51/// Launch arguments of a role: the target override, else the default.
52pub fn role_args(site: &Site, target: &Target, role: Role) -> Option<String> {
53    pick(&target.phases, role).or_else(|| pick(&site.phase_defaults, role))
54}
55
56/// Everything a phase needs to know about where it runs.
57#[derive(Clone)]
58pub struct Scope<'a> {
59    /// The site file.
60    pub site: &'a Site,
61    /// The path of the site file, absolute, exported as `EB_PIPELINE_SITE`
62    /// so that a command can run eb-pipeline on the same file.
63    pub site_file: Option<String>,
64    /// The target the phase runs for.
65    pub target: &'a Target,
66    /// The build type, which picks the target's `build_types` override.
67    pub build_type: Option<&'a str>,
68    /// The run id, `--run-id`.
69    pub run_id: String,
70    /// Timestamp directory name under `filesystems.log_root`.
71    pub log_stamp: String,
72}
73
74impl<'a> Scope<'a> {
75    /// The build type, `default` without one: the `{build}` of job names.
76    pub fn build_name(&self) -> &str {
77        self.build_type.unwrap_or("default")
78    }
79
80    /// `<log_root>/<log stamp>/<target>`, where this run writes its logs.
81    pub fn log_dir(&self) -> String {
82        format!(
83            "{}/{}/{}",
84            self.site.filesystems.log_root.trim_end_matches('/'),
85            self.log_stamp,
86            self.target.name
87        )
88    }
89
90    /// The target's `software_root`, else `software` under
91    /// [`Scope::install_prefix`].
92    pub fn software_root(&self) -> String {
93        self.target
94            .software_root
95            .clone()
96            .unwrap_or_else(|| format!("{}/software", self.install_prefix()))
97    }
98
99    /// The target's `modules_root`, else `modules` under
100    /// [`Scope::install_prefix`].
101    pub fn modules_root(&self) -> String {
102        self.target
103            .modules_root
104            .clone()
105            .unwrap_or_else(|| format!("{}/modules", self.install_prefix()))
106    }
107
108    /// eb-staged-rebuild `--ledger-config` of the target.
109    pub fn ledger_config(&self) -> Option<String> {
110        self.target.ledger_config.clone().or_else(|| {
111            self.site
112                .rebuild
113                .as_ref()
114                .and_then(|r| r.ledger_config.clone())
115        })
116    }
117
118    /// The target's `site_prefix`, else `filesystems.install_root`.
119    pub fn install_prefix(&self) -> String {
120        self.target
121            .site_prefix
122            .clone()
123            .unwrap_or_else(|| self.site.filesystems.install_root.clone())
124    }
125
126    /// EASYBUILD_BUILDPATH of the target.
127    pub fn build_path(&self) -> String {
128        self.per_target(&self.site.filesystems.build_path)
129    }
130
131    /// EASYBUILD_SOURCEPATH entries of the target.
132    pub fn source_paths(&self) -> Vec<String> {
133        let paths = &self.site.filesystems.source_paths;
134        paths.iter().map(|p| self.per_target(p)).collect()
135    }
136
137    /// eb-staged-rebuild `--state-root` of the target; `None` leaves the
138    /// tool's default.
139    pub fn state_root(&self) -> Option<String> {
140        let r = self.site.rebuild.as_ref()?;
141        r.state_root.as_deref().map(|s| self.per_target(s))
142    }
143
144    /// A site path with `{target}` expanded to the target's name.
145    fn per_target(&self, path: &str) -> String {
146        path.replace("{target}", &self.target.name)
147    }
148
149    /// Install path EESSI-extend sets for a site install when it loads, over
150    /// the exported EASYBUILD_INSTALLPATH. EasyBuild prefers the split install
151    /// variables to it, so split mode gets no note.
152    pub fn eessi_install_note(&self) -> Option<String> {
153        let es = self.site.eessi_on()?;
154        if !es.site_install || self.site.filesystems.export_install_vars == "split" {
155            return None;
156        }
157        let base = match self.env().get("EESSI_SITE_SOFTWARE_PREFIX") {
158            Some(p) => format!("{}/versions", p.trim_end_matches('/')),
159            None => "<EESSI repository>/host_injections".into(),
160        };
161        let cpu = self.target.cpu_target.as_deref().unwrap_or("<cpu subdir>");
162        let accel = match self.target.accel_target.as_deref() {
163            Some(a) if !a.is_empty() => {
164                format!(", plus `/{a}` for an NVIDIA target when EESSI_ACCELERATOR_INSTALL is set")
165            }
166            _ => String::new(),
167        };
168        Some(format!(
169            "EESSI-extend replaces EASYBUILD_INSTALLPATH when it loads: \
170             {base}/<release>/software/linux/{cpu}{accel}"
171        ))
172    }
173
174    fn type_override(&self) -> Option<&BuildTypeOverride> {
175        self.build_type.and_then(|b| self.target.build_types.get(b))
176    }
177
178    /// The build type's `eb_optarch`, else the target's.
179    pub fn optarch(&self) -> Option<String> {
180        self.type_override()
181            .and_then(|o| o.eb_optarch.clone())
182            .or_else(|| self.target.eb_optarch.clone())
183    }
184
185    /// The build type's `max_parallel`, else the target's.
186    pub fn max_parallel(&self) -> Option<u32> {
187        self.type_override()
188            .and_then(|o| o.max_parallel)
189            .or(self.target.max_parallel)
190    }
191
192    /// The job name of `phase`: `scheduler.job_name_template` with
193    /// `{project}`, `{build}`, `{phase}` and `{target}` filled in.
194    pub fn job_name(&self, phase: &str) -> String {
195        self.site
196            .scheduler
197            .job_name_template
198            .replace("{project}", self.site.project())
199            .replace("{build}", self.build_name())
200            .replace("{phase}", phase)
201            .replace("{target}", &self.target.name)
202    }
203
204    /// Launch prefix of a phase: route wrapper (CPU role), launch command,
205    /// common arguments, job name, role arguments.
206    pub fn launch(&self, role: Role, phase: &str) -> Result<Vec<String>, Fail> {
207        self.launch_with(role, phase, None)
208    }
209
210    /// Like `launch`, with the role arguments replaced by `args`.
211    pub fn launch_with(
212        &self,
213        role: Role,
214        phase: &str,
215        args: Option<&str>,
216    ) -> Result<Vec<String>, Fail> {
217        self.launch_routed(role, phase, args, (role == Role::Cpu).then_some(phase))
218    }
219
220    /// Like `launch_with`; `route_phase` names the phase to look up in the
221    /// route's `phases` list, or `None` for a command that is not routed.
222    pub fn launch_routed(
223        &self,
224        role: Role,
225        phase: &str,
226        args: Option<&str>,
227        route_phase: Option<&str>,
228    ) -> Result<Vec<String>, Fail> {
229        let mut v = Vec::new();
230        if let Some(rp) = route_phase {
231            v.extend(self.route_prefix(rp)?);
232        }
233        if self.site.scheduler.kind == "slurm" {
234            v.extend(split_args(&self.site.scheduler.launch)?);
235            v.extend(self.site.scheduler.common_args.iter().cloned());
236            v.push(format!("--job-name={}", self.job_name(phase)));
237            let a = args
238                .map(str::to_string)
239                .or_else(|| role_args(self.site, self.target, role));
240            if let Some(a) = a {
241                v.extend(split_args(&a)?);
242            }
243        }
244        Ok(v)
245    }
246
247    /// The target's route when it applies to `phase`.
248    fn active_route(&self, phase: &str) -> Option<&Route> {
249        self.target
250            .route
251            .as_ref()
252            .filter(|r| r.kind == "command" && r.phases.iter().any(|p| p == phase))
253    }
254
255    fn render_basic(&self, t: &str, phase: &str) -> String {
256        let log_dir = self.log_dir();
257        t.replace("{phase_dir}", &format!("{log_dir}/{phase}"))
258            .replace("{log_dir}", &log_dir)
259            .replace("{work_dir}", &self.build_path())
260            .replace("{target}", &self.target.name)
261            .replace("{phase}", phase)
262    }
263
264    fn render_shares(&self, l: &[String], phase: &str) -> String {
265        l.iter()
266            .map(|s| self.render_basic(s, phase))
267            .collect::<Vec<_>>()
268            .join(":")
269    }
270
271    /// Render a route template: the basic placeholders, then the route's own.
272    fn render_route(&self, r: &Route, t: &str, phase: &str) -> String {
273        self.render_basic(t, phase)
274            .replace("{runtime_root}", r.runtime_root.as_deref().unwrap_or(""))
275            .replace("{shares_ro}", &self.render_shares(&r.shares_ro, phase))
276            .replace("{shares_rw}", &self.render_shares(&r.shares_rw, phase))
277    }
278
279    /// Route command, rendered arguments and the `--` separator.
280    fn route_prefix(&self, phase: &str) -> Result<Vec<String>, Fail> {
281        let Some(r) = self.active_route(phase) else {
282            return Ok(Vec::new());
283        };
284        let mut v = split_args(r.command.as_deref().unwrap_or(""))?;
285        if !r.args.is_empty() {
286            v.extend(r.args.iter().map(|a| self.render_route(r, a, phase)));
287            v.push("--".into());
288        }
289        Ok(v)
290    }
291
292    /// Environment of a routed command. `digest` is the run-time value of
293    /// the receipt digest variable; `None` plans the `${NAME}` placeholder.
294    pub fn route_env(&self, phase: &str, digest: Option<&str>) -> BTreeMap<String, String> {
295        let mut e = BTreeMap::new();
296        let Some(r) = self.active_route(phase) else {
297            return e;
298        };
299        for (k, v) in &r.env {
300            e.insert(k.clone(), self.render_route(r, v, phase));
301        }
302        if let Some(root) = &r.runtime_root {
303            e.insert("EB_PIPELINE_ROUTE_RUNTIME_ROOT".into(), root.clone());
304        }
305        if !r.shares_ro.is_empty() {
306            e.insert(
307                "EB_PIPELINE_ROUTE_SHARES_RO".into(),
308                self.render_shares(&r.shares_ro, phase),
309            );
310        }
311        if !r.shares_rw.is_empty() {
312            e.insert(
313                "EB_PIPELINE_ROUTE_SHARES_RW".into(),
314                self.render_shares(&r.shares_rw, phase),
315            );
316        }
317        if let Some(n) = &r.receipt_digest_env {
318            e.insert(
319                "EB_PIPELINE_ROUTE_RECEIPT_DIGEST".into(),
320                digest.map_or_else(|| format!("${{{n}}}"), str::to_string),
321            );
322        }
323        e
324    }
325
326    /// Directories a routed command expects to exist.
327    pub fn route_dirs(&self, phase: &str) -> Vec<String> {
328        match self.active_route(phase) {
329            Some(r)
330                if r.args
331                    .iter()
332                    .chain(&r.shares_ro)
333                    .chain(&r.shares_rw)
334                    .any(|a| a.contains("{phase_dir}")) =>
335            {
336                vec![format!("{}/{}", self.log_dir(), phase)]
337            }
338            _ => Vec::new(),
339        }
340    }
341
342    /// Hardware class variables of a command, exported only when the target
343    /// defines a CPU class.
344    pub fn hardware_env(&self, role: Role) -> BTreeMap<String, String> {
345        let mut e = BTreeMap::new();
346        let Some(cpu) = &self.target.cpu_hardware else {
347            return e;
348        };
349        let hw = if role == Role::Cpu {
350            Some(cpu)
351        } else {
352            self.target.hardware.as_ref()
353        };
354        if let Some(h) = hw {
355            if let Some(v) = &h.vendor_id {
356                e.insert("EB_PIPELINE_HW_VENDOR_ID".into(), v.clone());
357            }
358            if let Some(v) = h.cpu_family {
359                e.insert("EB_PIPELINE_HW_CPU_FAMILY".into(), v.to_string());
360            }
361            if let Some(v) = h.model {
362                e.insert("EB_PIPELINE_HW_MODEL".into(), v.to_string());
363            }
364        }
365        e
366    }
367
368    /// The target's fetch profile as JSON, for source prefetch commands.
369    pub fn fetch_env(&self) -> BTreeMap<String, String> {
370        let mut e = BTreeMap::new();
371        if let Some(p) = &self.target.fetch_profile {
372            if let Ok(j) = serde_json::to_string(p) {
373                e.insert("EB_PIPELINE_FETCH_PROFILE".into(), j);
374            }
375        }
376        e
377    }
378
379    /// Environment exported to every phase.
380    pub fn env(&self) -> BTreeMap<String, String> {
381        let s = self.site;
382        let mut e: BTreeMap<String, String> = s.scheduler.env.clone();
383        let fs = &s.filesystems;
384        let mut put = |k: &str, v: String| {
385            e.insert(k.to_string(), v);
386        };
387        put("EASYBUILD_TMPDIR", fs.tmp.clone());
388        put("EASYBUILD_BUILDPATH", self.build_path());
389        if !fs.source_paths.is_empty() {
390            put("EASYBUILD_SOURCEPATH", self.source_paths().join(":"));
391        }
392        if fs.export_install_vars == "split" {
393            put("EASYBUILD_INSTALLPATH_SOFTWARE", self.software_root());
394            put("EASYBUILD_INSTALLPATH_MODULES", self.modules_root());
395        } else {
396            put("EASYBUILD_INSTALLPATH", self.install_prefix());
397        }
398        if let Some(o) = self.optarch() {
399            put("EASYBUILD_OPTARCH", o);
400        }
401        if let Some(p) = self.max_parallel() {
402            put("EASYBUILD_MAX_PARALLEL", p.to_string());
403        }
404        if let Some(c) = &self.target.cuda_compute_capabilities {
405            put("EASYBUILD_CUDA_COMPUTE_CAPABILITIES", c.clone());
406        }
407        if fs.read_only_installdir {
408            put(
409                "EASYBUILD_READ_ONLY_INSTALLDIR",
410                fs.read_only_installdir_value.clone(),
411            );
412        }
413        if let Some(c) = &fs.configs_repo {
414            put("EASYBUILD_CONFIGS_REPOPATH", c.clone());
415        }
416        if let Some(f) = &self.site_file {
417            put("EB_PIPELINE_SITE", f.clone());
418        }
419        put("EB_PIPELINE_SITE_NAME", s.site.name.clone());
420        put("EB_PIPELINE_TARGET", self.target.name.clone());
421        put("EB_PIPELINE_BUILD_TYPE", self.build_name().to_string());
422        put("EB_PIPELINE_RUN_ID", self.run_id.clone());
423        put("EB_PIPELINE_LOG_STAMP", self.log_stamp.clone());
424        put("EB_PIPELINE_LOG_DIR", self.log_dir());
425        if let Some(a) = &s.site.build_account {
426            put("EB_PIPELINE_BUILD_ACCOUNT", a.clone());
427        }
428        if let Some(g) = &s.site.default_group {
429            put("EB_PIPELINE_DEFAULT_GROUP", g.clone());
430        }
431        if !s.modules.init.is_empty() {
432            put("EB_PIPELINE_MODULES", s.modules.init.join(" "));
433        }
434        if s.modules.unuse_path {
435            put("EB_PIPELINE_UNUSE_PATH", "1".into());
436        }
437        if let Some(f) = &s.modules.shell_init {
438            put("EB_PIPELINE_SHELL_INIT", f.clone());
439        }
440        if let Some(es) = s.eessi_on() {
441            if es.site_install {
442                put("EESSI_SITE_INSTALL", "1".into());
443            }
444            if let Some(b) = &es.bootstrap_modulepath {
445                put("EESSI_SITE_BOOTSTRAP_MODULEPATH", b.clone());
446            }
447            if let Some(c) = &self.target.cpu_target {
448                put(&es.cpu_override_var, c.clone());
449            }
450            if let Some(a) = &self.target.accel_target {
451                put(&es.accel_override_var, a.clone());
452            }
453            // The same prefix EasyBuild installs into. An explicit
454            // `site_prefix` wins; otherwise this is `filesystems.install_root`,
455            // so a site layer and EasyBuild do not install to two places.
456            put("EESSI_SITE_SOFTWARE_PREFIX", self.install_prefix());
457        }
458        e
459    }
460
461    /// Environment added for one build list line.
462    pub fn line_env(&self, easyconfig: &str) -> BTreeMap<String, String> {
463        let (name, version) = package_of(easyconfig);
464        let mut e = BTreeMap::new();
465        if let Some(p) = self.site.modules.package_env.get(&name) {
466            e.extend(p.clone());
467        }
468        if let Some(p) = self.target.package_env.get(&name) {
469            e.extend(p.clone());
470        }
471        if let Some(l) = self.site.licences_on() {
472            if let Some(p) = l.env.get(&name) {
473                e.extend(p.clone());
474            }
475            if let Some(g) = licence_group(l, &name, version.as_deref()) {
476                e.insert("EB_PIPELINE_LICENCE_GROUP".into(), g);
477            }
478        }
479        e
480    }
481
482    /// Wrapper that loads modules before the wrapped command runs.
483    pub fn module_wrap(&self) -> Vec<String> {
484        let m = &self.site.modules;
485        if m.init.is_empty() && !m.unuse_path && m.shell_init.is_none() {
486            return Vec::new();
487        }
488        vec![
489            m.shell.clone(),
490            "-c".into(),
491            MODULE_SCRIPT.into(),
492            "eb-pipeline".into(),
493        ]
494    }
495}
496
497/// Fixed script of the module wrapper; module names arrive through the
498/// environment, never through interpolation. The site's init is sourced
499/// without `-e` or `-u`, as a login shell sources it: EESSI's Lmod init
500/// reads variables it never sets. `module` and the command run under `-e`.
501/// The names are split with pathname expansion off, so that `module load`
502/// gets each one as written, and back on for `module load` itself.
503pub const MODULE_SCRIPT: &str =
504    "if [ -n \"${EB_PIPELINE_SHELL_INIT:-}\" ]; then . \"$EB_PIPELINE_SHELL_INIT\"; fi
505set -e
506if [ -n \"${EB_PIPELINE_UNUSE_PATH:-}\" ]; then MODULEPATH=; export MODULEPATH; fi
507module purge
508set -f
509for m in ${EB_PIPELINE_MODULES:-}; do set +f; module load \"$m\"; done
510set +f
511exec \"$@\"";
512
513/// Shells that `modules.shell` may name, by name or by path. The wrapper
514/// needs a POSIX shell, which splits an unquoted expansion at white space and
515/// takes `set -f`: zsh does neither, and csh, tcsh and fish cannot parse it.
516pub const MODULE_SHELLS: &[&str] = &["sh", "bash", "dash", "ash", "ksh", "ksh93", "mksh", "yash"];
517
518/// Group that applies to a package, if any. A version that does not parse
519/// gets the group (fail closed).
520pub fn licence_group(l: &Licences, name: &str, version: Option<&str>) -> Option<String> {
521    let g = l.groups.get(name)?;
522    if let Some(limit) = l.below_version.get(name) {
523        let lim = crate::util::parse_version(limit)?;
524        if let Some(v) = version.and_then(|v| {
525            let core: String = v
526                .chars()
527                .take_while(|c| c.is_ascii_digit() || *c == '.')
528                .collect();
529            crate::util::parse_version(core.trim_end_matches('.'))
530        }) {
531            if crate::util::cmp_version(&v, &lim) != std::cmp::Ordering::Less {
532                return None;
533            }
534        }
535    }
536    Some(g.clone())
537}
538
539fn strip_nulls(v: Value) -> Value {
540    match v {
541        Value::Object(m) => Value::Object(
542            m.into_iter()
543                .filter(|(_, v)| !v.is_null())
544                .map(|(k, v)| (k, strip_nulls(v)))
545                .collect(),
546        ),
547        Value::Array(a) => Value::Array(a.into_iter().map(strip_nulls).collect()),
548        o => o,
549    }
550}
551
552/// Resolved view of one or all targets after defaults and overrides.
553/// `site_file` is the `EB_PIPELINE_SITE` of the environment it shows.
554pub fn explain(
555    site: &Site,
556    site_file: Option<&str>,
557    target: Option<&str>,
558    build_type: Option<&str>,
559) -> Result<Value, Fail> {
560    let selected: Vec<&Target> = match target {
561        Some(t) => vec![site.target(t)?],
562        None => site.targets.iter().collect(),
563    };
564    let mut targets = Vec::new();
565    for t in selected {
566        let scope = Scope {
567            site,
568            site_file: site_file.map(str::to_string),
569            target: t,
570            build_type,
571            run_id: "<run-id>".into(),
572            log_stamp: "<log-stamp>".into(),
573        };
574        let mut phases = serde_json::Map::new();
575        for role in Role::ALL {
576            phases.insert(
577                role.name().into(),
578                json!({
579                    "args": role_args(site, t, role),
580                    "launch": scope.launch_routed(
581                        role,
582                        role.name(),
583                        None,
584                        (role == Role::Cpu).then_some("build"),
585                    )?,
586                }),
587            );
588        }
589        targets.push(json!({
590            "name": t.name,
591            "default": t.default,
592            "build_lists": t.build_lists,
593            "eb_optarch": scope.optarch(),
594            "max_parallel": scope.max_parallel(),
595            "cuda_compute_capabilities": t.cuda_compute_capabilities,
596            "cpu_target": t.cpu_target,
597            "accel_target": t.accel_target,
598            "site_prefix": scope.install_prefix(),
599            "software_root": scope.software_root(),
600            "modules_root": scope.modules_root(),
601            "install_note": scope.eessi_install_note(),
602            "staged": t.staged,
603            "state_root": scope.state_root(),
604            "ledger_config": scope.ledger_config(),
605            "route": t.route,
606            "select": t.select,
607            "hardware": t.hardware,
608            "cpu_hardware": t.cpu_hardware,
609            "fetch_profile": t.fetch_profile,
610            "package_env": if t.package_env.is_empty() { Value::Null } else { json!(t.package_env) },
611            "phases": phases,
612            "env": scope.env(),
613        }));
614    }
615    Ok(strip_nulls(json!({
616        "site": {
617            "name": site.site.name,
618            "project": site.project(),
619        },
620        "build_type": build_type,
621        "scheduler": {
622            "kind": site.scheduler.kind,
623            "launch": site.scheduler.launch,
624            "common_args": site.scheduler.common_args,
625            "job_name_template": site.scheduler.job_name_template,
626        },
627        "targets": targets,
628    })))
629}