Debian Codegraph @

doc/source/index.rst

raw
1 .. Home page
2
3 Environment Modules
4 ===================
5
6 .. only:: html
7
8 .. image:: https://img.shields.io/github/stars/envmodules/modules
9 :target: https://github.com/envmodules/modules
10 :alt: GitHub Repository
11
12 .. image:: https://img.shields.io/github/license/envmodules/modules?color=lightsteelblue
13 :alt: GitHub License
14
15 .. image:: https://img.shields.io/github/v/release/envmodules/modules
16 :target: https://github.com/envmodules/modules/releases/latest
17 :alt: GitHub Release
18
19 .. image:: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpublic.api.bsky.app%2Fxrpc%2Fapp.bsky.actor.getProfile%2F%3Factor%3Denvmodules.bsky.social&query=%24.followersCount&style=social&logo=bluesky&label=%40EnvModules
20 :target: https://bsky.app/profile/envmodules.bsky.social
21 :alt: Bluesky
22
23 .. image:: https://img.shields.io/matrix/modules%3Amatrix.org?color=darkcyan
24 :target: https://matrix.to/#/#modules:matrix.org
25 :alt: Matrix
26
27 **Welcome to the Environment Modules documentation portal. The Environment
28 Modules package provides for the dynamic modification of a user's environment
29 via modulefiles.**
30
31 The Modules package is a tool that simplifies shell initialization and
32 lets users easily modify their environment during a session using
33 modulefiles.
34
35 Each modulefile contains the information needed to configure the shell for
36 an application. Once the Modules package is initialized, the environment
37 can be modified on a per-module basis using the :command:`module` command
38 which interprets modulefiles. Typically modulefiles instruct the
39 :command:`module` command to alter or set shell environment variables such as
40 :envvar:`PATH`, :envvar:`MANPATH`, etc. modulefiles may be shared by many
41 users on a system and users may have their own collection to supplement or
42 replace the shared modulefiles.
43
44 Modules can be **loaded** and **unloaded** dynamically and atomically,
45 in an clean fashion. All popular shells are supported, including *bash*,
46 *ksh*, *zsh*, *sh*, *csh*, *tcsh*, *fish*, *cmd*, *pwsh*, as well as some
47 languages such as *tcl*, *perl*, *python*, *ruby*, *cmake* and *r*.
48
49 Modules are useful in managing different versions of applications. Modules
50 can also be bundled into meta-modules that will load an entire suite of
51 different applications.
52
53 .. note:: Modules presented here are ones that modify the shell or script
54 execution environment. They should not be confused with language-specific
55 modules (e.g., Perl modules, Python modules or R modules) that add specific
56 capabilities to scripts.
57
58 Quick examples
59 ^^^^^^^^^^^^^^
60
61 Here is an example of loading a module on a Linux machine under bash.
62 ::
63
64 $ module load gcc/12.4.0
65 $ which gcc
66 $ /usr/local/gcc/12.4.0/linux-x86_64/bin/gcc
67
68 Now we'll switch to a different version of the module
69 ::
70
71 $ module switch gcc/14
72 $ which gcc
73 /usr/local/gcc/14.2.0/linux-x86_64/bin/gcc
74
75 And now we'll unload the module altogether
76 ::
77
78 $ module unload gcc
79 $ which gcc
80 gcc not found
81
82 Now we'll log into a different machine, using a different shell (tcsh).
83 ::
84
85 % module load gcc/14.2
86 % which gcc
87 /usr/local/gcc/14.2.0/linux-aarch64/bin/gcc
88
89 Note that the command line is exactly the same, but the path has
90 automatically configured to the correct architecture.
91
92 Get started with Modules
93 ^^^^^^^^^^^^^^^^^^^^^^^^
94
95 Learn how to retrieve and install Modules :ref:`on Unix<INSTALL>` or
96 :ref:`on Windows<INSTALL-win>`. An overlook on the new functionalities
97 introduced by each version is available in the :ref:`MIGRATING` guide.
98 :ref:`NEWS` provides the full list of changes added in each version. The
99 :ref:`changes` document gives an in-depth view of the modified behaviors and
100 new features between major versions.
101
102 Reference manual page for the :ref:`module(1)`, :ref:`ml(1)` and
103 :ref:`envml(1)` commands and for :ref:`modulefile(5)` script provide details
104 on all supported options.
105
106 A :ref:`cookbook` of recipes describes how to use the various features of
107 Modules and how to extend the :command:`module` command to achieve specific
108 needs.
109
110 Links
111 ^^^^^
112
113 * Web site: https://envmodules.io
114 * Documentation: https://modules.readthedocs.io
115 * Source repository: https://github.com/envmodules/modules
116 * Issue tracking system: https://github.com/envmodules/modules/issues
117 * Download releases: https://github.com/envmodules/modules/releases
118
119 .. _Community:
120
121 Community
122 ^^^^^^^^^
123
124 Modules is an open source project. Questions, discussion, and contributions
125 are welcome. You can get in contact with the Modules community via:
126
127 * the `modules-interest mailing list`_
128 (``[email protected]``)
129 * the `Modules chat room`_ (``#modules:matrix.org``)
130 * the :ref:`Technical Steering Committee meeting<tsc-meeting>`
131
132 The project is also present on several social media platforms:
133
134 * X/Twitter: `@EnvModules`_
135 * Mastodon: `@[email protected]`_
136 * Bluesky: `@EnvModules.bsky.social`_
137
138 .. _modules-interest mailing list: https://lists.hpsf.io/g/modules-interest
139 .. _Modules chat room: https://matrix.to/#/#modules:matrix.org
140 .. _@EnvModules: https://x.com/EnvModules
141 .. _@[email protected]: https://mast.hpc.social/@EnvModules
142 .. [email protected]: https://bsky.app/profile/envmodules.bsky.social
143
144 Contributing
145 ^^^^^^^^^^^^
146
147 Modules project welcomes contributions of all kinds! Before submitting an
148 issue or pull request, please take a moment to review our :ref:`Contributing
149 guide<CONTRIBUTING>`. It includes important information about issue reporting,
150 coding standards, etc.
151
152 Please note that Modules project has a `Code of conduct`_. It ensures a
153 respectful and inclusive environment for all contributors. By participating in
154 the Modules community, you agree to abide by its rules.
155
156 .. _Code of conduct: https://github.com/envmodules/modules?tab=coc-ov-file#readme
157
158 Governance
159 ^^^^^^^^^^
160
161 Modules is part of the `High Performance Software Foundation`_ within the
162 `Linux Foundation`_.
163
164 This project adheres to a :ref:`Technical charter<CHARTER>`, which defines its
165 governance model, decision-making process, and long-term vision.
166
167 .. _High Performance Software Foundation: https://hpsf.io
168 .. _Linux Foundation: http://linuxfoundation.org
169
170 License
171 ^^^^^^^
172
173 Modules is distributed under the GNU General Public License, either version 2
174 or (at your option) any later version (`GPL-2.0-or-later`).
175
176 .. only:: html
177
178 .. toctree::
179 :hidden:
180 :maxdepth: 2
181 :caption: Basics
182
183 INSTALL
184 INSTALL-win
185 MIGRATING
186 NEWS
187 user-guide
188 FAQ
189 changes
190 other-implementations
191
192 .. toctree::
193 :hidden:
194 :maxdepth: 2
195 :caption: Examples
196
197 cookbook
198
199 .. toctree::
200 :hidden:
201 :maxdepth: 2
202 :caption: Reference
203
204 ml
205 module
206 modulefile
207 modulecmd
208 envml
209
210 .. toctree::
211 :hidden:
212 :maxdepth: 2
213 :caption: Development
214
215 CONTRIBUTING
216 devel
217 design
218 CHARTER
219 GOVERNANCE
220 acknowledgments