This cookiecutter template is a heavily modified variant of the official template-formula that aims to ease the process of writing userland formulae in the style of the tool suite.
This term describes a bunch of formulae that I wrote to setup and manage my personal systems (examples: zsh, git, gnupg, ssh, vim, asdf, Firefox, Yabai). I will create a better overview of those once I get ready to publish them.
The underlying problem was that Salt is generally used to setup server environments, which operates on the system scope. To manage the user environment, I had to bend the available tools a bit.
- This cookiecutter currently needs to be modified to find the template files with the alternative syntax, otherwise it will complain about this not being a template. (@TODO pull request)
- Also, since PR #1692, cookiecutter does not support dicts with new keys, which breaks my use case. Hence I removed this breaking change again.
Cruft is a wrapper around cookiecutter that takes care of maintaining the boilerplate. It allows you to show the diff between what the template generated and the current state with cruft diff and to apply updates from the template with cruft update (and more).
Cruft currently also needs to be very recent and modified to support cookiecutter v2 and the alternative Jinja syntax. Both changes are found in the my branch of my fork. (@TODO pull request)
Since I use pipx to manage python programs in their own isolated environments, my installation goes as follows:
pipx install git+https://github.com/lkubb/cruft.git@my
pipx runpip cruft uninstall cookiecutter
pipx runpip cruft install git+https://github.com/lkubb/cookiecutter.git@myPip might complain about some dependencies, but it works.
Creating a new formula from this template is as easy as:
cookiecutter https://github.com/lkubb/salt-tool-template-formulaFor cookiecutter, this is where the journey ends.
The recommended way to use this template goes a little further though, since (a) there are hidden variables with further configuration and (b) updates from the template are cumbersome. This is where cruft steps in.
cruft create https://github.com/lkubb/salt-tool-template-formulaHaving created the formula with cruft, you will find a .cruft.json file in the root directory. This saves your answers and allows you to edit some hidden variables. Those are currently for parameters to the formula, sorted into:
lookup: Custom lookup variables for data that the user should not have to modify regularly.settings: Global settings for this formula.usersettings: Settings that are available per-user.
Once you have modified those, run cruft diff | git apply to recreate the formula. Warning: This command resets the state to the autogenerated one, so take care if you have modified any files manually at this point. In that case, you can pipe the output into a file and manually select the changes: cruft diff > temp.patch, edit and then git apply temp.patch.
This is an overview of the available parameters for autogeneration. The most recent version is found in cookiecutter.json though and might be out of sync.
- name [str]
- The name of the managed program. Example:
Google Chrome. - abbr [str]
- A slugified version of
name. Example:google-chrome. - abbr_pysafe [str]
- A short and pythonic version of
abbr. Example:google_chromeorchrome. This will be used in many places, including the formula base dir (tool_chrome), the pillar key and the Jinja variable name. - pkg [str]
- The default package name of the program. Example:
google-chrome,gnupg. - modstate [bool]
- Whether this formula will provide custom execution/state modules. This will autogenerate a skeleton for both and include hints in the docs.
- needs_repo [bool]
- Whether the package installation relies on custom repositories (for Linux). This will add boilerplate for those in the
parameters/os_familyfiles as well as sls files to install them. - has_service [bool]
- Whether a service is to be managed.
- mac_library [bool]
- Whether on MacOS, the default configuration lives in
~/Library/Application Support. - mac_cask [bool]
- Whether on MacOS, the package is a cask.
- has_xdg [bool]
- Whether the formula should have some kind of XDG spec support.
- needs_xdg_help [bool]
- If has_xdg and the program does not act that way by default, whether you will provide a way to migrate the data and enforce complicance.
- has_conffile_only [bool]
- If the program only has a configuration file (e.g.
.gitconfig). - default_confdir [str]
- The default configuration directory on Linux. Can be empty for
$HOME. - default_confdir_mac [str]
- The default configuration directory on MacOS. Can be empty for
$HOME. - default_conffile [str]
- The name of the default configuration file. Example:
.gitconfig. - xdg_dirname [str]
- The name of the directory in XDG dirs for this program (e.g.
git). - xdg_conffile [str]
- The name of the configuration file inside
~/.config/<xdg_dirname>. Example:config. - has_configsync [bool]
- Whether the formula provides automatic syncing of configuration files from a dotfiles repository.
- has_config_template [bool]
- Whether the formula provides a way to serialize parameters into the program's config file.
- has_completions [bool]
- Whether the formula provides a way to install shell completions for the program.
- has_tests [bool]
- Whether the formula should have test boilerplate code. This is only provided for Linux at the moment, so MacOS-only formulae should answer
nhere. - git_username [str]
- Your Github/Gitlab/... username that should be used as the author of the formula.
- lookup [map/dict]
- An arbitrarily nested mapping/dictionary that describes lookup data that the user should not have to modify. Examples include package dependencies, some paths, package names etc.
- settings [map/dict]
- An arbitrarily nested mapping/dictionary that describes global parameters for the formula. Examples include package version and system configuration for the managed program.
- usersettings [map/dict]
- An arbitrarily nested mapping/dictionary that describes per-user parameters for the formula. Examples include list of plugins to install, user configuration for the managed program.