Skip to content

Commit 3e99364

Browse files
bcummingbcumming
committed
big refactor
1 parent 6b35d3c commit 3e99364

File tree

6 files changed

+1120
-723
lines changed

6 files changed

+1120
-723
lines changed

‎docs/images/uenv/uenv-store.png‎

108 KB
Loading

‎docs/software/uenv/guides.md‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
[](){#ref-uenv-guides}
2+
# uenv guides
3+
4+
This page contains guides for features and work
5+
6+
[](){#ref-uenv-labels}
7+
## uenv labels
8+
9+
Uenv are referred to using **labels**, which are used to refer to specific uenv, or groups of uenv, with the uenv command line tool.
10+
Each label has the following form:
11+
12+
```
13+
name/version:tag@system%uarch
14+
```
15+
16+
The different fields are described in the following table:
17+
18+
| label | meaning |
19+
|-------|---------|
20+
| `name` | name of the uenv, e.g. `gromacs`, `prgenv-gnu` |
21+
| `version` | version of the uenv: e.g. `v8.7`, `2025.01` |
22+
| `tag` | a tag applied by CSCS |
23+
| `uarch` | node microarchitecture: one of `gh200`, `a100`, `zen2`, `mi200`, `mi300a`, `zen3` |
24+
| `cluster` | name of the cluster, e.g. `daint`, `clariden`, `eiger` or `santis` |
25+
26+
!!! example "Example labels"
27+
??? note "`prgenv-gnu/24.11:v2@daint%gh200`"
28+
The `prgenv-gnu` programming environment, built on [Daint][ref-cluster-daint] for the Grace-Hopper GH200 (`gh200`) architecture.
29+
30+
* the _version_ `24.11` refers to the version
31+
* the _tag_ `v2` refers to a minor update to the uenv (e.g. a bug fix or addition of a new package).
32+
33+
??? note "`cp2k/2025.1:v3@eiger%zen2`"
34+
The uenv provides version 2025.1 of the CP2K simulation code, built for the AMD Rome (`zen2`) architecture of [Eiger][ref-cluster-eiger].
35+
36+
* the _version_ `2025.1` refers to the CP2K version [v2025.1](https://github.com/cp2k/cp2k/releases/tag/v2025.1)
37+
* the _tag_ `v2` refers to a minor update by CSCS to the original `v1` version of the uenv that had a bug.
38+
39+
For more information about the labeling scheme, see the [uenv deployment][ref-uenv-deploy-versions] docs.
40+
41+
[](){#ref-uenv-labels-examples}
42+
### Using labels
43+
44+
The uenv command line interface (CLI) has a flexible interface for filtering uenv by providing only part of the full label.
45+
Below are some examples of using labels with the CLI (see documentation for the individual commands for more information):
46+
47+
```bash
48+
# search for all uenv on the current system that have the name prgenv-gnu
49+
uenv image find prgenv-gnu
50+
51+
# search for all uenv with version 24.11
52+
uenv image find /24.11
53+
54+
# search for all uenv with tag v1
55+
uenv image find :v1
56+
57+
# search for a specific version
58+
uenv image find prgenv-gnu/24.11:v1
59+
```
60+
61+
By default, `uenv` filters results to uenv that were built for the current cluster.
62+
The name of the current cluster is always available via the `CLUSTER_NAME` environment variable.
63+
64+
```console
65+
# log into the eiger vCluster
66+
$ ssh eiger
67+
68+
# this command will search for all prgenv-gnu uenv on _eiger_
69+
$ uenv image find prgenv-gnu
70+
71+
# use @ to search on a specific system, e.g. on daint:
72+
$ uenv image find prgenv-gnu@daint
73+
74+
# this can be used to search for all uenv on daint:
75+
$ uenv image find @daint
76+
77+
# use '*' as a wildcard used meaning "all systems"
78+
# this will show all images on all systems
79+
uenv image find @*
80+
81+
# search for all images on Alps that were built for gh200 nodes.
82+
uenv image find @*%gh200
83+
```
84+
85+
[](){#ref-uenv-customenv}
86+
## Custom environments
87+
88+
!!! warning "[Keep bashrc clean][ref-guides-terminal-bashrc]"
89+
90+
It is common practice to add `module` commands to `~.bashrc`, for example
91+
```bash title="~/.bashrc"
92+
# make my custom modules available
93+
module use $STORE/myenv/modules
94+
# load the modules that I always want in the environment
95+
module load ncview
96+
```
97+
98+
This will make custom modules available, and load `ncview`, every time you log in.
99+
It is not possible to do the equivalent with `uenv start`, for example:
100+
```bash title="~/.bashrc"
101+
# start the uenv that I always use
102+
uenv start prgenv-gnu/24.11:v2 --view=default
103+
# ERROR: the following lines will not be executed
104+
module use $STORE/myenv/modules
105+
module load ncview
106+
```
107+
108+
!!! question "Why can't I use `uenv start` in `~/.bashrc`?"
109+
The `module` command uses some "clever" tricks to modify the environment variables in your current shell.
110+
For example, `module load ncview` will modify the value of environment variables like `PATH`, `LD_LIBRARY_PATH`, and `PKG_CONFIG_PATH`.
111+
112+
The `uenv start` command loads a uenv, and __starts a new shell__, ready for you to enter commands.
113+
This means that lines in the `.bashrc` that follow the command are never executed.
114+
115+
Things are further complicated because if `uenv start` is executed inside `~/.bashrc`, the shell is not a tty shell.
116+
117+
It is possible to create a custom command that will start a new shell with a uenv loaded, with additional customizations to the environment (e.g. loading modules and setting environment variables).
118+
119+
The first step is to create a script that performs the the customization steps to perform once the uenv has been loaded.
120+
Here is an example for an environment called `myenv`:
121+
122+
```bash title="~/.myenvrc"
123+
# always add this line
124+
source ~/.bashrc
125+
126+
# then add customization commands here
127+
module use $STORE/myenv/modules
128+
module load ncview
129+
export DATAPATH=$STORE/2025/data
130+
```
131+
132+
Then create an alias in `~/.bashrc` for the `myenv` environment:
133+
134+
```bash title="~/.bashrc"
135+
alias myenv='uenv run prgenv-gnu/24.11:v2 --view=default -- bash --rcfile ~/.myenvrc'
136+
```
137+
138+
This alias uses `uenv run` to start a new bash shell that will apply the customizations in `~/.myenvrc` once the uenv has been loaded.
139+
Then, the environment can be started with a single command once logged in.
140+
141+
```console
142+
$ ssh eiger.cscs.ch
143+
$ myenv
144+
```
145+
146+
The benefit of this approach is that you can create multiple environments, whereas modifying `.bashrc` will lock you into using the same environment every time you log in.
147+
148+
149+
150+
[](){#ref-uenv-uninstall}
151+
## Uninstalling the uenv tool
152+
153+
It is strongly recommended to use the version of uenv installed on the system, instead of installing your own version from source.
154+
This guide walks through the process of detecting if you have an old version installed, and removing it.
155+
156+
!!! note
157+
In the past CSCS has recommended installing a more recent version of uenv to help fix issues for some users.
158+
Some users still have old self-installed versions installed in `HOME`, so they are missing out on new uenv features, and possibly seeing errors on systems with the most recent `v9.0.0` uenv installed.
159+
160+
!!! warning "error caused by incompatible uenv version"
161+
If trying to use `uenv run` or `uenv start`, and you see an error message like the following:
162+
163+
```
164+
error: unable to exec '/capstor/scratch/cscs/wombat/.uenv-images/images/61d1f21881a6....squashfs:/user-environment':
165+
No such file or directory (errno=2)
166+
```
167+
168+
Then you are probably using an old version of uenv that is not compatible with the version of `squashfs-mount` installed on the system.
169+
170+
First, log into the target cluster, and enter `type uenv` and inspect the output.
171+
172+
The system version of `uenv` is installed in `/usr/bin`, so if you see the following you do not need to make any changes:
173+
174+
```console
175+
$ type uenv
176+
uenv is /usr/bin/uenv
177+
```
178+
179+
Version 5 of uenv used a bash function called `uenv`, which will give output that looks like this:
180+
181+
```console
182+
$ type uenv
183+
uenv is a function
184+
uenv ()
185+
{
186+
local _last_exitcode=$?;
187+
function uenv_usage ()
188+
{
189+
...
190+
```
191+
192+
If you have installed version 6, 7, 8 or 9, it will be in a different location, for example:
193+
194+
```console
195+
$ type uenv
196+
uenv is /users/voldemort/.local/bin/uenv
197+
```
198+
199+
??? question "why not use `which uenv`?"
200+
The `which uenv` command searches the directories listed in the `PATH` environment variable for the `uenv` executable, and ignores bash functions.
201+
If there is a `uenv` bash function is set, then it will be take precedence over the `uenv` executable found using `which uenv`.
202+
203+
To remove uenv version 6, 7, 8 or 9, delete the executable, then force bash to forget the old command.
204+
205+
```console
206+
# remove your self-installed executable
207+
$ rm $(which uenv)
208+
209+
# forget the old uenv command
210+
$ hash -r
211+
212+
# type and which should point to the same executable in /usr/bin
213+
$ type uenv
214+
uenv is /usr/bin/uenv
215+
$ which uenv
216+
/usr/bin/uenv
217+
```
218+
219+
To remove version 5, look in your `.bashrc` file for a line like the following and remove or comment it out:
220+
221+
```bash
222+
# configure the user-environment (uenv) utility
223+
source /users/voldemort/.local/bin/activate-uenv
224+
```
225+
226+
Log out and back in again, then issue the following command to force bash to forget the old uenv command:
227+
```console
228+
# forget the old uenv command
229+
$ hash -r
230+
231+
# type and which should point to the same executable in /usr/bin
232+
$ type uenv
233+
uenv is /usr/bin/uenv
234+
$ which uenv
235+
/usr/bin/uenv
236+
```
237+

0 commit comments

Comments
 (0)