From e072167ce3ad7a2efe40c7e2dfdcd7d5bfe301a9 Mon Sep 17 00:00:00 2001 From: Xavier Delaruelle Date: Tue, 22 Aug 2023 22:04:24 +0200 Subject: [PATCH] doc: modernize modulefile code examples Modernize and simplify modulefile code examples in documentation: * Follow coding convention defined for the project * Use simple "#%Module" file signature, no "1.0" suffix needed --- .../tips-for-code-reuse/bar/1.0/nothreads | 2 +- .../tips-for-code-reuse/bar/1.0/openmp | 2 +- .../tips-for-code-reuse/bar/1.0/pthreads | 2 +- .../tips-for-code-reuse/bar/2.0/nothreads | 2 +- .../tips-for-code-reuse/bar/2.0/openmp | 2 +- .../tips-for-code-reuse/bar/2.0/pthreads | 2 +- doc/example/tips-for-code-reuse/foo/1.0 | 2 +- doc/example/tips-for-code-reuse/foo/2.0 | 2 +- doc/example/tips-for-code-reuse/fooA/1.0 | 2 +- doc/example/tips-for-code-reuse/fooA/2.0 | 2 +- doc/source/FAQ.rst | 15 ++++----- doc/source/cookbook/tips-for-code-reuse.rst | 6 ++-- doc/source/modulefile.rst | 31 +++++++------------ 13 files changed, 31 insertions(+), 41 deletions(-) diff --git a/doc/example/tips-for-code-reuse/bar/1.0/nothreads b/doc/example/tips-for-code-reuse/bar/1.0/nothreads index 664ec5ab..c0c7601f 100644 --- a/doc/example/tips-for-code-reuse/bar/1.0/nothreads +++ b/doc/example/tips-for-code-reuse/bar/1.0/nothreads @@ -1,4 +1,4 @@ -#%Module1.0 +#%Module set version 1.0 set threadingmodel nothreads diff --git a/doc/example/tips-for-code-reuse/bar/1.0/openmp b/doc/example/tips-for-code-reuse/bar/1.0/openmp index c7f9296d..c2342a7c 100644 --- a/doc/example/tips-for-code-reuse/bar/1.0/openmp +++ b/doc/example/tips-for-code-reuse/bar/1.0/openmp @@ -1,4 +1,4 @@ -#%Module1.0 +#%Module set version 1.0 set threadingmodel openmp diff --git a/doc/example/tips-for-code-reuse/bar/1.0/pthreads b/doc/example/tips-for-code-reuse/bar/1.0/pthreads index 1f6c9ab7..3ff16dc3 100644 --- a/doc/example/tips-for-code-reuse/bar/1.0/pthreads +++ b/doc/example/tips-for-code-reuse/bar/1.0/pthreads @@ -1,4 +1,4 @@ -#%Module1.0 +#%Module set version 1.0 set threadingmodel pthreads diff --git a/doc/example/tips-for-code-reuse/bar/2.0/nothreads b/doc/example/tips-for-code-reuse/bar/2.0/nothreads index 00bebf15..b2110def 100644 --- a/doc/example/tips-for-code-reuse/bar/2.0/nothreads +++ b/doc/example/tips-for-code-reuse/bar/2.0/nothreads @@ -1,4 +1,4 @@ -#%Module1.0 +#%Module set version 2.0 set threadingmodel nothreads diff --git a/doc/example/tips-for-code-reuse/bar/2.0/openmp b/doc/example/tips-for-code-reuse/bar/2.0/openmp index 6f1558cd..1ea80f70 100644 --- a/doc/example/tips-for-code-reuse/bar/2.0/openmp +++ b/doc/example/tips-for-code-reuse/bar/2.0/openmp @@ -1,4 +1,4 @@ -#%Module1.0 +#%Module set version 2.0 set threadingmodel openmp diff --git a/doc/example/tips-for-code-reuse/bar/2.0/pthreads b/doc/example/tips-for-code-reuse/bar/2.0/pthreads index 98f9741a..0ad46dcf 100644 --- a/doc/example/tips-for-code-reuse/bar/2.0/pthreads +++ b/doc/example/tips-for-code-reuse/bar/2.0/pthreads @@ -1,4 +1,4 @@ -#%Module1.0 +#%Module set version 2.0 set threadingmodel pthreads diff --git a/doc/example/tips-for-code-reuse/foo/1.0 b/doc/example/tips-for-code-reuse/foo/1.0 index 974f66a4..752bea06 100644 --- a/doc/example/tips-for-code-reuse/foo/1.0 +++ b/doc/example/tips-for-code-reuse/foo/1.0 @@ -1,4 +1,4 @@ -#%Module1.0 +#%Module ## ## foo diff --git a/doc/example/tips-for-code-reuse/foo/2.0 b/doc/example/tips-for-code-reuse/foo/2.0 index 42161ac2..e5b3a3a0 100644 --- a/doc/example/tips-for-code-reuse/foo/2.0 +++ b/doc/example/tips-for-code-reuse/foo/2.0 @@ -1,4 +1,4 @@ -#%Module1.0 +#%Module ## ## foo diff --git a/doc/example/tips-for-code-reuse/fooA/1.0 b/doc/example/tips-for-code-reuse/fooA/1.0 index fba99691..7efdf0ff 100644 --- a/doc/example/tips-for-code-reuse/fooA/1.0 +++ b/doc/example/tips-for-code-reuse/fooA/1.0 @@ -1,4 +1,4 @@ -#%Module1.0 +#%Module set version 1.0 set moduledir [file dirname $ModulesCurrentModulefile] diff --git a/doc/example/tips-for-code-reuse/fooA/2.0 b/doc/example/tips-for-code-reuse/fooA/2.0 index 3c943204..f772c1a9 100644 --- a/doc/example/tips-for-code-reuse/fooA/2.0 +++ b/doc/example/tips-for-code-reuse/fooA/2.0 @@ -1,4 +1,4 @@ -#%Module1.0 +#%Module set version 2.0 set moduledir [file dirname $ModulesCurrentModulefile] diff --git a/doc/source/FAQ.rst b/doc/source/FAQ.rst index 67778437..c702c0f7 100644 --- a/doc/source/FAQ.rst +++ b/doc/source/FAQ.rst @@ -15,8 +15,8 @@ sh: .. code-block:: sh - module () - { + module () + { eval "$(/some/path/modulecmd sh "$@")" } @@ -69,7 +69,7 @@ csh: (overwrite existing file) How to use the module command from Makefile? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To make use of the ``module`` command from a Makefile, the shell initialization script should first be sourced within Makefile rule to define the ``module`` function in that context. Environment variable ``MODULESHOME`` may help to locate the shell initialization script in a generic way, like done in the following example: +To make use of the ``module`` command from a Makefile, the shell initialization script should first be sourced within Makefile rule to define the ``module`` function in that context. Environment variable ``MODULESHOME`` may help to locate the shell initialization script in a generic way, like done in the following example: .. code-block:: Makefile @@ -130,15 +130,12 @@ import the environment changes performed by a shell script within a How do I specify the *default* modulefile for some modulefile directory? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Modules usually uses the the highest lexicographically sorted :ref:`modulefile(4)` under the directory, unless there is a ``.version`` file in that directory which has a format like the following where "native" is a modulefile (or a sub-directory) in that directory. It's also possible to set the default with a ``.modulerc`` file with a **module-version** command. +Modules usually uses the the highest lexicographically sorted :ref:`modulefile(4)` under the directory, unless there is a ``.version`` file in that directory which has a format like the following where ``native`` is a modulefile (or a sub-directory) in that directory. It's also possible to set the default with a ``.modulerc`` file with a **module-version** command. .. code-block:: tcl - #%Module1.0##################################################################### - ## - ## version file for Perl - ## - set ModulesVersion "native" + #%Module + set ModulesVersion native I don't want a *default* modulefile for the directory? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/source/cookbook/tips-for-code-reuse.rst b/doc/source/cookbook/tips-for-code-reuse.rst index cad79baf..238abc54 100644 --- a/doc/source/cookbook/tips-for-code-reuse.rst +++ b/doc/source/cookbook/tips-for-code-reuse.rst @@ -76,9 +76,9 @@ variable "version" passed to it by the stub file. It also handles defining the help procedure and the whatis text, and the conflict with itself. Note that the "common" file does **NOT** start -with the Modules magic "#%Module1.0"; this will keep "common" from showing +with the Modules magic "#%Module"; this will keep "common" from showing up in "module avail fooA". The "1.0" and "2.0" files do need to start with -the magic "#%Module1.0" tag so the module command will "see" them. Because +the magic "#%Module" tag so the module command will "see" them. Because of this, the "module avail fooA" command will just show the 1.0 and 2.0 versions as expected. @@ -121,7 +121,7 @@ defaults the version (e.g. if the user types "module load fooB" without specifying the version of fooB.) The common file also handles defining the help procedure and whatis text. When the command "module avail fooB" is issued, the common file does not get listed (because it does not start with the magic -"#%Module1.0" tag), nor does the .generic file get listed (because it starts +"#%Module" tag), nor does the .generic file get listed (because it starts with a period (".")), but the two 1.0 and 2.0 symlinks do get listed, just as one wants. diff --git a/doc/source/modulefile.rst b/doc/source/modulefile.rst index a9025b3c..b1275f4d 100644 --- a/doc/source/modulefile.rst +++ b/doc/source/modulefile.rst @@ -114,22 +114,22 @@ the *modulefile* is being loaded. An example: Suppose that a full selection of *modulefiles* are needed for various different architectures, but some of the *modulefiles* are not needed and the user should be alerted. Having the unnecessary *modulefile* - be a link to the following notavail *modulefile* will perform the task + be a link to the following ``notavail`` *modulefile* will perform the task as required. .. code-block:: tcl - #%Module1.0 - ## notavail modulefile - ## - proc ModulesHelp { } { - puts stderr "This module does nothing but alert the user" + #%Module + + proc ModulesHelp {} { + puts stderr {This module does nothing but alert the user} puts stderr "that the [module-info name] module is not available" } - module-whatis "Notifies user that module is not available." + module-whatis {Notifies user that module is not available.} + set curMod [module-info name] - if { [ module-info mode load ] } { + if {[module-info mode load]} { puts stderr "Note: '$curMod' is not available for [uname sysname]." } break @@ -1487,21 +1487,15 @@ be loaded. Such a file would look like: .. code-block:: tcl - #%Module1.0 - ## - ## The desired version of X11 - ## - set ModulesVersion "R4" + #%Module + set ModulesVersion R4 The equivalent :file:`.modulerc` would look like: .. code-block:: tcl - #%Module1.0 - ## - ## The desired version of X11 - ## - module-version "./R4" default + #%Module + module-version ./R4 default If the extended default mechanism is enabled (see :envvar:`MODULES_EXTENDED_DEFAULT` in :ref:`module(1)`) the module version @@ -1963,4 +1957,3 @@ Tcl was developed by John Ousterhout at the University of California at Berkeley. TclX was developed by Karl Lehenbauer and Mark Diekhans. -