e231c6ae7a
- giving things a better structure - better documentation with the way things need to be as a standard
85 lines
2.7 KiB
Markdown
85 lines
2.7 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 at minimum 6 key: value pairs
|
|
|
|
```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.
|
|
|
|
### 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:
|
|
__air_configured: true
|
|
```
|
|
|
|
or alternatively:
|
|
|
|
```yaml
|
|
- name: Start air configuration
|
|
when:
|
|
- __configured['air'] is undefined
|
|
```
|
|
|
|
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: pkg_sys
|
|
- Only for packages installed from the system package manager
|
|
- If a package adds a repository to handle the system installation, it should be
|
|
done in the package configuration itself. For example, installing `ghostty` via
|
|
the system package manager requires adding a copr repo on fedora. This should be
|
|
done in a section named 'Adding copr repository scottames/ghostty'
|
|
|