Debian Codegraph @

doc/source/cookbook/modulefiles-in-git.rst

raw
1 .. _modulefiles-in-git:
2
3 Version control your Modulefiles using Git
4 ==========================================
5
6 The Modules concept is a great way to manage versions of tools on a
7 common server, but managing the Modulefiles themselves is error-prone
8 when not controlled using a SCM like `Git <https://git-scm.com/>`_.
9
10 Goals
11 -----
12
13 * To be able to create, edit, and test Modulefiles without the risk of
14 breaking other users.
15 * To be able to track changes to the system-wide Modulefiles using
16 Git.
17 * To enable testing of new tool versions (with their associated
18 Modulefiles) before making the new version generally available
19 (since the new Modulefile will not be public until pushed).
20
21 Assumptions
22 -----------
23
24 *Details are tweakable via TCL variables*
25
26 * You have Environment Modules version 4.1 or later installed on your
27 system, and Git version 2.4 or later.
28 * You have a Unix user named ``modules`` that exists only for managing
29 the Modulefiles, and controlling updates to them.
30 * The path ``/home/modules/modulefiles`` is in your ``modulerc`` file::
31
32 module use --append /home/modules/modulefiles
33
34 * Other Unix users (not named ``modules``) use the modules from
35 ``/home/modules/modulefiles``.
36
37
38 Principles of Operation
39 -----------------------
40
41 First we create a git repo for the Modulefiles.
42
43 Then we install a Modulefile named ``localmodules`` that, when loaded,
44 switches :envvar:`MODULEPATH` to a locally-created git clone of the
45 Modulefiles. When unloaded, it switches :envvar:`MODULEPATH` back to the
46 default.
47
48 After this, any time a user wants to edit the Modulefiles, they work in
49 their local git repo. After editing, testing, and committing to the local
50 git repo, ``git push`` updates the main repository, which (assuming the
51 user knows the password for user ``modules``) automatically updates
52 ``/home/modules/modulefiles``.
53
54
55 Implementation
56 --------------
57
58 .. literalinclude:: ../../example/modulefiles-in-git/modulefiles/localmodules
59 :caption: localmodules
60
61 Installation
62 ------------
63
64 First convert the existing Modulefiles into a git repo at
65 ``/home/modules/modulefiles``, as user ``modules``::
66
67 cd /home/modules/modulefiles
68 git init
69 git add .
70 git commit -m 'Initial checking of existing Modulefiles'
71 # Enable updates when receiving pushes:
72 git config --local receive.denyCurrentBranch updateInstead
73
74
75 Edit your global ``$MODULESHOME/init/modulerc`` file to use the new
76 env var ``MODULES_REPO`` instead of hard-coding the path (requires
77 Modules 4.1). Your modulerc should have::
78
79 setenv MODULES_REPO /home/modules/modulefiles
80 module use /\$MODULES_REPO
81
82 (The extra slash required before \$MODULES_REPO is a `bug
83 <https://github.com/envmodules/modules/issues/223>`_ to be fixed in
84 4.2.3.)
85
86 Copy the ``localmodules`` file from the Modules source tree to your
87 repo::
88
89 cd /home/modules/modulefiles
90 curl --output localmodules https://raw.githubusercontent.com/envmodules/modules/main/doc/example/modulefiles-in-git/modulefiles/localmodules
91
92 Edit paths in the top of ``localmodules``, if your installation
93 differs from the assumptions, then::
94
95 git add localmodules
96 git commit -m 'Add localmodules from github.com/envmodules/modules'
97
98 Usage example
99 -------------
100
101 As a regular user (i.e. anyone but user ``modules``)::
102
103 module load localmodules
104 cd $HOME/modulefiles
105
106 Edit, test, then::
107
108 git commit -am 'Make some edits'
109 git push
110 module unload localmodules
111
112 After a successful push and unload, it is safe to delete your local
113 ``$HOME/modulefiles`` directory if you wish.
114
115 .. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: