Modules

Linux computers on the FI network use a module system to manage the software installed on them. Thanks to it

the same software can be used across faculty Linux machines,
different versions of the same software can run side by side,
students and faculty can install and make available to others any software they wish (as long as its license allows it, of course).

A module is a set of software that logically belongs together. For example, the module ghccontains, in addition to the compiler ghc, the interpreter ghci, the documentation generator haddock, and the packaging tool cabal.

Using

Most of the work with modules is mediated by module, which has several commands. The most important is add for connecting modules - programs in a module are not easily accessible until the module is connected.

Connecting a module:
```
  $ module add ‹name›
```

List the available modules:

  $ module avail
  -------- /packages/run/modules-3.1.6/modulefiles --------
  binhex         gnuplot        modules        tcl-tk
  devel          info-services  plan           texlive
  eclipse        maple          snns           viewers

List of currently connected modules:
```
  $ module list
  Currently Loaded Modulefiles:
          1) modules
```
The modules module must always be present; if not, it needs to be added in the standard way: module add modules.

I want to add a module

Excellent! Follow these steps:

Is there no older version? Is there no distribution package?

If you want to create a new version of an existing module, it's a good idea to contact the maintainer of the current version first. This is the owner of the file /packages/run.64/modules/modulefiles/‹pkg›-‹current version›.

It is also a good idea to check if the software (in a version sufficient for you) exists in a distribution package. If so, just write to unixXnxrCmdz7@fi8sb2tAxs3.muni8-=vPnDZO.cz, and if there is no problem, we will install it.
Create a module using the application in the Faculty Administration.

Enter the name and version of the software package. Hereafter we will refer to them as ‹pkg›and ‹version›.

When created, an empty module skeleton will be created:
- /packages/run.64/‹pkg›-‹version›/ (this is where it will be installed)
- /packages/run.64/modules/modulefiles/‹pkg›-version› (module configuration)
(Actually, there is more; we refer interested parties to the advanced section below.)
Install the software into /packages/run.64/‹pkg›-‹version›/.

This varies by software; typically it involves setting a prefix when configuring, building and/or installing to this directory. Look for the option --prefix, CMAKE_INSTALL_PREFIX, etc.

Perform the installation on one of the following computers:

aisa, anxur, aura, nymfe01,

where you plan to use the module (otherwise you may run into problems with e.g. system library versions). If it is not a GUI program, it is safer to install it on Aisa or Aura - the program will then usually be able to run on graphical stations. In particular, if you compile with the gcc or llvm module, binaries compiled on Aisa will probably run on Nymphs, but definitely not the other way around.
Set up the module with the file /packages/run.64/modules/modulefiles/‹pkg›-‹version›.

You will need to find out exactly where the executables are installed and add that path to the environment variable PATH in the configuration file. It is also a good idea to make the manual pages available.

Here is a short example from the module ghc-8.10.2:
```
 #%Module1.0
 #!
 #! Title: ghc
 #! Version: 8.10.2
 #! Description: The Glasgow Haskell Compiler

 prepend-path PATH     /packages/run.64/ghc-8.10.2/bin
 prepend-path MANPATH  /packages/run.64/ghc-8.10.2/share/man
```
Similarly, you may need to set up LD_LIBRARY_PATH or other environment variables. Here you can also set module dependencies on other modules or conflicts with other modules. See the separate section below and man 4 modulefile for details.
Test the functionality.
```
 $ module add ‹pkg›-‹version›
```
And verify that everything works as it should.
Contact us regarding the default version.

All modules must have a version number listed. A package name without a version is just a shortcut for some default version. If you want your module to be connected with a shorter command
```
 $ module add ‹pkg›
```
you need to mark your module version as default. You cannot do this yourself, but you can email us at unixB7iMxeuSQ@fiN=FfWY0zm.muniCxlD8rBSY.cz.

More advanced module configuration

In addition to prepend-path VARIABLE VALUE, a module can change environment variables in other ways:

prepend-path VARIABLE VALUE - adding a value and a colon to the beginning
append-path VARIABLE VALUE - adding a colon and a value at the end
setenv VARIABLE VALUE - overwriting a variable with a value
unsetenv VARIABLE VALUE - deleting a variable

It is also possible to set up dependencies and conflicting modules. If your module needs to use other modules, always make this explicit in the configuration. Otherwise, over time, we may evaluate a needed module as unused and delete it.

conflict MODULE [MODULE ...]
prereq   MODULE [MODULE ...]

Finally, you can directly connect modules or perform other operations with the module command.

module   COMMAND [ARGUMENT]

If you need to write some short help for a module, you can write it in the file /packages/run/modules/helpfiles/‹pkg›-‹version›. It will then be viewable with the command modulehelp ‹pkg›-‹version›.

For more information, see the manual pages module(1) and modulefile(4).

How does it all work?

The modules are available on all Linux machines in the directory /packages. In addition to the subdirectory run.64, there is run with the old 32-bit modules. Another subdirectory that may be of interest is share, where platform-independent files are placed (i.e. what is usually in /usr/share). The idea is that the directory /packages/run.64 is shared between machines with the same platform, and /packages/share is shared between all machines.

Since Linux-amd64 is currently the only platform endowed with modules on FI , there is no need to use share and you can put the entire installation in run.64 (where only binaries, libraries, etc. would fall in a multi-platform design).

From the description of the installation, it's probably obvious that the whole magic of adding modules is actually just adding paths to PATH (or other variables).

For this to work, the module command must be a shell function, not an executable program. (This function does not appear in the shell by itself; it is introduced by the /etc/profile.d/modules.sh file.) As a result, while you can use the modulecommand in shell scripts (typically, e.g., ~/.bashrc), you cannot use it in other programs. On the other hand, nothing prevents you from accessing the binaries directly via the absolute path /packages/run.64/‹pkg›-‹version›/.... However, this carries a risk in long term use. Unlike module add, we can only detect this usage on servers (Aisa, Anxur, Aura), not on stations (Nymfe, Musa). Modules used only on stations should therefore always be added via module add, so that we don't evaluate them as unused and remove them over time. The same applies to modules with libraries, etc. - for now we only detect binary execution.

The existence of a module is "caused" by the existence of a correctly formatted configuration file in /packages/run.64/modules/modulefiles/. Thus the default version of the module (the one without an explicit version number) also has its configuration file in the modulefiles directory - but in fact it is just a symbolic link to the file of the specific version. Thus, the default versions of modules can be found by using the readlink command (or even by listing the modulefiles directory using ls -l).

Local modules on student stations

On the Nymfe and Musa stations, you may also encounter modules ending in -loc. These are the same modules as their non- -loc versions, only they are located on the local disk of the Nymfe stations. Local modules are only created by unix@fi for bulky modules, both to speed them up and to limit network traffic.