| 1 |
# <img src="https://raw.githubusercontent.com/envmodules/modules/main/share/logo/modules_logo_text.svg" height="180" alt="Modules"/> |
| 2 |
|
| 3 |
[](https://github.com/envmodules/modules/actions?query=workflow:linux-tests) |
| 4 |
[](https://github.com/envmodules/modules/actions?query=workflow:windows-tests) |
| 5 |
[](https://cirrus-ci.com/github/envmodules/modules) |
| 6 |
[](https://codecov.io/gh/envmodules/modules) |
| 7 |
[](https://modules.readthedocs.io/en/latest/?badge=latest) |
| 8 |
[](https://repology.org/metapackage/environment-modules/versions) |
| 9 |
[](https://bsky.app/profile/envmodules.bsky.social) |
| 10 |
[](https://matrix.to/#/#modules:matrix.org) |
| 11 |
|
| 12 |
Modules, provides dynamic modification of a user's environment |
| 13 |
============================================================== |
| 14 |
|
| 15 |
The Modules package is a tool that simplify shell initialization and |
| 16 |
lets users easily modify their environment during the session with |
| 17 |
modulefiles. |
| 18 |
|
| 19 |
Each modulefile contains the information needed to configure the shell for |
| 20 |
an application. Once the Modules package is initialized, the environment can |
| 21 |
be modified on a per-module basis using the module command which interprets |
| 22 |
modulefiles. Typically modulefiles instruct the module command to alter or |
| 23 |
set shell environment variables such as PATH, MANPATH, etc. modulefiles may |
| 24 |
be shared by many users on a system and users may have their own collection |
| 25 |
to supplement or replace the shared modulefiles. |
| 26 |
|
| 27 |
Modules can be loaded and unloaded dynamically and atomically, in an clean |
| 28 |
fashion. All popular shells are supported, including bash, ksh, zsh, sh, |
| 29 |
csh, tcsh, fish, cmd, pwsh, as well as some scripting languages such as tcl, |
| 30 |
perl, python, ruby, cmake and r. |
| 31 |
|
| 32 |
Modules are useful in managing different versions of applications. Modules |
| 33 |
can also be bundled into meta-modules that will load an entire suite of |
| 34 |
different applications. |
| 35 |
|
| 36 |
|
| 37 |
Quick examples |
| 38 |
-------------- |
| 39 |
|
| 40 |
Here is an example of loading a module on a Linux machine under bash. |
| 41 |
|
| 42 |
$ module load gcc/12.4.0 |
| 43 |
$ which gcc |
| 44 |
$ /usr/local/gcc/12.4.0/linux-x86_64/bin/gcc |
| 45 |
|
| 46 |
Now we'll switch to a different version of the module |
| 47 |
|
| 48 |
$ module switch gcc/14 |
| 49 |
$ which gcc |
| 50 |
/usr/local/gcc/14.2.0/linux-x86_64/bin/gcc |
| 51 |
|
| 52 |
And now we'll unload the module altogether |
| 53 |
|
| 54 |
$ module unload gcc |
| 55 |
$ which gcc |
| 56 |
gcc not found |
| 57 |
|
| 58 |
Now we'll log into a different machine, using a different shell (tcsh). |
| 59 |
|
| 60 |
% module load gcc/14.2 |
| 61 |
% which gcc |
| 62 |
/usr/local/gcc/14.2.0/linux-aarch64/bin/gcc |
| 63 |
|
| 64 |
Note that the command line is exactly the same, but the path has |
| 65 |
automatically configured to the correct architecture. |
| 66 |
|
| 67 |
|
| 68 |
Getting things running |
| 69 |
---------------------- |
| 70 |
|
| 71 |
The simplest way to build and install Modules on a Unix system is: |
| 72 |
|
| 73 |
$ ./configure |
| 74 |
$ make |
| 75 |
$ make install |
| 76 |
|
| 77 |
To learn the details on how to install modules see [`INSTALL.txt`][1] for Unix |
| 78 |
system or [`INSTALL-win.txt`][2] for Windows. |
| 79 |
|
| 80 |
|
| 81 |
Requirements |
| 82 |
------------ |
| 83 |
|
| 84 |
* Tcl >= 8.5 |
| 85 |
|
| 86 |
|
| 87 |
Documentation |
| 88 |
------------- |
| 89 |
|
| 90 |
See [`MIGRATING`][3] to get an overlook of the new functionalities introduced |
| 91 |
by each released versions. [`NEWS`][4] provides the full list of changes added |
| 92 |
in each version. The [`Changes`][5] document gives an in-depth view of the |
| 93 |
modified behaviors and new features between major versions. You may also look |
| 94 |
at the `ChangeLog` for the technical development details. |
| 95 |
|
| 96 |
The `doc` directory contains both the paper and man pages describing the |
| 97 |
user's and the module writer's usage. To generate the documentation files, |
| 98 |
like the man pages (you need Sphinx >= 1.0 to build the documentation), just |
| 99 |
type: |
| 100 |
|
| 101 |
$ ./configure |
| 102 |
$ make -C doc all |
| 103 |
|
| 104 |
The following man pages are provided: |
| 105 |
|
| 106 |
module(1), ml(1), envml(1), modulefile(5) |
| 107 |
|
| 108 |
|
| 109 |
Test suite |
| 110 |
---------- |
| 111 |
|
| 112 |
Regression testing scripts are available in the `testsuite` directory (you |
| 113 |
need DejaGnu to run the test suite): |
| 114 |
|
| 115 |
$ ./configure |
| 116 |
$ make test |
| 117 |
|
| 118 |
Once modules is installed after running `make install`, you have the |
| 119 |
ability to test this installation with: |
| 120 |
|
| 121 |
$ make testinstall |
| 122 |
|
| 123 |
|
| 124 |
Links |
| 125 |
----- |
| 126 |
|
| 127 |
* Web site: https://envmodules.io |
| 128 |
* Online documentation: https://modules.readthedocs.io |
| 129 |
* GitHub source repository: https://github.com/envmodules/modules |
| 130 |
* GitHub Issue tracking system: https://github.com/envmodules/modules/issues |
| 131 |
|
| 132 |
|
| 133 |
Community |
| 134 |
--------- |
| 135 |
|
| 136 |
Modules is an open source project. Questions, discussion, and contributions |
| 137 |
are welcome. You can get in contact with the Modules community via: |
| 138 |
|
| 139 |
* the [modules-interest mailing list][6] |
| 140 |
(`[email protected]`) |
| 141 |
* the [Modules chat room][7] (`#modules:matrix.org`) |
| 142 |
|
| 143 |
The project is also present on several social media platforms: |
| 144 |
|
| 145 |
* X/Twitter: [@EnvModules][8] |
| 146 |
* Mastodon: [@[email protected]][9] |
| 147 |
* Bluesky: [@EnvModules.bsky.social][10] |
| 148 |
|
| 149 |
|
| 150 |
Contributing |
| 151 |
------------ |
| 152 |
|
| 153 |
Modules project welcomes contributions of all kinds! Before submitting an |
| 154 |
issue or pull request, please take a moment to review our [Contributing |
| 155 |
guide][11]. It includes important information about issue reporting, coding |
| 156 |
standards, etc. |
| 157 |
|
| 158 |
Please note that Modules project has a [Code of conduct][12]. It ensures a |
| 159 |
respectful and inclusive environment for all contributors. By participating in |
| 160 |
the Modules community, you agree to abide by its rules. |
| 161 |
|
| 162 |
|
| 163 |
Governance |
| 164 |
---------- |
| 165 |
|
| 166 |
Modules is part of the [High Performance Software Foundation](https://hpsf.io) |
| 167 |
within the [Linux Foundation](http://linuxfoundation.org). |
| 168 |
|
| 169 |
This project adheres to a [Technical charter][13], which defines its |
| 170 |
governance model, decision-making process, and long-term vision. |
| 171 |
|
| 172 |
|
| 173 |
License |
| 174 |
------- |
| 175 |
|
| 176 |
Modules is distributed under the GNU General Public License, either version 2 |
| 177 |
or (at your option) any later version (`GPL-2.0-or-later`). Read the file |
| 178 |
`COPYING.GPLv2` for details. |
| 179 |
|
| 180 |
|
| 181 |
Authors |
| 182 |
------- |
| 183 |
|
| 184 |
Modules current core developer and maintainer is Xavier Delaruelle, |
| 185 |
[email protected] |
| 186 |
|
| 187 |
Many thanks go to the [contributors][14] of the Modules project. |
| 188 |
|
| 189 |
|
| 190 |
Acknowledgments |
| 191 |
--------------- |
| 192 |
|
| 193 |
We would like to express our gratitude to [CEA][15] for the resources and |
| 194 |
funding provided to the project over the recent years. |
| 195 |
|
| 196 |
The following people have notably contributed to Modules and Modules would not |
| 197 |
be what it is without their contributions: |
| 198 |
|
| 199 |
* R.K. Owen |
| 200 |
* Kent Mein |
| 201 |
* Mark Lakata |
| 202 |
* Harlan Stenn |
| 203 |
* Leo Butler |
| 204 |
* Robert Minsk |
| 205 |
* Jens Hamisch |
| 206 |
* Peter W. Osel |
| 207 |
* John L. Furlan |
| 208 |
|
| 209 |
|
| 210 |
[1]: https://modules.readthedocs.io/en/stable/INSTALL.html |
| 211 |
[2]: https://modules.readthedocs.io/en/stable/INSTALL-win.html |
| 212 |
[3]: https://modules.readthedocs.io/en/stable/MIGRATING.html |
| 213 |
[4]: https://modules.readthedocs.io/en/stable/NEWS.html |
| 214 |
[5]: https://modules.readthedocs.io/en/stable/changes.html |
| 215 |
[6]: https://sourceforge.net/projects/modules/lists/modules-interest |
| 216 |
[7]: https://matrix.to/#/#modules:matrix.org |
| 217 |
[8]: https://x.com/EnvModules |
| 218 |
[9]: https://mast.hpc.social/@EnvModules |
| 219 |
[10]: https://bsky.app/profile/envmodules.bsky.social |
| 220 |
[11]: https://modules.readthedocs.io/en/latest/CONTRIBUTING.html |
| 221 |
[12]: CODE_OF_CONDUCT.md |
| 222 |
[13]: https://modules.readthedocs.io/en/latest/CHARTER.html |
| 223 |
[14]: https://github.com/envmodules/modules/graphs/contributors |
| 224 |
[15]: https://www.cea.fr/english |