Skip to content

Latest commit

 

History

History
132 lines (92 loc) · 3.93 KB

CONTRIBUTING.adoc

File metadata and controls

132 lines (92 loc) · 3.93 KB
Raw

Care and feeding of your initramfs generator

This guide attempts to outline the style used in the mkinitcpio codebase.

Table of Contents

1. Bash v. POSIX

Never use POSIX syntax if Bash offers a construct of its own, even if the two are effectively identical. This means always using double braces over the inferior [ and test.

2. Variable usage and naming conventions

There are three classifications of variables in mkinitcpio.

2.1. Local variables

All lower case, and scoped within functions. Use freely, as they are well contained. Unless you are introducing a new option, this is what you want to use.

local foo="$1"

2.2. Global variables

These are known to mkinitcpio internally, but are global in scope. They carry runtime configuration and data collected during the image generation process. These are always lower case, but carry a leading underscore to denote that they are global. It is helpful to prefix these variables instead with a f or d if they refer to a file or directory, respectively.

define -i _optcolor=1
_d_hookdir='/etc/foo.d'
_f_config='/etc/foo.conf'

2.3. "API" variables

Also global in scope, but exist "outside" of mkinitcpio - either drawn in from the configuration file, or "exported" to the install hooks. These are always all upper case. When introducing new variables, extreme care must be taken to pick names that will not conflict with the environment inherited by mkinitcpio.

3. Function naming

Use all lower case with underscores where appropriate, for easy readability. Adhere to POSIX variable naming requirements for the contents of the name, that is: only alphanumerics, underscores, and the identifier must not start with a number.

4. Quoting

Overquoting is preferred to underquoting. Prefer single quotes to double quotes if possible. Remember to quote, quote and quote some more.

When quoting variables, use brace expansion if the variable is part of a larger string.

a='/test'
b="/some/path${a}"
c="$b"

5. Functions and block statements

Always use "top-right, lower left" for blocks of code and functions.

do_glob() {
    local g fn="$1"; shift

    for g in "$@"; do
        "$fn" "$g"
    done
}

6. Building

To build with meson, run meson setup build [options…​]. This will create ./build and prepare mkinitcpio for installation. See meson.options for a list of mkinitcpio-specific options that can be passed to meson.

To install, run meson install -C build.

6.1. Meson templating

All source files are templated by meson with the following variables:

  • VERSION: mkinitcpio version

  • BINDIR: the binary installation directory (for example: /usr/bin)

  • SYSCONFDIR: the system configuration directory (for example: /etc)

  • INITCPIO_LIBDIR: the mkinitcpio library directory (for example: /usr/lib/initcpio)

  • INITCPIO_SYSCONFDIR: the mkinitcpio system configuration directory (for example: /etc/initcpio)

  • VCONSOLE_CONF: the name of the vconsole.conf file in SYSCONFDIR. On some distributions, this may be something else, like rc.conf

  • UDEVD_PATH: the absolute path to the udev daemon executable

  • TMPFILES_PATH: the absolute path to the systemd-tmpfiles executable

Templated values can be used in source files as @VARIABLE@.

New templated values should be added to conf_data in meson.build.

7. Testing

7.1. Bash Automated Testing System

mkinitcpio uses bats (Bash Automated Testing System). The tests are found in the test directory. Use meson test -C build --suite bats to run the test suite.

Each newly added function should also have an accompanying test.

7.2. ShellCheck

All shell scripts must be validated with ShellCheck. Use meson test -C build --suite shellcheck and ensure it successfully passes.

8. EditorConfig

A .editorconfig file is provided to ensure consistency (indenting, newlines, trailing whitespace) between text editors.