Debian Codegraph @

doc/source/envml.rst

raw
1 .. _envml(1):
2
3 envml
4 =====
5
6 SYNOPSIS
7 --------
8
9 **envml** [*MODULE_ACTION*]... [--] *COMMAND* [*ARG*]...
10
11 DESCRIPTION
12 -----------
13
14 The :command:`envml` command configures the environment using specified
15 Environment Modules actions and then given command.
16
17 This is useful for running a command in a modified environment without
18 permanently altering the current shell session.
19
20 :command:`envml` interprets its first arguments as module actions, then
21 switches to command execution after either encountering ``--`` or determining
22 that the remaining arguments form the actual command to run.
23
24 MODULE_ACTION FORMAT
25 --------------------
26
27 Each module action argument can be one of the following forms:
28
29 - ``purge``
30 Unload all currently loaded modulefiles.
31
32 - ``restore[=coll]``
33 Restore the module environment from the named collection ``coll``. If no
34 name is given, restores the default collection.
35
36 - ``unload=mod1[&mod2...]``
37 Unload one or more specified modulefiles.
38
39 - ``switch=mod1&mod2``
40 Unload ``mod1`` and load ``mod2``.
41
42 - ``[load=]mod1[&mod2...]``
43 Load one or more specified modulefiles. ``load=`` can be omitted.
44
45 Multiple MODULE_ACTIONs can be passed in a single argument using the colon
46 (``:``) separator. The ampersand (``&``) is used to specify multiple modules
47 in a single action.
48
49 COMMAND EXECUTION
50 -----------------
51
52 Everything following the ``--`` separator is treated as the command to execute
53 in the modified environment.
54
55 If no ``--`` separator is provided, :command:`envml` assumes the first
56 argument is a MODULE_ACTION and the remaining arguments form the command to
57 execute.
58
59 OPTIONS
60 -------
61
62 .. option:: --help, -h
63
64 Display usage information and exit.
65
66 EXAMPLES
67 --------
68
69 Restore default module collection then run ``command arg1 arg2``:
70
71 .. code-block:: sh
72
73 envml restore command arg1 arg2
74
75 Purge all modules, then load ``mod1`` and ``mod2``, and run the command:
76
77 .. code-block:: sh
78
79 envml purge:mod1:mod2 command arg1 arg2
80
81 Use the ``--`` separator to avoid ambiguity:
82
83 .. code-block:: sh
84
85 envml restore load=mod1&mod2 -- command arg1 arg2
86
87 EXIT STATUS
88 -----------
89
90 The :command:`envml` command returns the exit status of the executed command
91 or ``1`` if module action fails.
92
93 DIAGNOSTICS
94 -----------
95
96 If the :command:`module` command is not available in the shell (i.e., not a
97 shell function), :command:`envml` will print an error and exit.
98
99 SEE ALSO
100 --------
101
102 :ref:`module(1)`, :ref:`modulecmd(1)`, :ref:`ml(1)`, :ref:`modulefile(5)`