working on helpers

CONTRIBUTING.md

@@ -19,7 +19,7 @@ up the correct linter and language server when using neovim/vim.
 
 ### Metadata
 
-The metadata consists of at minimum 6 key: value pairs
+The metadata consists of `key: value` pairs, at minimum requiring:
 
 ```yaml
 # Package: <package name>
@@ -32,6 +32,35 @@ The metadata consists of at minimum 6 key: value pairs
 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,
@@ -50,15 +79,7 @@ It looks like this, using the `air` package:
 
     - name: Finalize air configuration
       ansible.builtin.set_fact:
-        __air_configured: true
-```
-
-or alternatively:
-
-```yaml
-- name: Start air configuration
-  when:
-    - __configured['air'] is undefined
+        __configured: "{{ __configured | combine( { 'air': true } ) }}"
 ```
 
 This way, if a package is included as part of another packages build, it only happens once.
@@ -68,17 +89,44 @@ This way, if a package is included as part of another packages build, it only ha
 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.
+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'
+##### 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