142 lines
5.6 KiB
Markdown
142 lines
5.6 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
# 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 overridden 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:
|
|
|
|
```yaml
|
|
- 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
|
|
|
|
2. 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.
|
|
3. 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:
|
|
```yaml
|
|
remote:
|
|
name: <remote name>
|
|
url: <flatpakrepo url>
|
|
method: <optional. Default 'system'>
|
|
```
|
|
- `pkg_flatpak` is a list of dicts describing how to install a flatpak
|
|
- Managed using `community.general.flatpak` ansible module.
|
|
- Format is:
|
|
```yaml
|
|
flatpak:
|
|
name: <flatpak name>
|
|
remote: <remote to install from>
|
|
method: <optional. Default 'system'>
|
|
state: <optional. Default 'present'>
|
|
```
|