Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lkubb/salt-tool-template-formula

A heavily modified variant of the official template formula for Cookiecutter. Serves as a base for several formulae that configure the user / developer environment with Salt.
https://github.com/lkubb/salt-tool-template-formula

cookiecutter-template development-environment devops dotfiles salt-formula saltstack

Last synced: 27 days ago
JSON representation

A heavily modified variant of the official template formula for Cookiecutter. Serves as a base for several formulae that configure the user / developer environment with Salt.

Awesome Lists containing this project

README 

        
Cookiecutter Template for ``salt-tool`` Formulae

================================================



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.



About ``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.



Prerequisites

-------------

Cookiecutter

~~~~~~~~~~~~

* 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

~~~~~

`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)



Example Installation

~~~~~~~~~~~~~~~~~~~~

Since I use ``pipx`` to manage python programs in their own isolated environments, my installation goes as follows:



.. code-block:: bash



    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@my



Pip might complain about some dependencies, but it works.



Usage

-----

First Creation

~~~~~~~~~~~~~~

Creating a new formula from this template is as easy as:



.. code-block:: bash



    cookiecutter https://github.com/lkubb/salt-tool-template-formula



For 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.



.. code-block:: bash



    cruft create https://github.com/lkubb/salt-tool-template-formula



Customization

~~~~~~~~~~~~~

Having 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``.



Parameters

----------

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_chrome`` or ``chrome``. 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_family`` files 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/``. 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 ``n`` here.



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.



References

----------

* https://github.com/saltstack-formulas/template-formula