# sorcery – Package manager for Source Mage GNU/Linux

- Synopsis
- Requirements
- Parameters
- Notes
- Examples
- Status

## Synopsis

- Manages “spells” on Source Mage GNU/Linux using sorcery toolchain

## Requirements

The below requirements are needed on the host that executes this module.

- bash

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
cache_valid_time - |  | Time in seconds to invalidate grimoire collection on update especially useful for SCM and rsync grimoires makes sense only in pair with `update_cache`
depends - |  | Comma-separated list of _optional_ dependencies to build a spell (or make sure it is built) with; use +/- in front of dependency to turn it on/off ('+' is optional though) this option is ignored if `name` parameter is equal to '*' or contains more than one spell providers must be supplied in the form recognized by Sorcery, e.g. 'openssl(SSL)'
name - |  | Name of the spell multiple names can be given, separated by commas special value '*' in conjunction with states `latest` or `rebuild` will update or rebuild the whole system respectively aliases: spell

state
-

Choices:
- present ←
- latest
- absent
- cast
- dispelled
- rebuild

Whether to cast, dispel or rebuild a package
state `cast` is an equivalent of `present`, not `latest`
state `latest` always triggers `update_cache=yes`
state `rebuild` implies cast of all specified spells, not only those existed before

update
boolean

Choices:
- no ←
- yes

Whether or not to update sorcery scripts at the very first stage

update_cache
boolean

Choices:
- no ←
- yes

Whether or not to update grimoire collection before casting spells
aliases: update_codex

## Notes

Note

- When all three components are selected, the update goes by the sequence – Sorcery -> Grimoire(s) -> Spell(s); you cannot override it.
- grimoire handling (i.e. add/remove, including SCM/rsync versions) is not yet supported.

## Examples

    # Make sure spell 'foo' is installed
    - sorcery:
        spell: foo
        state: present

    # Make sure spells 'foo', 'bar' and 'baz' are removed
    - sorcery:
        spell: foo,bar,baz
        state: absent

    # Make sure spell 'foo' with dependencies 'bar' and 'baz' is installed
    - sorcery:
        spell: foo
        depends: bar,baz
        state: present

    # Make sure spell 'foo' with 'bar' and without 'baz' dependencies is installed
    - sorcery:
        spell: foo
        depends: +bar,-baz
        state: present

    # Make sure spell 'foo' with libressl (providing SSL) dependency is installed
    - sorcery:
        spell: foo
        depends: libressl(SSL)
        state: present

    # Playbook: make sure spells with/without required dependencies (if any) are installed
    - sorcery:
        name: "{{ item.spell }}"
        depends: "{{ item.depends | default(None) }}"
        state: present
      loop:
        - { spell: 'vifm', depends: '+file,-gtk+2' }
        - { spell: 'fwknop', depends: 'gpgme' }
        - { spell: 'pv,tnftp,tor' }

    # Install the latest version of spell 'foo' using regular glossary
    - sorcery:
        name: foo
        state: latest

    # Rebuild spell 'foo'
    - sorcery:
        spell: foo
        state: rebuild

    # Rebuild the whole system, but update Sorcery and Codex first
    - sorcery:
        spell: '*'
        state: rebuild
        update: yes
        update_cache: yes

    # Refresh the grimoire collection if it's 1 day old using native sorcerous alias
    - sorcery:
        update_codex: yes
        cache_valid_time: 86400

    # Update only Sorcery itself
    - sorcery:
        update: yes

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Vlad Glagolev (@vaygr)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.