Contributing

Package definition

A "package" is just a yaml task list that defines how to install a piece of software. It does this through the use of helpers that manage;

dependency installations
building from source
linking binaries to a usable PATH
calling external tools when required
installation via package managers on the system

Anatomy of a Package Definition

It starts with package metadata, as a comment block above the installation steps. This should come after the line # vim: set filetype=yaml.ansible :, which sets up the correct linter and language server when using neovim/vim.

Metadata

The metadata consists of key: value pairs, at minimum requiring:

# Package: <package name>
# Description: <package description>
# Version: <latest supported version of package. 'latest' is fine>
# Methods: <list of available methods for installation>
# Helpers: <list of helpers used by the package directly>
# Maintainers: <list of maintainers for this package>

This list should match package defaults where it makes sense, for example, the Version: should match the default installed version of the package.

Default configuration

Default, non-computed configuration must exist in vars/main.yml, generally consisting of the default version, urls, internal dependencies (internal to Ansible package manager) and list of files installed after a build, without the install_prefix.

When adding default configuration, it MUST match the following:

Surround the configuration in # {{{ <package> configuration and # }}}
- Where "package" is the name of the package
Prefix the configuration with the name of the package, using snake case
- Example: alacritty_version: v0.16.1
- This keeps the configuration unique per package, and allows for the defaults to be over-ridden where needed.

The things that should be in the default configuration, if relevant, are:

Default version, as <package>_version
Git repository for pulling the source as <package>_git_repo
Archive URL as <package>_archive_url
Internal dependecies as <package>_pkg_deps: <list of internal dependencies>
Files installed when building from source as <package>_build_files
Default compile flags for the build system.
- Example using cargo: <package>_cargo_build_flags: <list of build flags>
Package build dependencies per ansible_os_family. These are only for system packages that are required for building the package from source.
Package runtime dependencies as <package>_run_deps: <list of run dependencies>
- These should only be system packages, not internal packages

Configuration acknowledgement

The "Configuration acknowledgement" MUST be at the start of the yaml file, and cover everything this package does. This is important for gating when a package should be configured or not.

It looks like this, using the air package:

- name: Start air configuration
  when:
    - "'air' is not in __configured"
  block:
    - name: Configure air installation method
    ...

    - name: Finalize air configuration
      ansible.builtin.set_fact:
        __configured: "{{ __configured | combine( { 'air': true } ) }}"

This way, if a package is included as part of another packages build, it only happens once.

Setting and adding package configuration to list

Adding the configuration for a package is done by appending the configuration to the appropriate list. Each helper has it's own installation block in tasks/main.yml.

Depending on the package installation method, the package must be added to the appropriate list.

Different lists, and when to use them

The following is a list of the different lists that are used, and the order they are run.

System packages

pkg_sys: List of system package manager packages to install

Installed using ansible.builtin.package
Installs the entire gathered list of packages at once, instead of looping over single items.
The package list is made unique by applying the unique filter to the list

Archive packages

Archive packages are binaries installed by extracting an archive and linking the files in place (usually in <install_prefix>/bin).

Archives are kept in a cache after download, unless clean_cache is true
Extracted archives are placed in <install_prefix>/archive/<name>
Archive files are linked to the appropriate place under install_prefix, as dictated by the pkg.links list, where pkg is the top level dict object of the archive

pkg_archive: List of packages installed via archive, like go
- Loops over list of archives and downloads, extracts and links them before moving on to the next.
Linux only packages. Flatpaks, appimages, and snapcraft packages.
- Flatpaks: use the lists flatpak_remotes and pkg_flatpak
  - flatpak_remotes is a list of dicts containing the flatpak remote configurations
    - Managed using community.general.flatpak_remote ansible module.
    - Format is:
      remote: name: <remote name> url: <flatpakrepo url> method: <optional, either 'system' or 'user'
  - pkg_flatpak is a list of dicts

5.2 KiB Raw Blame History