Pmodules - an improved environment modules system

3. TUTORIALS

3.1. Step-by-step guide to build a 'Hello, world!' module

Download a stub for a new build-block

wget --output-document=stub.tgz https://github.com/Pmodules/buildblock_stub/archive/refs/tags/1.0.0.tar.gz

Unpack the stub into the directory hello_world
```
mkdir hello_world && cd $_
tar --strip-components 1 -xvf ../stub.tgz
chmod 0755 build
```
After un-taring the following files are in the current directory:

files/config.yaml                   (1)
build                               (2)
modulefile                          (3)
LICENSE                             (4)

1	configuration file for the module `hello_world`
2	build-script
3	modulefile
4	license of the module Edit `files/config.yaml` `--- format: 1 hello_world: (1) defaults: (2) group: Tools (3) relstage: stable (4) compile_in_sourcetree: true (5) urls: (6) - url: https://github.com/Pmodules/$P/archive/refs/tags/$V.tar.gz name: $P-$V.tar.gz shasums: (7) hello_world-1.0.0.tar.gz: bc1cfd90ac55e9f3babab0a426ed4b3c7edf15266363ab1b595d234797fbce7b versions: 1.0.0: config: (8) relstage: unstable (9)`
5	The name of the module.
6	Default configuration for all version. This can be overwritten in the 'versions' section.
7	The group the module will be installed in.
8	If not otherwise specified in the version specific configuration, the release stage is set to `stable`.
9	Usually the software is compiled in a dedicated build directory. Here we have to compile in the source tree.
10	Download URL and filename. `$P` will be substituted by the module name and `$V` by the version.
11	SHA256 hash sums for each source file. Hash sums are optional but recommended. Therefor you can start without the hash sum and add it later. If the hash sum is missing, you get a warning. If the hash sum is wrong, the build process aborts.
12	Configuration for version 1.0.0.
13	Overwrite the default release stage.

For linting YAML files use the tool yamlint or an on-line linter like yaml-validator.

Edit the build script
```
#!/usr/bin/env modbuild

pbuild::configure() {    (1)
	:
}

pbuild::install() {      (2)
	mkdir -p "${PREFIX}/bin"
	install --mode=0755 "${SRC_DIR}/hello" "${PREFIX}/bin"
}
```
1 Don’t use the default pbuild::configure() function! There is nothing to configure. :)

2 The Makefile doesn’t have an 'install' target. Therefore we have to code it ourself.
Build the module
```
./build 1.0.0
```

Release module as 'stable'

Remove the line relstage: unstable in the config section of version 1.0.0:

---
format: 1
hello_world:
  defaults:
    group: Tools
    relstage: stable
    compile_in_sourcetree: true
    urls:
      - url: https://github.com/Pmodules/$P/archive/refs/tags/$V.tar.gz
        name: $P-$V.tar.gz

  shasums:
    hello_world-1.0.0.tar.gz: bc1cfd90ac55e9f3babab0a426ed4b3c7edf15266363ab1b595d234797fbce7b

  versions:
    1.0.0:                   (1)

1	Since the `config` section is empty after removing the line `relstage: unstable` the entire section can be removed.

To change the release stage run the build-script again: ./build 1.0.0

3.2. Add new version, build with autotools

In version 2.0.0 the author added autotools files. Let’s add this version to our build-block.

Edit files/config.yaml

---
format: 1
hello_world:
  defaults:
    group: Tools
    relstage: stable
    urls:
      - url: https://github.com/Pmodules/$P/archive/refs/tags/$V.tar.gz
        name: $P-$V.tar.gz

  shasums:
    hello_world-1.0.0.tar.gz: bc1cfd90ac55e9f3babab0a426ed4b3c7edf15266363ab1b595d234797fbce7b
    hello_world-2.0.0.tar.gz: cd4ef1a7581fd4306f9b045b4bb9d722e1a978be3f93c709e0e8436347e38cf4

  versions:
    1.0.0:
      config:                          (1)
        compile_in_sourcetree: true
        build_functions:
          prep: [pbuild::prep]
          configure: []
          compile: [pbuild::compile]
          install: [install-1]
    2.0.0:                             (2)
      config:
        relstage: unstable

1	Several changes are required in the config section: With autotools the software can be compiled outside the sources. This is recommended and the default for autotools and CMake. Define the build function for version 1.x: Nothing to configure for version 1.x. In version 2+ we can use the default installation function. For version 1, we need a separate version.
2	Configuration for version 2.0.0.

Edit ./build

#!/usr/bin/env modbuild

pbuild::pre_configure(){
        ./autogen.sh
}

# we need this function for major version 1!
install-1() {
        mkdir -p "${PREFIX}/bin"
        install --mode=0755 "${SRC_DIR}/hello" "${PREFIX}/bin"
}

3.3. Deprecate old version, make current version stable

Edit files/config.yaml

---
format: 1
hello_world:
  defaults:
    group: Tools
    relstage: stable
    urls:
      - url: https://github.com/Pmodules/$P/archive/refs/tags/$V.tar.gz
        name: $P-$V.tar.gz

  shasums:
    hello_world-1.0.0.tar.gz: bc1cfd90ac55e9f3babab0a426ed4b3c7edf15266363ab1b595d234797fbce7b
    hello_world-2.0.0.tar.gz: cd4ef1a7581fd4306f9b045b4bb9d722e1a978be3f93c709e0e8436347e38cf4

  versions:
    1.0.0:
      config:                          (1)
        compile_in_sourcetree: true
        relstage: deprecated
        build_functions:
          prep: [pbuild::prep]
          configure: []
          compile: [pbuild::compile]
          install: [install-1]
    2.0.0:                             (2)

1	Don’t use the default `pbuild::configure()` function! There is nothing to configure. :)
2	The Makefile doesn’t have an 'install' target. Therefore we have to code it ourself.