Spell writing handbook

Introduction

This is a technical reference document.

The first part describes all of the files that are checked for in a spell, their purpose, and documented attributes.
The second part describes the standards we use in the grimoire.

Spell files

These are the files used during a cast, in their execution order:

PREPARE – Useful for those rare times when the DETAILS file needs to be modified or the spell or package needs to be configured before the DETAILS file is executed.
DETAILS – Informational file, required for all spells.
CONFIGURE – Used to select and modify a package's compile time options.
DEPENDS – Lists all other spells that are required or optionally required to be cast.
UP_TRIGGERS – Provides the opportunity to use runtime registration of on_cast triggers.
SUB_DEPENDS – Used to make a spell depend on another spell with certain features enabled.
PRE_SUB_DEPENDS – Tells Sorcery whether or not the sub-dependee is providing the given sub-depends.
TRIGGER_CHECK – Used to inspect each trigger in a spell.

(…Processing of the depended on spells…)

(…DETAILS is run again…)

CONFLICTS

— Build API begin —

PRE_BUILD
BUILD
PRE_INSTALL (build API 2 only)
INSTALL (build API 2 only)
INSTALL_EXTRAS (build API 2 only) / POST_BUILD (build API 1 only)
POST_INSTALL
TRANSFER (build API 2 only)
FINAL (build API 2 only)
TRIGGERS

— Build API end —

(…The triggered spells are cast now…)

These are the files used during the download, in their execution order:

DOWNLOAD

These are the files used during a dispel, in their execution order:

These are the files used during a resurrect, in their execution order:

These files are processed during a scribe update, cleanse --tablet, or cleanse --tablet_spell, in their execution order:

REPAIR^* files

These files are known as spell filters:

excluded
protected
volatiles
configs

These are the other files:

HISTORY
PROVIDES
EXPORTS
SOLO
services
init.d directory
pam.d directory
xinetd.d directory
desktop directory

Standards

General formatting rule: no tabs except in HISTORY, align '='s in DETAILS, and use newlines (for other formatting rules, check the appropriate spell file pages above).
Spell standards – strict rules related to creating or updating spells, which help to avoid common mistakes.
Integrity checking standards – standards of integrity verification for upstream sources.
Spell deprecation process – a guide to perform spell deprecation.
Multiversion spells – the standard for spells with multiple versions.

Spell/Book

Information

Tools

Resources

Spell writing handbook

Introduction

Spell files

Standards