Skip to content

Commit

Permalink
update the readme and examples
Browse files Browse the repository at this point in the history
  • Loading branch information
@ripytide
ripytide committed Sep 29, 2024
1 parent 8512466 commit 7caf315
Show file tree
Hide file tree
Showing 3 changed files with 172 additions and 218 deletions.
314 changes: 109 additions & 205 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 [<path>...]` | create a symlink to the specified group file(s) in your groups folder |
| `group export [args] <group> ...` | export (move) a non-symlink group and re-import it as symlink |
| `group list` | list names of all groups |
| `group new [-e] [<group>...]` | create new groups, use `-e` to edit them immediately after creation |
| `group remove [<group>...]` | remove a previously imported group |
| `group show [<group>...]` | 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 <regex>` | 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/<VERSION>` or
`component/<VERSION>/<component>`, where <VERSION> can be stable,
nightly, or any explicit rust version. The `<component>` 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 <package-name>
packages explicitly by running: `pipx install <package-name>
--include-deps`.
21 changes: 18 additions & 3 deletions config.toml
View file
Original file line number Diff line number Diff line change
@@ -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"]
Expand Down
Loading

0 comments on commit 7caf315

Please sign in to comment.