From 599b57105fc80e635a5c387b0f42411b33f5024c Mon Sep 17 00:00:00 2001
From: bcumming <bcumming@cscs.ch>
Date: Tue, 21 May 2024 07:33:55 +0200
Subject: [PATCH] start work on proposal and wip code for env var setting

---
 env-var.py | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 todo.md    | 66 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 146 insertions(+)
 create mode 100644 env-var.py
 create mode 100644 todo.md

diff --git a/env-var.py b/env-var.py
new file mode 100644
index 0000000..011a93a
--- /dev/null
+++ b/env-var.py
@@ -0,0 +1,80 @@
+from enum import Enum
+from typing import Optional
+
+class EnvVarOp (Enum):
+    PREPEND=1
+    APPEND=2
+    SET=3
+
+class EnvVarKind (Enum):
+    SCALAR=2
+    LIST=2
+
+def is_env_value_list(v):
+    return isinstance(v, list) and all(isinstance(item, str) for item in v)
+
+class ListEnvVarUpdate():
+    def __init__(self, value: list[str], op: EnvVarOp):
+        self._value = value
+        self._op = op
+
+    @property
+    def op(self):
+        return self._op
+
+    @property
+    def value(self):
+        return self._value
+
+class EnvVar:
+    def __init__(self, name: str):
+        self._name = name
+
+    @property
+    def name(self):
+        return self._name
+
+class ListEnvVar(EnvVar):
+    def __init__(self, name: str, value: list[str], op: EnvVarOp):
+        super().__init__(name)
+
+        self._updates = [ListEnvVarUpdate(value, op)]
+
+    def update(self, value: list[str], op:EnvVarOp):
+        self._updates.append(ListEnvVarUpdate(value, op))
+
+class ScalarEnvVar(EnvVar):
+    def __init__(self, name: str, value: Optional[str]):
+        super().__init__(name)
+        self._value = value
+
+    @property
+    def value(self):
+        return self._value
+
+    @property
+    def is_null(self):
+        return self.value is None
+
+    def update(self, value: Optional[str]):
+        self._value = value
+
+class Env:
+    def __init__(self):
+        self._vars = {}
+
+    def apply(self, var: EnvVar):
+        self._vars[var.name] = var
+
+    def print(self):
+        for name, var in self._vars.items():
+            print(f"{name}: {var.value}")
+
+env = Env()
+
+s = ScalarEnvVar("CUDA_HOME", "/opt/nvidia/cuda12")
+#l = ListEnvVar("PATH", ["/usr/bin", "/opt/nvidia/cuda12/bin"], EnvVarOp.APPEND)
+
+env.apply(s)
+#env.apply(l)
+env.print()
diff --git a/todo.md b/todo.md
new file mode 100644
index 0000000..e2dbcec
--- /dev/null
+++ b/todo.md
@@ -0,0 +1,66 @@
+Design document for handling of environment variables.
+
+The uenv CLI and Slurm plugin need to modify environment variables, to implement some key features that automatically configure the runtime environment according to flags and configuration files provided when launching a job or starting a uenv.
+
+This document outlines a single design for how this should be achieved for all use cases and both the CLI and Slurm plugin use case.
+
+## Use Cases
+
+### Activating views
+
+Activating a view sets environment variables like `PATH`, `PKG_CONFIG_PATH`, etc.
+
+### Enabling modules
+
+To automatically enable modules, the MODULEPATH variable needs to be prenended.
+
+### Configuration files
+
+We want to support configruation files that specify a uenv, and how the environment should be configured, fo users.
+
+This includes explicitly setting environment variables.
+
+## Constraints
+
+The main constraint is how Slurm executes jobs. The Slurm daemon starts a single process on each node, then forks into a separate process for each MPI rank on the node.
+Each fork then runs the user-provided command using `execve`. At no point is a new shell started.
+
+As a result, it is not possible to source a shell script in the environment, that might set environment variables.
+Instead, the only way to modify the environment is to use the `spank_setenv` function, which updates a list of environment variables to be passed to `execve`.
+
+Environment modification:
+- create a new namespace and mount squashfs images.
+- set environment variables using `spank_setenv`, `os.setenv`, etc.
+
+## Features
+
+1. support for scalar and list variables.
+2. three different modes for setting values
+    - set: scalar and list variabls
+    - unset: scalar and list variabls
+    - prepend: list variables
+    - append: list variables
+
+
+Data structure
+
+- `var.type`
+    - `scalar`: a scalar value
+    - `list`: a colon separated list, like `PATH`, `LD_LIBRARY_PATH`, etc.
+- `var.operation` is one of
+    - `prepend`: prepend to a list
+    - `append`: prepend to a list
+    - `set`: set the value to equal
+    - `unset`: 
+each variable has three values
+- var.old
+    - the value currently set in the environment, before modification
+    - can be `null`
+- var.value
+    - the value provided by uenv
+- var.new
+    - the value set by uenv
+    - this is apply(env.delta, env.old, env.operation)
+
+
+class envVar: