GRIMOIRE(5) File Formats 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 informa-
tion as package name, version(1,3,5), 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 direc-
tories 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(1,n) 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(1,n) does not exist in(1,8) the package directory then a
set(7,n,1 builtins) of default description instructions are used. The default instruc-
tions for each description file(1,n) can be found in(1,8) /var/lib/sorcery/mod-
ules/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(7,n,1 builtins) in(1,8) DETAILS.
A better description of these file(1,n) 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(1,8,3 Search::Dict) 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(1,3) README (perhaps you skip this step?)
step 5) less(1,3) 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(1,8) build_api/api2 as
e.g. real_default_pre_build, any calls of sorcery functions from gri-
moire 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(3,n) you want your spell to patch some files after the unpacking of
sources, your PRE_BUILD file(1,n) should contain
default_pre_build && patch
DESCRIPTION FILES
PREPARE
This file(1,n) can be created if(3,n) there needs to be some kind of pre-
configuration before DETAILS is sourced. Note that this file(1,n) is
only used in(1,8) a cast.
DETAILS (necessary for every spell)
This file(1,n) is required and describes the URL for step 1. It also
contains version(1,3,5) information, package name, source name, source
directory, and a description of the package.
CONFLICTS
This file(1,n) contains a list of spells conflicting with this one.
Usually only used when two spells install the same file(1,n)(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(1,n) contains a list of other packages upon which the pack-
age depends. This enables automatic installing of packages
needed. If dependencies are turned on then the packages listed
are installed in(1,8) 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(1,8) lowercase>,
or real_default_... in(1,8) build_api/api2. (except FINAL and TRIGGERS)
PRE_BUILD
This describes the unpacking process as performed in(1,8) 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(1,8) 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(1,n) touched during install so we can get the
install log of files installed by the spell.
It is recommended that if(3,n) you add this file(1,n) 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 configu-
ration files and documentation, and finally turns off install-
watch. It is highly recommended to run default_post_install at
the end of this file.
FINAL
This file(1,n) contains instructions on files to be installed and
instructions to be performed that should for some reason not
appear in(1,8) the install logs (e.g. modifying another package's
/etc files)
This is the only file(1,n) in(1,8) the build process that does not have a
default, so if(3,n) it does not exist, nothing will be done.
TRIGGERS
If this file(1,n) exists, the triggers in(1,8) it are registered. A trig-
ger is a mechanism in(1,8) sorcery to recompile a package as soon as
another package is recompiled/removed (e.g. drivers are trig-
gered to recast on kernel recasts)
The next two files are run at remove. Their defaults are to do nothing.
PRE_REMOVE
This file(1,n) contains instructions on what to do before dispelling
the package, e.g. stopping the daemon installed by it.
POST_REMOVE
This file(1,n) contains instructions to perform after successfully
removing the package. This might be used to undo changes done in(1,8)
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/edi-
tors/emacs. (use your grimoire for test)
If however you want to look(1,8,3 Search::Dict) at a very unusual, but much more complex
example, look(1,8,3 Search::Dict) at /var/lib/sorcery/codex/test/x11-libs/xorg. To under-
stand how the software catalog works it is also important to look(1,8,3 Search::Dict) at
/var/lib/sorcery/modules/build_api/api2 and examine the default func-
tions.
AUTHOR
Original version(1,3,5) 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), sor-
cery(8), sorcery_config(5), summon(8)
WARRANTY
This is free software with ABSOLUTELY NO WARRANTY
Source Mage GNU Linux September 2004 GRIMOIRE(5)