From 7caf3150518581b35b20b81615601a91be2cc735 Mon Sep 17 00:00:00 2001 From: ripytide Date: Sun, 29 Sep 2024 17:31:05 +0100 Subject: [PATCH] update the readme and examples --- README.md | 314 +++++++++++++------------------------- config.toml | 21 ++- groups/example_group.toml | 55 +++++-- 3 files changed, 172 insertions(+), 218 deletions(-) diff --git a/README.md b/README.md index 67cca0c..1b00ceb 100644 --- a/README.md +++ b/README.md @@ -62,234 +62,138 @@ but not in your group files (`pacdef clean`). ## Supported Backends -At the moment, supported backends are the following. Pull requests for +At the moment, supported backends are the following. Pull Requests for additional backends are welcome! -Package Manager | Group Name | Notes | ---------------- | ----------- | ---------------------------------------------------------------------------------------- | -`pacman` | `[arch]` | only one of `pacman`/`paru`/`yay` can -be used at once since they operate on the same local package database, -configure which one via the `arch_package_manager` config option| -`paru` | `[arch]` | includes pacman-wrapping AUR helpers (configurable) | -`yay` | `[arch]` | includes pacman-wrapping AUR helpers (configurable) | -`apt` | `[debian]` | minimum supported apt-version 2.0.2 ([see upstream](https://gitlab.com/volian/rust-apt)) | -`dnf` | `[fedora]` | | -`flatpak` | `[flatpak]` | can manage either system-wide or per-user installation (configurable) | -`pip` | `[python]` | | -`cargo` | `[rust]` | | -`rustup` | `[rustup]` | See the comments [below](#rustup) about the syntax of the packages in the group file. | -`xbps` | `[void]` | | - -Backends that have a `feature flag` require setting the respective -flag for the build process. The appropriate system libraries and their -header files must be present on the machine and be detectable by -`pkg-config`. For backends that state "built-in", they are always -supported during compile time. Any backend can be disabled during -runtime (see below, "[Configuration](#configuration)"). - -For example, to build `pacdef` with support for Debian Linux, you can -run one of the two commands. - -- (recommended) `cargo install -F debian pacdef`, this downloads and - builds it from [https://crates.io](https://crates.io) -- in a clone of this repository, `cargo install --path . -F debian` - -### Example - -This tree shows my pacdef repository (not the `pacdef` config dir). - -```ini -. -├── generic -│ ├── audio -│ ├── base -│ ├── desktop -│ ├── private -│ ├── rust -│ ├── wayland -│ ├── wireless -│ ├── work -│ └── xorg -├── hosts -│ ├── hostname_a -│ ├── hostname_b -│ └── hostname_c -└── pacdef.toml -``` - -- The `base` group holds all packages I need unconditionally, and - includes things like zfs, - [paru](https://github.com/Morganamilo/paru) and - [neovim](https://github.com/neovim/neovim). -- In `xorg` and `wayland` I have stored the respective graphic servers - and DEs. -- `wireless` contains tools like `iwd` and `bluez-utils` for machines - with wireless interfaces. -- Under `hosts` I have one file for each machine I use. The filenames - match the corresponding hostname. The packages are specific to one - machine only, like device drivers, or any programs I use exclusively - on that machine. - -Usage on different machines: - -- home server: `base private hostname_a` -- private PC: `audio base desktop private rust wayland hostname_b` -- work PC: `base desktop rust work xorg hostname_c` - -### Example - -Let's assume you have the following group files. - -`base`: - -```ini -[arch] -paru -zsh +| Backend | Group Name | Notes | +| --------------------- | ----------- | ------------------------------------- | +| `pacman`/`paru`/`yay` | `[arch]` | see the `arch_package_manager` config | +| `apt` | `[apt]` | | +| `dnf` | `[dnf]` | | +| `flatpak` | `[flatpak]` | | +| `pipx` | `[pipx]` | | +| `cargo` | `[cargo]` | | +| `rustup` | `[rustup]` | | +| `xbps` | `[xbps]` | | -[rust] -pacdef -topgrade -``` - -`development`: +## Config -```ini -[arch] -rustup -rust-analyzer - -[rust] -cargo-tree -flamegraph +```toml +# By default the `pacdef` `config.toml` file is expected in the +# `XDG_CONFIG_HOME/pacdef` directory (`~/.config/pacdef/config.toml`) +# unless using the `--config-dir` cli option. + +# To decide which group files are relevant for the current machine +# `pacdef` uses the machine's hostname in the `hostname_groups` table in +# the config file to get a list of group file names. + +# Since pacman, yay and paru all operate on the same package database +# they are mutally exclusive and so you must pick which one you want +# pacdef to use. +# Examples include: "pacman", "paru", "yay" +# Default: "pacman" +arch_package_manager = "paru" + +# Extra arguments passed to pacman when removing an arch package. +# Default: [] +arch_rm_args = ["-ns"] + +# Whether to install flatpak packages systemwide or for the current user. +# Default: true +flatpak_systemwide = true + +# Backends to disable from all pacdef behavior. See the README.md for +# the list of backend names +# Default: [] +disabled_backends = ["apt"] + +# Which group files apply for which hostnames +# Default: None +[hostname_groups] +pc = ["example_group"] +laptop = ["example_group"] +server = ["example_group"] ``` -Pacdef will make sure you have the following packages installed for -each package manager: - -- Arch (`pacman`, AUR helpers): paru, zsh, rustup, rust-analyzer -- Rust (`cargo`): pacdef, topgrade, cargo-tree, flamegraph - -Note that the name of the section corresponds to the ecosystem it -relates to, rather than the package manager it uses. - -## Commands - -| Subcommand | Description | -| --------------------------------- | --------------------------------------------------------------------- | -| `group import [...]` | create a symlink to the specified group file(s) in your groups folder | -| `group export [args] ...` | export (move) a non-symlink group and re-import it as symlink | -| `group list` | list names of all groups | -| `group new [-e] [...]` | create new groups, use `-e` to edit them immediately after creation | -| `group remove [...]` | remove a previously imported group | -| `group show [...]` | show contents of a group | -| `package clean [--no_confirm]` | remove all unmanaged packages | -| `package review` | for each unmanaged package interactively decide what to do | -| `package search ` | search for managed packages that match the search string | -| `package sync [--no_confirm]` | install managed packages | -| `package unmanaged` | show all unmanaged packages | -| `version` | show version information, supported backends | - -### Aliases - -Most subcommands have aliases. For example, instead of `pacdef package -sync` you can write `pacdef p sy`, and `pacdef group show` would -become `pacdef g s`. - -Use `--help` or the zsh completion to find the right aliases. - -## Configuration - -On first execution, it will create an empty config file under -`$XDG_CONFIG_HOME/pacdef/pacdef.toml`. The following key-value pairs -can be set. The listed values are the defaults. +## Group Files ```toml -aur_helper = "paru" # AUR helper to use on Arch Linux (paru, yay, ...) -arch_rm_args = [] # additional args to pass to AUR helper when removing packages (optional) -disabled_backends = [] # backends that pacdef should not manage, e.g. ["python"], this can reduce runtime if the package manager is notoriously slow (like pip) - -warn_not_symlinks = true # warn if a group file is not a symlink -flatpak_systemwide = true # whether flatpak packages should be installed system-wide or per user -pip_binary = "pip" # choose whether to use pipx instead of pip for python package management (see below, 'pitfalls while using pipx') +# Declared Packages in toml format can come in two formats, short-form +# and long-form: +# +# short-form syntax is simply a string of the name of the package. +# +# long-form syntax is a table which contains several fields which can +# optionally be set to specify install options on a per-package basis. +# The "package" field in the table specifies the name of the package. +# +# For example, the following two packages are equivalent: +# arch = [ +# "pacdef", +# { package = "pacdef" } +# ] + +arch = [ + "pacdef", + # optional_deps: additional packages to install with this package, short-form syntax only + { package = "pacdef", optional_deps = ["git"] } +] +cargo = [ + "pacdef", + # see cargo docs for info on the options + { package = "pacdef", version = "0.1.0", git = "https://github.com/ripytide/pacdef", all_features = true, no_default_features = false, features = [ "feature1", ] }, +] +pipx = [ + "pacdef", + { package = "packdef" } +] +apt = [ + "pacdef", + { package = "packdef" } +] +xbps = [ + "pacdef", + { package = "packdef" } +] +flatpak = [ + "pacdef", + { package = "packdef" } +] +dnf = [ + "pacdef", + # see dnf docs for more info on these options + { package = "pacdef", repo = "/etc/yum.repos.d/fedora_extras.repo" }, +] +rustup = [ + "stable", + # components: extra non-default components to install with this toolchain + { package = "stable", components = ["rust-analyzer"] } +] ``` -## Group file syntax - -Group files loosely follow the syntax for `ini`-files. - -1. Sections begin by their name in brackets. -2. One package per line. -3. Anything after a `#` is ignored. -4. Empty lines are ignored. -5. If a package exists in multiple repositories, the repo can be - specified as prefix followed by a forward slash. The package - manager must understand this notation. - -Example: - -```ini -[arch] -alacritty -firefox # this comment is ignored -libreoffice-fresh -mycustomrepo/zsh-theme-powerlevel10k - -[rust] -cargo-update -topgrade -``` +## Commands -### Rustup - -Rustup packages are managed quite differently. For referring to the -syntax, have a look [below](#group-file-syntax). In contrast to other -package managers, rustup handles package naming very differently. -These packages are either of the form `toolchain/` or -`component//`, where can be stable, -nightly, or any explicit rust version. The `` field has to -be substituted with the name of the component you want installed. - -Example: - -```ini -[rustup] -component/stable/rust-analyzer -toolchain/stable -component/stable/cargo -component/stable/rust-src -component/stable/rustc -toolchain/1.70.0 -component/1.70.0/cargo -component/1.70.0/clippy -component/1.70.0/rust-docs -component/1.70.0/rust-src -component/1.70.0/rust-std -component/1.70.0/rustc -component/1.70.0/rustfmt -``` +Run `pacdef -h` to see an overview of the commands available with +`pacdef`. -## Misc. +## Miscellaneous ### Automation Pacdef is supported by -[topgrade](https://github.com/topgrade-rs/topgrade). +[`topgrade`](https://github.com/topgrade-rs/topgrade). -### Naming +## Naming `pacdef` combines the words "package" and "define". -### minimum supported rust version (MSRV) - -MSRV is 1.74 due to dependencies that require this specific version. -Development is conducted against the latest stable version. +## Backend Pitfalls -### Pitfalls while using pipx +### Pipx Some packages like -[mdformat-myst](https://github.com/executablebooks/mdformat-myst) do +[`mdformat-myst`](https://github.com/executablebooks/mdformat-myst) do not provide an executable themselves but rather act as a plugin to their dependency, which is mdformat in this case. Please install such -packages explicitly by running `pipx install +packages explicitly by running: `pipx install --include-deps`. diff --git a/config.toml b/config.toml index 5db77d0..26b6412 100644 --- a/config.toml +++ b/config.toml @@ -1,18 +1,33 @@ -# Which arch package manager to use. For example: pacman, paru, yay, -# etc.. +# By default the `pacdef` `config.toml` file is expected in the +# `XDG_CONFIG_HOME/pacdef` directory (`~/.config/pacdef/config.toml`) +# unless using the `--config-dir` cli option. + +# To decide which group files are relevant for the current machine +# `pacdef` uses the machine's hostname in the `hostname_groups` table in +# the config file to get a list of group file names. + +# Since pacman, yay and paru all operate on the same package database +# they are mutally exclusive and so you must pick which one you want +# pacdef to use. +# Examples include: "pacman", "paru", "yay" +# Default: "pacman" arch_package_manager = "paru" # Extra arguments passed to pacman when removing an arch package. -arch_rm_args = [""] +# Default: [] +arch_rm_args = ["-ns"] # Whether to install flatpak packages systemwide or for the current user. +# Default: true flatpak_systemwide = true # Backends to disable from all pacdef behavior. See the README.md for # the list of backend names +# Default: [] disabled_backends = ["apt"] # Which group files apply for which hostnames +# Default: None [hostname_groups] pc = ["example_group"] laptop = ["example_group"] diff --git a/groups/example_group.toml b/groups/example_group.toml index ed30c1f..cb3ba63 100644 --- a/groups/example_group.toml +++ b/groups/example_group.toml @@ -1,16 +1,51 @@ -arch = ["pacdef", { package = "pacdef", optional_deps = ["git"] }] +# Declared Packages in toml format can come in two formats, short-form +# and long-form: +# +# short-form syntax is simply a string of the name of the package. +# +# long-form syntax is a table which contains several fields which can +# optionally be set to specify install options on a per-package basis. +# The "package" field in the table specifies the name of the package. +# +# For example, the following two packages are equivalent: +# arch = [ +# "pacdef", +# { package = "pacdef" } +# ] + +arch = [ + "pacdef", + # optional_deps: additional packages to install with this package, short-form syntax only + { package = "pacdef", optional_deps = ["git"] } +] cargo = [ "pacdef", - { package = "pacdef", version = "0.1.0", git = "https://github.com/ripytide/pacdef", all_features = true, no_default_features = false, features = [ - "feature1", - ] }, -] -pipx = ["pacdef"] -apt = ["pacdef"] -xbps = ["pacdef"] -flatpak = ["pacdef"] + # see cargo docs for info on the options + { package = "pacdef", version = "0.1.0", git = "https://github.com/ripytide/pacdef", all_features = true, no_default_features = false, features = [ "feature1", ] }, +] +pipx = [ + "pacdef", + { package = "packdef" } +] +apt = [ + "pacdef", + { package = "packdef" } +] +xbps = [ + "pacdef", + { package = "packdef" } +] +flatpak = [ + "pacdef", + { package = "packdef" } +] dnf = [ "pacdef", + # see dnf docs for more info on these options { package = "pacdef", repo = "/etc/yum.repos.d/fedora_extras.repo" }, ] -rustup = ["stable", { package = "stable", components = ["rust-analyzer"] }] +rustup = [ + "stable", + # components: extra non-default components to install with this toolchain + { package = "stable", components = ["rust-analyzer"] } +]