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