GRIMOIRE(5)

NAME
grimoire - a software catalogue for sorcery

DESCRIPTION
A software catalogue is a list of software packages (simply referred to as "packages" or "spells") divided into sections. Each package contains one or more description files. Description files contain such information as package name, version, URL, directory information, etc. Other description files provide unpacking, compilation, installation, and tracking instructions.

SUMMARY
The grimoires are found under /var/lib/sorcery. The top level of directories are the grimoires names. The list of grimoires is found under /etc/sorcery/local/grimoire The subdirectories are the sections. The directories under the section names are the packages. Each package directory will have a BASH description file called DETAILS and optionally contain one or more of the following description files:

PREPARE, CONFLICTS, CONFIGURE, DEPENDS, PRE_BUILD, BUILD, PRE_INSTALL, INSTALL, POST_INSTALL, FINAL, PRE_REMOVE, POST_REMOVE.

If a description file does not exist in the package directory then a set of default description instructions are used. The default instructions for each description file can be found in /var/lib/sorcery/modules/build_api/api2.

PRELIMINARY NOTES

This manpage describes build_api 2. The older build_api 1 is deprecated and getting removed. For spells to work with api2, BUILD_API=2 needs to be set in DETAILS.

A better description of these file are found on the website, under the spell howto:

    http://wiki.sourcemage.org/index.php?page=Spellbook

A typical manual source code installation might look like this (assume the application is called foo):

    step 1) find the URL and download the tarball

    step 2) tar xvfz foo-1.00.tar.gz

    step 3) cd foo

    step 4) less README (perhaps you skip this step?)

    step 5) less INSTALL (... and this one?)

    step 6) ./configure

    step 7) make

    step 8) make install

Sourcemage basically automates these steps.

Note on the defaults: While the defaults are found in build_api/api2 as e.g. real_default_pre_build, any calls of sorcery functions from grimoire files should be limited to functions from libapi. This is so your spell doesn't break as soon as some sorcery code is rewritten. So if you want your spell to patch some files after the unpacking of sources, your PRE_BUILD file should contain

    default_pre_build && patch

DESCRIPTION FILES

PREPARE

    This file can be created if there needs to be some kind of preconfiguration before DETAILS is sourced. Note that this file is only used in a cast.

DETAILS (necessary for every spell)

    This file is required and describes the URL for step 1. It also contains version information, package name, source name, source directory, and a description of the package.

CONFLICTS

    This file contains a list of spells conflicting with this one. Usually only used when two spells install the same file(s).

CONFIGURE

    The configure script. This is not step 6, but rather questions about options to be passed to ./configure and other changes to the build.

DEPENDS

    This file contains a list of other packages upon which the package depends. This enables automatic installing of packages needed. If dependencies are turned on then the packages listed are installed in order prior to installing package.

If any of the files mentioned up to now are missing, nothing will be used. (except DETAILS, which is required)

(dependencies are being cast, DETAILS run again)

all the following files have defaults as default_<name in lowercase>, or real_default_... in build_api/api2. (except FINAL and TRIGGERS)

PRE_BUILD

    This describes the unpacking process as performed in step 2. The default PRE_BUILD will work for the following compressions:

    bzip2, gzip, zip, RPM, tar

BUILD

    This describes the compilation process as performed in steps 6 and 7. Here the package is built, not installed yet. If the software package compiles using these 2 steps then the default BUILD can be used. Sorcery automatically changes the install path and sets optimization options.

PRE_INSTALL

    This will start installwatch, sorcery's install logging system. It will log every file touched during install so we can get the install log of files installed by the spell. It is recommended that if you add this file it contains default_pre_install.

INSTALL

    This is step 8. "make install" by default. If your spell needs another way to install its files, here is the place to do so.

POST_INSTALL

    This step finishes off the install process. It installs configuration files and documentation, and finally turns off installwatch. It is highly recommended to run default_post_install at the end of this file.

FINAL

    This file contains instructions on files to be installed and instructions to be performed that should for some reason not appear in the install logs (e.g. modifying another package's /etc files) This is the only file in the build process that does not have a default, so if it does not exist, nothing will be done.

TRIGGERS

    If this file exists, the triggers in it are registered. A trigger is a mechanism in sorcery to recompile a package as soon as another package is recompiled/removed (e.g. drivers are triggered to recast on kernel recasts)

The next two files are run at remove. Their defaults are to do nothing.

PRE_REMOVE

    This file contains instructions on what to do before dispelling the package, e.g. stopping the daemon installed by it.

POST_REMOVE

    This file contains instructions to perform after successfully removing the package. This might be used to undo changes done in FINAL.

FINAL NOTES
The best way to learn the software catalogue is to examine some of the description files yourself. Most software catalogue entries are simple. For example try looking under /var/lib/sorcery/codex/test/editors/emacs. (use your grimoire for test) If however you want to look at a very unusual, but much more complex example, look at /var/lib/sorcery/codex/test/x11-libs/xorg. To understand how the software catalog works it is also important to look at /var/lib/sorcery/modules/build_api/api2 and examine the default functions.

AUTHOR
Original version by Kyle Sallee, and updated Thomas Stewart and Karsten Behrmann.

Maintained by the Source Mage GNU Linux Team (http://www.sourcemage.org)

REPORTING BUGS

Report bugs to bugzilla <http://bugs.sourcemage.org>

SEE ALSO
cast(8), cleanse(8), dispel(8), gaze(1), scribbler(8), scribe(8), sorcery(8), sorcery_config(5), summon(8)

WARRANTY

This is free software with ABSOLUTELY NO WARRANTY