diff --git a/docs/software/uenv/index.md b/docs/software/uenv/index.md index b336da77..426a2a45 100644 --- a/docs/software/uenv/index.md +++ b/docs/software/uenv/index.md @@ -368,6 +368,7 @@ By default, the modules are not activated when a uenv is started, and need to be cmake version 3.30.5 ``` +[](){#ref-uenv-error-v9modules} ??? warning "bash: module: command not found" Version 9.0.0 of uenv, installed on October 22 2025, has a bug that removes the module command on Santis and Clariden. @@ -532,32 +533,6 @@ it is possible to override the default uenv by passing a different `--uenv` and * Note how the second call has access to `mpicc`, provided by `prgenv-gnu`. -[](){#ref-uenv-installation} -## Installing the uenv tool - -The command line tool can be installed from source, if you are working on a cluster that does not have uenv installed, or if you need to test a new version. - -!!! note - uenv is installed already on CSCS clusters, so installation is not required. - - Only follow these steps if you are advised to test out a new version (e.g. if it has a fix for an issues that you are encountering). - -```bash -git clone https://github.com/eth-cscs/uenv2.git -cd uenv2 - -./install-alps-local.sh # (1)! - -# update bashrc -echo "export PATH=\$HOME/.local/\$(uname -m)/bin:\$PATH" >> $HOME/.bashrc -echo "unset -f uenv" >> $HOME/.bashrc -``` - -1. Run installation script. This will install uenv in `$HOME/.local/$(uname -m)/bin/`. - -!!! warning - Before uenv can be used, you need to log out then back in again and type `which uenv` to verify that uenv has been installed in your `$HOME` path. - [](){#ref-uenv-labels} ## uenv labels @@ -701,3 +676,100 @@ $ myenv ``` 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. + +[](){#ref-uenv-uninstall} +## Uninstalling the uenv tool + +It is strongly recommended to use the version of uenv installed on the system, instead of installing your own version from source. +This guide walks through the process of detecting if you have an old version installed, and removing it. + +!!! note + In the past CSCS has recommended installing a more recent version of uenv to help fix issues for some users. + 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. + +!!! warning "error caused by incompatible uenv version" + If trying to use `uenv run` or `uenv start`, and you see an error message like the following: + + ``` + error: unable to exec '/capstor/scratch/cscs/wombat/.uenv-images/images/61d1f21881a6....squashfs:/user-environment': + No such file or directory (errno=2) + ``` + + Then you are probably using an old version of uenv that is not compatible with the version of `squashfs-mount` installed on the system. + +### Detecting which version of uenv is installed + +First, log into the target cluster, and enter `type uenv` and inspect the output. + +The system version of `uenv` is installed in `/usr/bin`, so if you see the following you do not need to make any changes: + +```console +$ type uenv +uenv is /usr/bin/uenv +``` + +Version 5 of uenv used a bash function called `uenv`, which will give output that looks like this: + +```console +$ type uenv +uenv is a function +uenv () +{ + local _last_exitcode=$?; + function uenv_usage () + { +... +``` + +If you have installed version 6, 7, 8 or 9, it will be in a different location, for example: + +```console +$ type uenv +uenv is /users/voldemort/.local/bin/uenv +``` + +??? question "why not use `which uenv`?" + The `which uenv` command searches the directories listed in the `PATH` environment variable for the `uenv` executable, and ignores bash functions. + If there is a `uenv` bash function is set, then it will be take precedence over the `uenv` executable found using `which uenv`. + +### Removing version 6 or later + +To remove uenv version 6, 7, 8 or 9, delete the executable, then force bash to forget the old command. + +```console +# remove your self-installed executable +$ rm $(which uenv) + +# forget the old uenv command +$ hash -r + +# type and which should point to the same executable in /usr/bin +$ type uenv +uenv is /usr/bin/uenv +$ which uenv +/usr/bin/uenv +``` + +### Removing version 5 + +To remove version 5, look in your `.bashrc` file for a line like the following and remove or comment it out: + +```bash +# configure the user-environment (uenv) utility +source /users/voldemort/.local/bin/activate-uenv +``` + +Log out and back in again, then issue the following command to force bash to forget the old uenv command: +```console +# forget the old uenv command +$ hash -r + +# type and which should point to the same executable in /usr/bin +$ type uenv +uenv is /usr/bin/uenv +$ which uenv +/usr/bin/uenv +``` + + + diff --git a/docs/software/uenv/release-notes.md b/docs/software/uenv/release-notes.md index 61ba1f19..6474af2a 100644 --- a/docs/software/uenv/release-notes.md +++ b/docs/software/uenv/release-notes.md @@ -29,6 +29,17 @@ This [version](https://github.com/eth-cscs/uenv2/releases/tag/v9.0.0) will repla - a bug where the `--only-meta` flag was ignored on `image pull`. - add hints to error message when uenv is not found. +[](){#ref-uenv-release-notes-v9.0.0-issues} +### Known issues + +!!! warning "user-installed uenv stopped working" + This version introduced changes to the `squashfs-mount` tool used by `uenv start` and `uenv -run` that are incompatible with older versions of uenv. + If you see errors that contain `error: unable to exec '...': No such file or directory (errno=2)`, follow the guide for [uninstalling user-installed uenv][ref-uenv-uninstall]. + +!!! warning "bash: module: command not found" + This is a known issue with version 9.0.0 that will be fixed in 9.0.1. + See the [uenv modules][ref-uenv-error-v9modules] docs for a workaround. + [](){#ref-uenv-release-notes-v8.1.0} ## v8.1.0