Seth Woolley's Man Viewer

grimoire(5) - grimoire, grimoire - a software catalogue for sorcery - man 5 grimoire

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

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)

References for this manual (incoming links)