64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
# Cram
|
|
|
|
> To force (people or things) into a place or container that is or appears to be too small to contain them.
|
|
|
|
An alternative to GNU Stow, more some notion of packages with dependencies and install scripts.
|
|
|
|
Think an Ansible or Puppet but anyarch and lite enough to check in with your dotfiles.
|
|
|
|
## Overview
|
|
|
|
Somewhat like Stow, Cram operates in terms of packages, which are directories with the following structure -
|
|
|
|
```
|
|
/REQUIRES # A list of other packages this one requires.
|
|
/BUILD # 1. Perform any compile or package management tasks.
|
|
/PRE_INSTALL # 2. Any other tasks required before installation occurs.
|
|
/INSTALL # 3. Do whatever constitutes installation.
|
|
# This supercedes the default copying of files.
|
|
/POST_INSTALL # 4. Any cleanup or other tasks following installation
|
|
... # Any other files are treated as package contents.
|
|
|
|
```
|
|
|
|
Cram reads a config dir with three groups of packages
|
|
- `packages.d/<packagename>` contains a package that installs but probably shouldn't configure a given tool, package or group of files.
|
|
Configuration should be left to profiles.
|
|
- `profiles.d/<profilename>` contains a profile; a group of related profiles and packages that should be installed together.
|
|
- `hosts.d/<hostname>` contains one package for each host, and should pull in a list of profiles.
|
|
- Both profiles and hosts entries may specify their own "inline" packages as a convenience.
|
|
|
|
The intent of this tool is to keep GNU Stow's intuitive model of deploying configs via symlinks, and augment it with a useful pattern for talking about "layers" / "packages" of related configs.
|
|
|
|
Cram installs the package `hosts.d/$(hostname)`, and `profiles.d/default` by default.
|
|
|
|
## Usage
|
|
|
|
```
|
|
$ cram apply [--dry-run|--execute] [--optimize] <configdir> <destdir>
|
|
```
|
|
|
|
The `apply` task applies a configuration to a destination directory.
|
|
The most common uses of this would be `--dry-run`, which functions as a `diff` or `--execute ~/conf ~/` for emulating Stow and installing dotfiles.
|
|
|
|
Cram always reads the `.cram.log` state file and diffs the current state against the configured state.
|
|
Files and directories no longer defined by the configured state are cleaned up automatically.
|
|
|
|
```
|
|
$ cram show <configdir>
|
|
```
|
|
|
|
The `list` task loads up and prints the `.cram.log` state file generated by any previous `cram apply --execute` so you can read a manifest of what cram thinks it did.
|
|
|
|
```
|
|
$ cram list <configdir>
|
|
```
|
|
|
|
The `show` task lists out all available packages (eg. packages, profiles, hosts, and subpackages) as a dependency graph.
|
|
|
|
## License
|
|
|
|
Copyright Reid 'arrdem' McKenzie, 31/10/2021.
|
|
|
|
Published under the terms of the MIT license.
|
|
See the included `LICENSE` file for more.
|