# 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 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:

```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, either 'system' or 'user'
                ```
        - `pkg_flatpak` is a list of dicts