ansible_role_package/README.md

# ansible_role_package

Manage package installation for a number of packages
that sometimes need special handling. Some are built from
source, some are appimages, some are special sources like
`cargo`, `npm`, `go`, etc.

When defining a workstation role, I had a lot of packages that needed
special instructions to properly install and use. I decided to
simplify the management of those packages by creating a role with
special handling.

Order of precedence for package installation:

1. System package manager (dnf, apt, homebrew, etc.)
2. Source built - only in some situations, like for fast moving software (neovim)
3. Appimage (Linux only)
4. Flatpak (Linux only)
5. Snap (Linux only), takes precedence over flatpak on Ubuntu based systems
6. Language package manager (`cargo install`, `go install`, `npm install`, etc.)

_This does not configure installed software, just installs it_

To install any of the available packages, they must be part of a list called
`packages`. Dependencies are handled on a best case basis.

## Supported Operating Systems

- Fedora Linux
- MacOS
- RHEL based distributions *Experimental* *best effort*
- Debian *Experimental*
- Alpine linux *Experimental* *best effort)

## Available Packages

- air: hot reload for go #development
- alacritty: terminal built in rust #gui
- ansible-lint: linting for yaml.ansible files #development #mangement
- ansible: configuration management #management
- ansible_ls: ansible language-server #development
- aquamarine: graphics library for hyrpland #hyprland #linux #gui
- bashls: bash language server #development
- bat: bat, an ehanced replacement for cat #cli
- bitwarden: password mananger #gui #security
- blender: 3d modeling, video editing tools #gui #media
- broot: a file browser/manager for the cli #cli
- btop: advanced top replacement #cli #management
- buf: protocol buffer tooling in go #development
- bufls: protocol buffer language server #development
- carapace: universal command completion engine #cli
- cheat: cli cheatsheet creator and viewer #cli
- checkmake: a linter and analyzer for makefiles #development
- choose: an alternative to cut written in rust #cli
- clangd: the LLVM based C/C++ compiler, langauge server and linter #development
- cmake: build system for C/C++ projects #development
- cmakelang: cmake linter and formatter #development
- commitlint-cli: linting for git commit messages #development
- commitlint-config-conventional: config for commitlint-cli #development
- consul: service discovery by hashicorp #hashicorp #service
- cssls: css language server #development
- curlie: enhanced version of curl #cli #network
- dbeaver: database manager gui #development #gui
- direnv: load .env files in the cli #development #mangement
- dockerls: dockerfile lanaguage server #development
- dotenv-linter: linter for .env  files #development
- duf: a good looking replacement for df #cli #management
- dust: a better looking version of du #cli #management
- editorconfig: common editor configuration system #development
- eslint: ECMA Script linting #development
- eza: a modern ls replacement #cli
- fd: a modern replacement for find #cli
- firefox: a modern OSS web browser #gui
- flatpak: universal linux package management system #cli #linux #management
- fzf: fuzzy find from a list given over stdin #cli
- ghostty: a modern advanced terminal emulator #gui
- git: project versioning system #development #management
- glow: cli markdown parser and viewer #cli
- go: the go programming language #development
- godot: the best OSS game making studio/engine #development #gui
- gopls: the go language server #development
- gping: graphical pinging on the cli #cli #management
- greetd: a simple system greeter #cli #linux #gui #hyprland
- heroic: heroic games launcher #gui #linux
- htmlls: html language server #development
- htmx-lsp: htmx language server #developement
- httpie: a graphical REST client #development #gui
- hugo: static html site generator #cli #development
- hyperfine: a cli benchmarking tool #cli
- hyprcursor: a hyprland support library #hyprland
- hyprgraphics: a hyrpland graphics library #hyprland
- hypridle: hyprland system idle monitor #hyprland
- hyprland: a pretty tiling window manager #hyprland #linux #gui
- hyprland_protocols: a hyprland wayland protocol library #hyprland
- hyprland_qt_support: hyprland qt libraries #hyprland
- hyprland_qtutils: hyrpland tools in qt: #hyprland
- hyprlang: hyprland configuration language #hyrpland
- hyprlock: hyprland screen locker #hyprland
- hyprpaper: hyprland wallpaper manager #hyprland
- hyprpicker: hyprland colour picker #hyprland
- hyprpolkitagent: hyprland policy kit agent #hyprland #management #security
- hyprutils: hyprland utilities library #hyprland
- hyprwayland_scanner: hyprland wayland library scanner #hyprland
- intelephense: php language server, linter and formatter #development
- jinja-lsp: the jinja language server #development
- jq: json cli parser #cli #development
- jsonls: json language server #development
- kitty: high perfomance terminal emulator #gui
- lazygit: git made easy #git #cli #development
- libreoffice: the free office suite #gui
- luals: lua language server #development
- markdownlint-cli: markdown linter #development
- mcfly: cli history manager #cli #management
- minio_client: cli S3 client #cli #management
- neovide: graphical interface for neovim in rust #development #gui
- neovim: best vim fork ever #neovim #development #cli #development
- nerdfonts: fonts patched with icons and glyphs #cli #gui
- nextcloud: nextcloud desktop sync client #gui #management
- nginxls: nginx configuration language server #development
- nodejs: javascript runtime engine #javascript #cli #development
- nomad: application orchestration by hashicorp #hashicorp #management
- nwg_hello: a greetd greeter #gui #linux #hyprland
- packer: machine builder by hashicorp #vm #development #hashicorp #management
- pandoc: universal document translator #cli
- pgadmin: postgresql administration gui #development #development #gui
- pipx: install pip packages as self contained executables #cli #management
- podman: container runtime engine compatible with docker #cli #mangement
- pulumi: infrastructure as code via regular programming languages #cli #development #manage
- pyright: python language server, linter and formatter #development
- python3: python3 language interpreter #development
- quobix-vacuum: openapi linter and sdk written in go #development
- revive: a fast and strict linter for go #development
- ripgrep: fast modern grep replacement #cli
- rust: the rust programming language #development #cli
- sd: a modern replacement for sed #cli
- sdbus_cpp_2: systemd dbus library version 2 #development #hyprland
- sqlfluff: sql linter #development
- sqlls: sql language server #development
- starship: command line prompt generator #cli
- stow: manage dotfiles easily #cli #management
- tailscale: p2p vpn with wireguard #security #cli #gui
- tailwindcss-languageserver: tailwindcss language server #development
- templ: generate HTML using go #go #html #development
- terraform: infrastructre as code via configuration files #cli #hashicorp #management
- terraformls: terraform language server #development #hashicorp
- thunderbird: email client from mozilla #gui
- tidy: html linter and formatter #development
- tldr: manpage summarizer #cli
- tmux: terminal multiplexer #cli
- uwsm: universal wayland system manager #hyprland #linux #gui
- vault: secrets management by hashicorp #security #hashicorp
- xdg_desktop_portal_hyprland: xdg portal for hyprland #hyprland #gui #linux
- xh: cli curl replacement #cli #network
- yamlls: yaml language server #development
- yazi: terminal file manager in rust #cli #management
- zfs: the zetabyte filesystem #filesystem #cli
- zig: the zig programming language #development
- zls: the zig language server #development
- zoxide: easily jump between directories #cli #management
- zsh: Z shell #cli

## Requirements

- nothing by ansible 

## Role Variables

- `use_local`: Boolean, default `true`
  - When `true`, uses the following paths:
    - `$HOME/.local` as the install prefix, placing binaries in `$HOME/.local/bin`
    - `$HOME/.local/appimage` for saved appimages, which are then linked to `$HOME/.local/bin`
    - `$HOME/.local/archive` for extracted archives linking binaries to `$HOME/.local/bin`
    - `$HOME/.cache` for caching downloads
    - `$HOME/.cargo` for cargo installations, placing binaries in `$HOME/.cargo/bin`
  - When `false`, uses the following system wide paths:
    - `/usr/local` as the install prefix, placing binaries in `/usr/local/bin`
    - `/opt/appimage` for saved appimages, which are then linked to `/usr/local/bin`
    - `/opt/archive` for extracted archives, linking binaries to `/usr/local/bin`
    - `/opt/cache` for caching downloads
    - `/opt/cargo` for rust cargo installations, placing binaries in `/opt/cargo/bin`
- `packages`: List of strings
  - List of packages to install from the `Available Packages` list
- `prefer_method`: String, default `system`
  - The preferred method of installation an application when multiple options exist
  - Valid options are:
    - `flatpak` - Flatpak, Linux only
    - `langtool` - Using language tools such as `cargo`, `go`, `npm` or `pipx`
    - `snap` - Snap, Linux only
    - `source` - Prefer building from source. **Not recommended**
    - `system` - Default, system package manager (dnf, apt, homebrew, etc.)

## Dependencies

## Example Playbook

```yaml
- name: Ensure packages are installed
  vars:
    packages:
      - air
      - go
      - rust
      - neovim
  hosts: devmachines
  gather_facts: true
  tasks:
    - name: Install given packages
      ansible.builtin.inlude_role:
        name: ansible_role_package
```

## License

MIT

## Author Information

- Matthew Stobbs <matthew@stobbs.ca>