7. TUTORIALS

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

This is for Pmodules 2.0 or newer!

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

  1. 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

  2. Unpack the stub into the directory hello_world

    mkdir hello_world && cd $_
tar --strip-components 1 -xvf ../stub.tgz
chmod 0755 build

  3. 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)
    1 The name of the module.
    2 Default configuration for all version. This can be overwritten in the 'versions' section.
    3 The group the module will be installed in.
    4 If not otherwise specified in the version specific configuration, the release stage is set to stable.
    5 Usually the software is compiled in a dedicated build directory. Here we have to compile in the source tree.
    6 Download URL and filename. $P will be substituted by the module name and $V by the version.
    7 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.
    8 Configuration for version 1.0.0.
    9 Overwrite the default release stage.

  4. 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.

  5. Build the module

    ./build 1.0.0

  6. 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 the build-script must be called again: ./build 1.0.0

7.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.

  1. 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:
        compile_in_sourcetree: true    (1)
        build_functions:               (2)
          prep: [pbuild::prep]
          configure: []
          compile: [pbuild::compile]
          install: [install-1]
    2.0.0:                             (3)
      config:
        relstage: unstable
    1 With autotools the software can be compiled outside the sources. This is recommended and the default for autotools and CMake. Therefore this configuration has been moved from the default section to the version specific section.
    2 Now that an Autotool configuration is available, the build functions for version 1 and version 2 differ. While for version 2 the default function can (and should) be used, a special function is required for the installation of version 1 and there is no configuration.
    3 Configuration for version 2.0.0.

  2. Edit ./build

    #!/usr/bin/env modbuild

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

# we need this function major version 1!
install-1() {
        mkdir -p "${PREFIX}/bin"
        install --mode=0755 "${SRC_DIR}/hello" "${PREFIX}/bin"
}
    1 This function is called before pbuild::configure(). Since the tar file only contains a configure.ac and no configure script, the latter must be generated. In most cases, this function is not needed.

  3. Build version 2.0.0

    ./build 2.0.0

7.3. Deprecate old version, make current version stable

  1. 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:
        compile_in_sourcetree: true
        relstage: deprecated         (1)
        build_functions:
          prep: [pbuild::prep]
          configure: []
          compile: [pbuild::compile]
          install: [install-1]
    2.0.0:                          (2)
    1 Set release stage of version 1.0.0 to 'deprecated'.
    2 The config section for version 2.0.0 has been removed. Therefor the defaults are used.

  2. Change release stages

    ./build 1.0.0
./build 2.0.0