Update existing Doc on how to use EESSI #317

TopRichard · 2024-10-08T12:41:14Z

Updating setting_up_environment.md in EESSI docs by adding EESSI module usage

docs/using_eessi/setting_up_environment.md

trz42

Looks good ... it feels a bit like one would have to know a bit about the system you're running on or read through several alternatives before you get going. Too many choices. Would be nice if one could just say eessi init and the best option is chosen. Then if one wants more control one specifies options to this command (or uses one of the alternatives listed here).

docs/using_eessi/setting_up_environment.md

ocaisa · 2024-10-16T13:36:52Z

It is perhaps even more complicated than this, as we haven't told them what to do if they are using a shell other than bash, for Lmod there are multiple permitted options.

trz42 · 2024-10-17T09:02:54Z

It is perhaps even more complicated than this, as we haven't told them what to do if they are using a shell other than bash, for Lmod there are multiple permitted options.

That's right. I wonder if - eventually - we can come up with a single command that works for most users.

For now, it's ok to accept that such a single command doesn't exist yet and we provide information about all the alternatives.

ocaisa · 2024-10-17T09:08:53Z

You can, but that will ultimately be a wrapper around Lmod (you're basically trying to reimplement the same thing that module load ... does), and then you would still need shell specific versions of the wrappers.

Unless such a command starts a subshell...which is possible. You could set BASH_ENV and start a prefix shell.

Co-authored-by: Thomas Röblitz <[email protected]>

ocaisa

Couple of other suggestions

docs/using_eessi/setting_up_environment.md

ocaisa · 2024-10-18T08:32:01Z

docs/using_eessi/setting_up_environment.md

+
+    :clap: Your environment is now set up, you are ready to start running software provided by EESSI!
+
+3.  Should Lmod be unavailable and `MODULEPATH` not utilized, you can initialise EESSI via an Lmod module by directly sourcing the Lmod initialisation script (this script automatically loads the EESSI module):


To keep things simple, we should probably start with this and then have a collapsed section for "Other scenarios" that mentions the two other approaches (and the note/warning about unsetting the MODULEPATH). That way the two approaches are equivalent for typical use case.

See https://squidfunk.github.io/mkdocs-material/reference/admonitions/?h=admon#collapsible-blocks

3. Should Lmod be unavailable and `$MODULEPATH` not used, you can initialise EESSI via an Lmod module by directly sourcing the Lmod initialisation script (this script automatically loads the EESSI module):

ocaisa · 2024-10-18T08:36:11Z

docs/using_eessi/setting_up_environment.md

+3.  Should Lmod be unavailable and `MODULEPATH` not utilized, you can initialise EESSI via an Lmod module by directly sourcing the Lmod initialisation script (this script automatically loads the EESSI module):
+
+    ``` { .bash .copy }
+    source /cvmfs/software.eessi.io/versions/2023.06/init/lmod/bash


We should make it clear that there are a range of options available here

or use $SHELL instead of harcoding bash?

I checked yesterday and $SHELL is not reliable for the supported shells, $0 is more reliable but not very visually helpful

(or rather the even worse $(basename $0))

ocaisa · 2024-10-18T08:37:19Z

docs/using_eessi/setting_up_environment.md

+
+## Sourcing the EESSI `bash` initialisation script
+
+You can initialise EESSI (in a non-reversible way) by running the command:


I think it is worth explicitly saying that this command only works with bash, and if you use another shell you should take the other approach.

how to check (echo $SHELL)

Co-authored-by: ocaisa <[email protected]>

boegel · 2024-10-18T12:49:23Z

docs/using_eessi/setting_up_environment.md

+
+   !!! note "Why do we recommend to unset `MODULEPATH`?"
+
+        Unsetting MODULEPATH may not be possible at some sites, and some compromise or workaround may


Suggested change

Unsetting MODULEPATH may not be possible at some sites, and some compromise or workaround may

Unsetting the `$MODULEPATH` environment variable, which tells Lmod in which directories environment module files are available, may not be possible at some sites, and some compromise or workaround may

boegel · 2024-10-18T12:49:51Z

docs/using_eessi/setting_up_environment.md

+
+        Unsetting MODULEPATH may not be possible at some sites, and some compromise or workaround may
+        be necessary. The underlying reason to suggest this is that EESSI and your system are most likely based on
+        two different operating system distributions - EESSI uses Gentoo Prefix, your system almost certainly uses some other


I wouldn't mention Gentoo Prefix here, keep it more general (compatibility layer + link to the corresponding page)

boegel · 2024-10-18T12:50:06Z

docs/using_eessi/setting_up_environment.md

+        Unsetting MODULEPATH may not be possible at some sites, and some compromise or workaround may
+        be necessary. The underlying reason to suggest this is that EESSI and your system are most likely based on
+        two different operating system distributions - EESSI uses Gentoo Prefix, your system almost certainly uses some other
+        distribution. If you can find a way to ensure that the _software stacks_ from your site and EESSI do not mix


distribution -> Linux distribution

boegel · 2024-10-18T12:50:32Z

docs/using_eessi/setting_up_environment.md

+
+1.  You are already using Lmod with version >= 8.6
+
+    In this case, we _recommend_ unsetting the `MODULEPATH`, because EESSI is not designed to mix modules coming from EESSI and from your system.


In this case, we _recommend_ unsetting `$MODULEPATH`, because EESSI is not designed to mix modules coming from EESSI and from your system.

boegel · 2024-10-18T12:51:04Z

docs/using_eessi/setting_up_environment.md

+    unset MODULEPATH
+    export MODULEPATH=/cvmfs/software.eessi.io/init/modules


If you're doing a hard set, then there's no need to unset?

boegel · 2024-10-18T12:52:04Z

docs/using_eessi/setting_up_environment.md

+
+2.  You are using an Lmod with a version older than 8.6 or any other tool utilizing `MODULEPATH` (Tmod, etc.)
+
+    You should unset MODULEPATH to prevent Lmod from attempting to build a cache for your module tree (as this can be very slow if you have


Suggested change

You should unset MODULEPATH to prevent Lmod from attempting to build a cache for your module tree (as this can be very slow if you have

You should unset `$MODULEPATH` to prevent Lmod from attempting to build a cache for your module tree (as this can be very slow if you have

boegel · 2024-10-18T12:52:19Z

docs/using_eessi/setting_up_environment.md

+2.  You are using an Lmod with a version older than 8.6 or any other tool utilizing `MODULEPATH` (Tmod, etc.)
+
+    You should unset MODULEPATH to prevent Lmod from attempting to build a cache for your module tree (as this can be very slow if you have
+    a lot of modules). Again, unsetting the MODULEPATH should be considered as a good idea in general so you do not mix local and EESSI


Suggested change

a lot of modules). Again, unsetting the MODULEPATH should be considered as a good idea in general so you do not mix local and EESSI

a lot of modules). Again, unsetting the `$MODULEPATH` should be considered as a good idea in general so you do not mix local and EESSI

boegel · 2024-10-18T12:52:45Z

docs/using_eessi/setting_up_environment.md

+
+    :clap: Your environment is now set up, you are ready to start running software provided by EESSI!
+
+3.  Should Lmod be unavailable and `MODULEPATH` not utilized, you can initialise EESSI via an Lmod module by directly sourcing the Lmod initialisation script (this script automatically loads the EESSI module):


3. Should Lmod be unavailable and `$MODULEPATH` not used, you can initialise EESSI via an Lmod module by directly sourcing the Lmod initialisation script (this script automatically loads the EESSI module):

boegel · 2024-10-18T12:53:04Z

docs/using_eessi/setting_up_environment.md

+3.  Should Lmod be unavailable and `MODULEPATH` not utilized, you can initialise EESSI via an Lmod module by directly sourcing the Lmod initialisation script (this script automatically loads the EESSI module):
+
+    ``` { .bash .copy }
+    source /cvmfs/software.eessi.io/versions/2023.06/init/lmod/bash


or use $SHELL instead of harcoding bash?

boegel · 2024-10-18T12:53:25Z

docs/using_eessi/setting_up_environment.md

+
+## Sourcing the EESSI `bash` initialisation script
+
+You can initialise EESSI (in a non-reversible way) by running the command:


how to check (echo $SHELL)

Update existing Doc on how to use EESSI

48e46e0

ocaisa reviewed Oct 8, 2024

View reviewed changes

docs/using_eessi/setting_up_environment.md Outdated Show resolved Hide resolved

Richard Top and others added 2 commits October 9, 2024 06:47

Update existing Doc on how to use EESSI

4e72953

Update setting_up_environment.md

069216f

trz42 requested changes Oct 16, 2024

View reviewed changes

TopRichard and others added 10 commits October 17, 2024 13:36

Update docs/using_eessi/setting_up_environment.md

49abc11

Co-authored-by: Thomas Röblitz <[email protected]>

Update docs/using_eessi/setting_up_environment.md

4dcbc25

Co-authored-by: Thomas Röblitz <[email protected]>

Update docs/using_eessi/setting_up_environment.md

0c0882d

Co-authored-by: Thomas Röblitz <[email protected]>

Update docs/using_eessi/setting_up_environment.md

56297c7

Co-authored-by: Thomas Röblitz <[email protected]>

Update docs/using_eessi/setting_up_environment.md

f5d6855

Co-authored-by: Thomas Röblitz <[email protected]>

Update docs/using_eessi/setting_up_environment.md

6bfca5d

Co-authored-by: Thomas Röblitz <[email protected]>

Update docs/using_eessi/setting_up_environment.md

0dd9a07

Co-authored-by: Thomas Röblitz <[email protected]>

Update docs/using_eessi/setting_up_environment.md

0b8bd58

Co-authored-by: Thomas Röblitz <[email protected]>

Update docs/using_eessi/setting_up_environment.md

d458ab9

Co-authored-by: Thomas Röblitz <[email protected]>

Update docs/using_eessi/setting_up_environment.md

5c251d5

Co-authored-by: Thomas Röblitz <[email protected]>

ocaisa requested changes Oct 18, 2024

View reviewed changes

docs/using_eessi/setting_up_environment.md Outdated Show resolved Hide resolved

docs/using_eessi/setting_up_environment.md Outdated Show resolved Hide resolved

docs/using_eessi/setting_up_environment.md Show resolved Hide resolved

ocaisa reviewed Oct 18, 2024

View reviewed changes

TopRichard and others added 8 commits October 18, 2024 12:18

Update docs/using_eessi/setting_up_environment.md

76d87b1

Co-authored-by: ocaisa <[email protected]>

Update docs/using_eessi/setting_up_environment.md

0f8e9e7

Co-authored-by: ocaisa <[email protected]>

Merge branch 'EESSI:main' into eessi-using-EESSI-as-module

1dff95b

Update setting_up_environment.md

ee020c4

Update setting_up_environment.md

bf98d89

Update setting_up_environment.md

e5f4cad

Update setting_up_environment.md

554590e

Update setting_up_environment.md

5d9d30b

boegel requested changes Oct 18, 2024

View reviewed changes

Update setting_up_environment.md

b726a4f

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update existing Doc on how to use EESSI #317

Update existing Doc on how to use EESSI #317

TopRichard commented Oct 8, 2024 •

edited

Loading

trz42 left a comment

ocaisa commented Oct 16, 2024

trz42 commented Oct 17, 2024

ocaisa commented Oct 17, 2024 •

edited

Loading

ocaisa left a comment

ocaisa Oct 18, 2024

ocaisa Oct 18, 2024

boegel Oct 18, 2024

ocaisa Oct 18, 2024

boegel Oct 18, 2024

ocaisa Oct 18, 2024

ocaisa Oct 18, 2024

ocaisa Oct 18, 2024 •

edited

Loading

boegel Oct 18, 2024

boegel Oct 18, 2024

boegel Oct 18, 2024

boegel Oct 18, 2024

boegel Oct 18, 2024

boegel Oct 18, 2024

boegel Oct 18, 2024

boegel Oct 18, 2024

boegel Oct 18, 2024

boegel Oct 18, 2024

boegel Oct 18, 2024


		:clap: Your environment is now set up, you are ready to start running software provided by EESSI!

		3. Should Lmod be unavailable and `MODULEPATH` not utilized, you can initialise EESSI via an Lmod module by directly sourcing the Lmod initialisation script (this script automatically loads the EESSI module):


		## Sourcing the EESSI `bash` initialisation script

		You can initialise EESSI (in a non-reversible way) by running the command:


		!!! note "Why do we recommend to unset `MODULEPATH`?"

		Unsetting MODULEPATH may not be possible at some sites, and some compromise or workaround may

	Unsetting MODULEPATH may not be possible at some sites, and some compromise or workaround may
	Unsetting the `$MODULEPATH` environment variable, which tells Lmod in which directories environment module files are available, may not be possible at some sites, and some compromise or workaround may


		1. You are already using Lmod with version >= 8.6

		In this case, we _recommend_ unsetting the `MODULEPATH`, because EESSI is not designed to mix modules coming from EESSI and from your system.

		unset MODULEPATH
		export MODULEPATH=/cvmfs/software.eessi.io/init/modules


		2. You are using an Lmod with a version older than 8.6 or any other tool utilizing `MODULEPATH` (Tmod, etc.)

		You should unset MODULEPATH to prevent Lmod from attempting to build a cache for your module tree (as this can be very slow if you have

	You should unset MODULEPATH to prevent Lmod from attempting to build a cache for your module tree (as this can be very slow if you have
	You should unset `$MODULEPATH` to prevent Lmod from attempting to build a cache for your module tree (as this can be very slow if you have

	a lot of modules). Again, unsetting the MODULEPATH should be considered as a good idea in general so you do not mix local and EESSI
	a lot of modules). Again, unsetting the `$MODULEPATH` should be considered as a good idea in general so you do not mix local and EESSI

Update existing Doc on how to use EESSI #317

Are you sure you want to change the base?

Update existing Doc on how to use EESSI #317

Conversation

TopRichard commented Oct 8, 2024 • edited Loading

trz42 left a comment

Choose a reason for hiding this comment

ocaisa commented Oct 16, 2024

trz42 commented Oct 17, 2024

ocaisa commented Oct 17, 2024 • edited Loading

ocaisa left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ocaisa Oct 18, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TopRichard commented Oct 8, 2024 •

edited

Loading

ocaisa commented Oct 17, 2024 •

edited

Loading

ocaisa Oct 18, 2024 •

edited

Loading