The DETAILS file is used to contain the information about the application that the spell is for.
SPELL
- This specifies the name of the spell you are creating. It must be lower case. (We let the developers of the application choose the way they'd like it spelled).
Example: SPELL="xzgv"
VERSION
- This specifies the current version number of the application in question. Please be exact.
Example: VERSION="0.7"
SOURCE
- Specifies the name of the source file of the application. Must be the full name not including any path information.
Example: SOURCE="$SPELL-$VERSION.tar.gz"
SOURCEn
- Specifies the names of additional source files for the application. The numbering starts with 2.
Example: SOURCE2="xzgv-addons.tar.gz"
SOURCE_DIRECTORY
- Used to specify the location where the source will be unpacked. You must pay special attention to the naming of the directory when unpacking the source file. (i.e. if the subdirectory is $SPELL-$VERSION, or perhaps just $SPELL etc.). $BUILD_DIRECTORY is a special variable which is set by the sorcery tools to allow you to not have to worry about where sorcery will unpack the source from, currently sorcery uses /usr/src to begin the unpacking of the application's source.
Example: SOURCE_DIRECTORY=$BUILD_DIRECTORY/$SPELL-$VERSION
SOURCE_URL[*]
- An array where you specify as many targets of where to download the source from. Must specify the full path (including filename) of the application source, so it is known where to download the spell from. Incrementing the number in the []'s will add additional entries, attempted in numerical order.
Example: SOURCE_URL[0]=http://xzgv.browser.org/$SOURCE
SOURCEn_URL[*]
- Arrays specifying the download links for additional SOURCEn entries. The numbering starts with 2 (SOURCE2_URL).
Example: SOURCE2_URL[0]=http://xzgv.browser.org/$SOURCE2
$SOURCEFORGE_URL
Automatically downloads the source from a SourceForge project.
Example: SOURCE_URL[0]=$SOURCEFORGE_URL/$SPELL/$SOURCE
FORCE_DOWNLOAD=on
- When set to 'on', the source will be downloaded by sorcery, regardless of it being present in the spool directory.
Example: FORCE_DOWNLOAD=on Example: FORCE_DOWNLOAD[2]=on #for SOURCE2 not SOURCE[2]! Example: FORCE_DOWNLOAD[n]=on #for SOURCEn not SOURCE[n]!
SOURCE_HASH/SOURCEn_HASH
The hash of the source file. Consists of <algorithm>:<hash>:<verification level>. The algorithm we currently use is sha512. verification level can be either WORKS_FOR_ME (no verification done) or other verification levels listed in Source Integrity Checking Standards
Example: SOURCE_HASH=sha512:<hash>:UPSTREAM_HASH
(actual hash ommited due to insane length)
SOURCE_GPG/SOURCEn_GPG
A signature used to verify the source file. Consists of <key file>:<signature file>:<verification level>. The key file has to exist in either the spell, the section or the grimoire the spell is in. The signature should be in the spell or downloaded by the spell. verification levels are listed in Source Integrity Checking Standards. See Spell_GPG_Checking for details about how to generate a key.
Example: SOURCE_GPG="gurus.gpg:$SOURCE.sig:WORKS_FOR_ME"
SOURCE_IGNORE/SOURCEn_IGNORE
This can be used instead of SOURCE_GPG or SOURCE_HASH to tell sorcery not to check the file. The content of this variable states the reason why it shouldn't be checked. It can be one of signature (that source is an upstream gpg signature), unversioned (the source changes without changing its filename) or volatile (source is downloaded from a version control system like cvs or subversion).
Example: SOURCE2_IGNORE=signature
WEB_SITE
- Used to document the applications "official" website (if there is one).
Example: WEB_SITE=http://xzgv.browser.org/
ENTERED
- This is a numerical string indicating the date this spell was "officially" created. Set this to the day you submit the spell for approval.
Example: ENTERED=20020406
UPDATED
- This is a numerical string indicating the date this spell was last changed. Used as a reference for the sorcery scripts to know if a spell has been updated. (This forces a recompile so only update for non-version updates that need a recompile. Version updates and non-recompile-needed changes should not touch this variable.)
Note: This is still supported, but shouldn't be used anymore. Instead use PATCHLEVEL or SECURITY_PATCH as applicable.
Example: UPDATED=20020406
PATCHLEVEL
- The number of revisions a spell has gone through without changing VERSION. This defaults to 0 if ommited. Any change to a spell that should trigger a rebuild on all systems using that spell should have PATCHLEVEL updated. On a VERSION change PATCHLEVEL should be removed.
Example: PATCHLEVEL=2
SECURITY_PATCH
The number of security related spell changes or version updates the spell has gone through. This number is used by sorcery queue-security to determine what spells need to be rebuilt for security reasons. SECURITY_PATCH must never be reset.
Example: SECURITY_PATCH=3
LICENSE[*]
- Specifies the licenses this application has been released under. Please use the acronym where applicable. The array elements correspond to the different source files in the same way as the MD5 array elements.
Example: LICENSE[0]=GPL
KEYWORDS Do not use this yet!
- We haven't decided which are valid keywords and so from the first systematic run onwards, only chaos ensued. Until we standardise the keywords list, no new ones should be added. Users can't easily search through them anyway.
SHORT
- A brief description of the spell. What it is, it's purpose etc. Used primarily by the 'gaze' command of the sorcery tools.
Example: SHORT="xzgv is a GTK+/Imlib-based picture viewer for X."
DOCS
Optional tag used to override the implicit DOCS variable to change what docs are installed. Only copies files, for dirs use DOC_DIRS instead.
Example:
Implicit DOCS: DOCS='README* FAQ* CHAN* DOC* SETUP LICENSE COPYING NEWS *rc'
New DOCS: DOCS="README* BUGS NEWS COPYING data/COPYING.* docs/example.lircrc"
DOCS="$DOCS etc/*.conf"DOC_DIRS
Optional tag used to override the implicit DOC_DIRS variable to change what doc dirs are installed. Only copies dirs and their contents.
Implicit DOC_DIRS="doc* conf"
- After all of the entries have been made for the details file. The last thing should be the long description for this spell. Used to give a more lengthy description of what this spell is and it's common uses etc. The description must be aligned to 80 characters (no line should exceed 80th character).
Example: cat << EOF xzgv is a GTK+/Imlib-based picture viewer for X, which supports most popular image formats. It provides a thumbnail-based file selector, and allows panning and fit-to-window methods of viewing. It has mouse support as well, but can be used solely from the keyboard. EOF
A list of lowercased generic single-word descriptions of a package. (1)