~sourcemage/tome-rdp

7a57aa4b8384ab4bec5aca47af6dd7450fae7742 — Eric Sandall 17 years ago e138c33 master 
Remove GrimoireGuruHandbook: Old copy, now using GrimoireGuruHandbook.tex
patch browse .tar.gz 
2 files changed, 3 insertions(+), 931 deletions(-)

D GrimoireGuruHandbook
M GrimoireGuruHandbook.tex

D GrimoireGuruHandbook => GrimoireGuruHandbook +0 -931
@@ 1,931 0,0 @@
We can either have all of the information in one file, such as 
http://wiki.sourcemage.org/GrimoireGurusHandbook, or we can setup each
section in a separate file, such as
http://wiki.sourcemage.org/NewGuruHandbook (I like the latter approach
better).

Guru Handbook v3.0

Section 1: Introduction
Welcome to helping to improve Source Mage! As a contributing member you are
entitled to filing bugs, submitting patches, and cleaning up our packages.
Below you will find instructions and tips on how to be the most helpful you
may be. You will soon be a bug hunting army of one.

Subscribe to all the freshmeat pages for the software in your section of
the grimoire, and also appropriate email lists for that software, and also
subscribe to sm-spell-submit@lists.ibiblio.org for our own notifications.
You probably have this covered already.

You will be responsible for taking newly contributed spells from new spell
submissions assigned to you via bugzilla (http://bugs.sourcemage.org/),
reviewing, correcting and submitting for inclusion in the grimoire. You may
recruit as many people to help you with this as you want. You can reject,
decline or otherwise ignore a newly contributed spell for any reason. You
may delay reviewing spells for as long as you like.

Section 2: Bug tracking
We are currently using Bugzilla[link], which is accessible from
http://bugs.sourcemage.org/.
	Subsection I: Creating an account
	Subsection II: Searching for bug reports
	Subsection III: Creating a bug report
	Subsection IV: Taking ownership of a bug
	Subsection V: Requesting integration to stable-rc or stable grimoires

Section 3: Patch creation
We prefer patches to be submitted with the diff options -Naur.

Section 4: SCM Usage
	Subsection I: Requesting an account
Here I am assuming you have been invited to obtain write permissions to our
repositories.

Send an e-mail to emrys@sourcemage.org requesting an SCM account with which
products (test grimoire, devel Sorcery, cauldron, etc.) you wish to have
write access to as well as your public RSA key. If you do not have a RSA
key, you may generate one by running:
	$ ssh-keygen
And include the contents of ~/.ssh/id_rsa.pub (assuming you only have one
RSA key).

You may view the repositories via a web browser at
http://scmweb.sourcemage.org/.

	Subsection II: Checking out the repositories
Now that you have an SCM account, you are ready to checkout the repository
you wish to work on. The following repositories are currently available:
	cauldron, grimoire, grimoire/games, grimoire/xorg-modular,
	grimoire/z-rejected, misc/archspecs, misc/prometheus, misc/quill,
	sorcery, and tome/rdp
Most Grimoire Developers will only work on with grimoire (which contains
devel, test, stable-rc, and stable grimoires), so you will check it out
with:
	$ git clone ssh://scm.sourcemage.org/smgl/grimoire
This will create a directory called 'grimoire' in your current directory.
  
	Subsection III: Setting up your information
In each cloned repository, there is a .git/config file where you will
provide some information (mainly for the commit messages):
Assuming you are Eric Sandall, you will want to add the following
information:
	[user]
		name = Eric Sandall
		email = sandalle@sourcemage.org

	Subsection IV: Keeping clones up-to-date
To grab the latest changes from the SCM, you will 'pull' them to you with
the following command, run from inside your clone (e.g. ~/grimoire/)
	$ git pull

Note that all but the `git clone` command need to be run from this
directory.  If you receive a message saying "fatal: Not a git repository:
'.git'", then you did not follow my instruction above.

	Subsection V: Selecting your working branch
The main grimoire that you have checked out has many branches. You may view
the available branches by running:
	$ git branch
And you will see output similar to this:
  devel
* master
  origin
  stable-0.3
  stable-0.4
  stable-rc-0.4
  stable-rc-0.5
  stable-rc-0.6

The "*" before "master" means that this is the currently checked out branch.
To checkout another branch (say devel), you would run:
	$ git checkout devel
Unless you know what you are doing, only work in the master (a.k.a. test)
branch.

You will *never* touch the 'origin' branch, as this is used by git
internally to check your changes against.

	Subsection VI: Making changes
Before making any changes, it is a good idea to make sure your clone is
up-to-date (though this is not required, it does make submitting easier).
Now that you are up-to-date, let us do a practice update.

Example: git 1.4.3.5 has just been released
	1. Make sure we are up-to-date with upstream
		$ git pull
	2. Make necessary changes to the git files
		$ cd devel/git
		$ vi DETAILS HISTORY
		Change VERSION from 1.4.3.4 to 1.4.3.5
		Add update entry to HISTORY
	3. Mark the files you wish to update
		$ git update-index DETAILS HISTORY

	4. Check which files are slated to be committed
		$ git status
		# Updated but not checked in:
		#   (will commit)
		#
		#       modified: devel/git/DETAILS
		#       modified: devel/git/HISTORY
		#

	Subsection VII: Committing changes
Now that we have made our modifications, we should submit them. To commit
all of your flagged files (from `git status`), run:
	$ git commit
This will open up your favorite editor (as defined in the variable $EDITOR)
with a file describing the files to be updated, where you briefly describe
what changes you made.

You may also commit only specific files by specifying them on the command
line:
	$ git commit DETAILS HISTORY
This will only commit the DETAILS and HISTORY files in our current
directory.

If you wish to specify your message log on the command line, rather than in
your favorite editor, you may do so with the -m flag:
	$ git commit -m "Updated git to 1.4.3.5"

If ever you make changes you wish to undo, before running `git commit`, you
may run the following:
	$ git checkout -f <list of files to revert to origin>

Note that `git commit` only updates your local copy of the repository, not
the server repository where everyone pulls from.

	Subsection VIII: Pushing changes upstream
You may do as many commits as you like before pushing your changes back to
the repository so everyone may see them. To push your changes to the server
repository, run:
	$ git push <destination> <source>
Since we are working in master, we would run:
	$ git push origin master
Note that destination will almost always be 'origin'.

	Subsection IX: Resolving conflicts
When you receive a conflict (usually denoted by the lines):
	ERROR: Merge conflict in {file}
	fatal: merge program failed
	After resolving the conflicts, mark the corrected paths with
	`git-update-index <paths>` and commit the result.
Inside the conflicting file you will see the line <<<<< .merge_file_stuff,
which begins the new changes, and a >>>>>> .merge_file_otherstuff, which
ends the new changes. Once you resolve the conflict by editing the file
and remove what should not be there, you will run `git update-index <file>`
and then commit your changes.

	Subsection X: Creating your own local branch
	Subsection XI: Creating your own remote branch
	Subsection XII: Checking out other branches
	Subsection XIII: Integrating between branches
	Subsection XIV: Updated a stable-rc or stable grimoire
These grimoires are special, in that you never modify them directly
(similar to how you treat the origin branch). To update one of these (say
stable-rc-0.6), you will use the following steps:
	1. $ git checkout stable-rc-0.6
	  Switch to the stable-rc-0.6 branch.
	2. $ git branch my-stable-rc-0.6
	  Create a branch of the current stable-rc-0.6 called my-stable-rc-0.6.
	3. $ git checkout my-stable-rc-0.6
	  Switch to our local my-stable-rc-0.6 branch.
	4. cherry-pick the changes you want into my-stable-rc-0.6
	5. $ git pull origin stable-rc-0.6
	  This synchronizing stable-rc-0.6 with upstream
	6. $ git push origin my-stable-rc-0.6:stable-rc-0.6.
	  This will push your changes from my-stable-rc-0.6 into stable-rc-0.6
	  and then up to the server (origin).

	Subsection XV: Fetching a new remote branch
The need for this most commonly occurs when a new stable branch is released,
but may be used for any other remote branches you wish to retrieve.

Let's say that stable-0.6 was just released, and your current local branches
look like this:
$ git branch
  devel
* master
  origin
  stable-0.3
  stable-0.4
  stable-rc-0.4
  stable-rc-0.5
  stable-rc-0.6

To grab the new stable-0.6 and stable-rc-0.7 (the next stable release candidate)
you would do the following:

$ git fetch ssh://scm.sourcemage.org/smgl/grimoire.git stable-0.6:stable-0.6

This tells git to fetch the remote branch named stable-0.6 (before the ":") and
call it stable-0.6 (after the ":") into the current git repository.

If you want this branch to be updated on a pull, you will also need to add
the branch information to .git/remotes/origin:
	Pull: refs/heads/stable-0.6:refs/heads/stable-0.6
	Pull: refs/heads/stable-rc-0.7:refs/heads/stable-rc-0.7
These two lines will add pull information for stable-0.6 and stable-rc-0.7.

Section 5: Writing a spell
	Subsection: PREPARE
Even before DETAILS, this file is sourced and cane be used to setup variables
for use in DETAILS.

There are cases where a spell writer wants to allow a choice of version in a
spell. Most of the times this is about pulling the current version from a
source code management system like CVS of Subversion. There are other cases
where an upstream project releases stable and development versions.

First rule for allowing such a version choice is that all dependencies of the
spell need to work with all versions, otherwise the spell should be split.

The version choice is done in PREPARE using the usual config_query* functions.
If there are more than two different versions to choose from, this should be
done using config_query_list, always defaulting to the version upstream
recommends as stable.

For versions downloading from a source code management system, the spell should
also ask the user whether she wants to update that spell automatically on every
sorcery [system-update|queue] (defaulting to 'n') and setting the version to
a timestamp.

Example: Setting up VERSION ahead of time for a multi-version spell
PREPARE:
config_query  SPELL_CVS  "Use CVS for latest development version?"  n  &&

if  [[  "$SPELL_CVS" == "y"  ]];  then
  config_query  SPELL_CVS_AUTOUPDATE  "Update on every system update?"  n
  if  [[  "$SPELL_CVS_AUTOUPDATE"  ==  "y"  ]];  then
    PREPARE_VERSION=$(date +%Y%m%d)
    PREPARE_SOURCE_URL[0]=cvs://:pserver:anonymous@fun.org:/cvsroot/spell:main
    SOURCE_IGNORE=volatile
    FORCE_DOWNLOAD="on"
  else
    PREPARE_VERSION="cvs"
  fi
else
  # Default version
  PREPARE_VERSION="2.1.3"
      SOURCE_HASH=<some sha512 hash of the 2.1.3 tarball>
fi

DETAILS:
        VERSION=${PREPARE_VERSION:-"2.1.3"}
         SOURCE=$SPELL-$VERSION.tar.bz2
  SOURCE_URL[0]=${PREPARE_SOURCE_URL[0]:-http://www.fun.org/download/$SOURCE}

Note: The ${VAR``:-string}  syntax means if $VAR is not empty, then use $VAR,
if it is empty, then use the string.

Note: We keep all of the checks out of DETAILS and use PREPARE for the ugliness.

The following variables are available in PREPARE:
	* SOURCE_CACHE: the directory where the sources reside:
	  /var/spool/sorcery
	* SCRIPT_DIRECTORY: the spell script directory in the codex:
	  /path/to/grimoire/section/spell
	* SPELL_DIRECTORY: this is the same as ${SCRIPT_DIRECTORY} 
	* SECTION_DIRECTORY: path/to/grimoire/section
	* GRIMOIRE: /path/to/grimoire

For more info on these variables, check /var/lib/sorcery/modules/libcodex
An important usecase for PREPARE is in multi version spells.

	Subsection: DETAILS
This file contains information about the application which 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

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 UPSTREAM_HASH (source was checked against an
	upstream provided hash).

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 level can be WORKS_FOR_ME, UPSTREAM_HASH, UPSTREAM_KEY,
	ESTABLISHED_UPSTREAM_KEY, VERIFIED_UPSTREAM_KEY or
	ID_CHECK_UPSTREAM_KEY (see libunpack in sorcery for a description of
	those levels). 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

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.

Example:
Implicit DOCS:
  DOCS="README* FAQ* CHAN* doc* DOC* conf SETUP LICENSE COPYING NEWS"
New DOCS:
  DOCS="README* BUGS NEWS COPYING data/COPYING.* docs/html docs/example.lircrc"
  DOCS="$DOCS etc/*.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

	Subsection: CONFIGURE
The CONFIGURE script is sourced during a cast, after DETAILS and before DEPENDS
and CONFLICTS. It is used to take care of more complex spells for which extra
information must be gathered and stored. This can be needed when there are
option ./configure switches that don't require any extra spells, or for doing
extra things in the BUILD script. The query can be made in the CONFIGURE and
then the flags stored can be used in any of the spell scripts.

Sorcery provides a way to store and later re-store environment variables
between different Spellbook scripts. The environment variable you want to
persist must be marked by function persistent_add

Example:
  persistent_add VAR BLAH SPELL_OPTION

This way you marked the three variables so that they will be persisted

Moreover sorcery gives you tools for querying user for information. Four
functions are provided for your convenience:
	* config_query
	* config_query_string
	* config_query_list
	* config_query_option
	* config_query_multi this is GRIMOIRE FUNCTIONS specific for the time
	  being

These functions do have three parameters; variable name, question presented to
the user and default (preselected) answer. All questions will be asked in the
positive (e.g. "Allow X", "Enable X").

Example:
    config_query  RMRF  "Enable forced removal?"  y
    config_query_string  NAME  "What is your name?"  $USER
    config_query_list  MTA  "Which mta would you like to use?" \
                             qmail sendmail postfix
    config_query_option  SPELL_OPTION  "Use X?"  y  "--with-x"  "--without-x"
    config_query_multi  SOMETHING  "What do you want?"  \
                        all none something1 something2

config_query_option is a bit different, it does not overwrite content of
$SPELL_OPTION, rather the result is appended to it. config_query_multi is
different from config_query_list in that it makes available multiple options
instead of just one. To use it one has to add
". $GRIMOIRE/config_query_multi.function" before calling it.

All config_query* functions also mark the variable to be persistent
automatically, and if that variable allready exists it won't ask again, just
print out the answer from last query. If it isn't apparent then you should know
that if you change the config_query* call you'll also want to change the
variable name.

For more examples and functions look into /var/lib/sorcery/modules/libapi.

	Subsection: DEPENDS
	Subsection: CONFLICTS
This file lists other spells that conflict against the spell being installed,
which default to 'n' when asked to dispel a currently installed spell.

Example:
  conflicts freeglut

and for multiple conflicts:

  conflicts  freeglut
  conflicts  openglut

You may also set the default (e.g. for a spell which conflicts with itself).

Example: Set the default to 'y' when asked to dispel freeglut
  conflicts  freeglut  y

	Subsection: PRE_BUILD
The PRE_BUILD file is executed by cast before the BUILD file.

Anything necessary to prepare the spell to be built should be done here, like
patching or unpacking additional sources. Usually this is done by adding
commands after default_pre_build, which unpacks the first source automatically.

Example:
  default_pre_build                            &&
  cd  $SOURCE_DIRECTORY                        &&
  unpack_file 2                                &&
  patch  -p0  <  $SCRIPT_DIRECTORY/gcc4.patch

Another use for this file is for spells using badly packaged sources that don't
unpack into a directory.

Example:
  mk_source_dir   $SOURCE_DIRECTORY  &&
  cd              $SOURCE_DIRECTORY  &&
  unpack_file

Many checkouts from an SCM (e.g. CVS) require you to run some setup before
building.

Example:
  default_pre_build              &&
  NOCONFIGURE="X"  ./autogen.sh

The 'NOCONFIGURE="X"' variable to autogen.sh tells autogen.sh to *not* run
./configure, since ./configure will be run in default_build.

	Subsection: DOWNLOAD

	Subsection: BUILD
	Subsection: PRE_INSTALL
PRE_INSTALL is responsible for removing the old version of the spell.
Overriding the default is only necessary in very few special cases.

Example:
# this is needed because save_libraries (in prepare_install) breaks because
# valgrind has its own libpthread.so
message  "${MESSAGE_COLOR}Preparing to install" \
         "${SPELL_COLOR}${SPELL}${DEFAULT_COLOR}"  &&

lock_resources "libgrimoire" "install"

if  spell_ok  valgrind;  then 
  dispel --notriggers --nosustain $SPELL
fi  

	Subsection: PRE_REMOVE
PRE_REMOVE is used to prepare a spell for removal. This is only necessary in a
few special cases.

Example:
  #Restore /etc/passwd when dispelling shadow
  ${INSTALL_ROOT}/usr/sbin/pwunconv &&
  ${INSTALL_ROOT}/usr/sbin/grpunconv

Done in PRE_REMOVE because those commands are installed by shadow, thus aren't
available after the dispel.

	Subsection: POST_REMOVE
POST_REMOVE is used to do any cleanup that might be necessary after a spell is
dispelled.

As an example, gstreamer 0.8 requires plugins to be registered/unregistered to
work, so gst-plugins has the following POST_REMOVE:

Example:
  gst-register-0.8

	Subsection: INSTALL
This file controls the actual install process.  If the INSTALL file is not
present in the spell, cast uses default_install:

Example:
  make  install

	Subsection: FINAL
Often used to display some important follow-up action that the sys-admin may
need to take. Also used to clean up special build directories or other cruft
needed during the cast. You use it if you really need to do something while
sorcery isn't looking.

Example:
  local  LOG=/var/log/clam-update.log  &&
  touch  $LOG                          &&
  chown  clamav  $LOG                  &&
  chmod  600     $LOG                  &&

  echo -e "\033[1mThis is a test of the virus scanner\033[0m"  &&
  clamscan -r -i $SOURCE_DIRECTORY/test                        &&
  echo -e "\033[1mTest complete\033[0m"

	Subsection: PRE_RESURRECT
	Subsection: POST_RESURRECT
	Subsection: TRIGGERS
Triggers are a solution to the problem that spells might need to act upon
events happening to other spells.

To this end, four triggers have been created:
	* on_cast
	* on_pre_cast
	* on_dispel
	* on_pre_dispel

And four actions that can be triggered:
	* cast_self
	* dispel_self
	* check_self
	* run_script <file>

These triggers are acted upon by sorcery when the events specified in the
triggers happen. The _pre_ triggers are executed before the spell is cast or
dispelled, and the others after the spell is cast or dispelled.

Each line in TRIGGERS consists of
	1) the trigger
	2) the spell to watch for
	3) the action to be triggered:

  <trigger> <spell> <action>

Or, when using action run_script:
  <trigger> <spell> run_script <file>

Take for example the following line in nvidia_driver's TRIGGERS file:

Example:
  on_cast  linux  cast_self

If nvidia_driver is installed and linux is cast, the above trigger causes
nvidia_driver to cast itself after linux is done casting.

New triggers are only registered for a spell when it is cast. They are not
automatically registered during grimoire update. If you are adding a new
TRIGGERS file, or a line to an existing one, you may also want to update
PATCHLEVEL in DETAILS. Most of the times, however, a new trigger shouldn't
force a rebuild. If something breaks, cleanse will identify problems and
suggest a recast, causing new triggers to be registered. 

	Subsection: UP_TRIGGERS
	Subsection: PRE_SUB_DEPENDS
	Subsection: SUB_DEPENDS
	Subsection: HISTORY
The format of HISTORY entries is as follows (all lines should be wrapped
to <80 columns):
<date>[space]<name>[space]<e-mail address>
[tab]*[space]<modified filename>[colon][space]<description>
[tab][space][space]<extra description for this file>
[tab]*[space]<modified filename>[colon][space]<description>
[tab][space][space]<extra description for this file>
[newline]

Example:
2006-11-13 Eric Sandall <sandalle@sourcemage.org>
	* DETAILS: Updated to 1.4.3.5
	  Changed SHORT description to not mention spell name (shorter now)

2006-10-13 Eric Sandall <sandalle@sourcemage.org>
	* DETAILS: Updated to 1.4.3.4
	* DEPENDS: Added optional dependency on foo
	  Removed dependency on bar (bogus entry)

	Subsection: PROVIDES
The PROVIDES file is used to contain information about what generic
dependencies a spell provides.

The format of this file is a simple list of provider names, seperated by
newlines.

Example:
  MOZILLA-BROWSER
  EMAIL-CLIENT
  WEB-BROWSER
  GRAPHICAL-WEB-BROWSER
  GECKO

When adding a spell to an existing provider (e.g. adding a new provider for
GECKO), *all* spells using that provider have to work with the new spell or need
to be fixed.

Note: due to historical reasons, another syntax using 'provides $NAME' is also
supported, but should not be used.

	Subsection: Deprecation
(copied from http://wiki.sourcemage.org/Spell_Deprecation)

Sometimes spells need to be removed in favor of other spells, e.g. when an
application gets renamed. This should happen automatically for users that
have the spell installed.

"old" is the spell to be removed, "new" is the spell that replaces it:
	1. Create old/PRE_BUILD, old/BUILD and old/INSTALL containing only
	  'true'.
	2. Edit old/DETAILS and comment out all SOURCE, SOURCE_URL and HASH/GPG
	  lines.
	3. Change the PATCHLEVEL field of old/DETAILS to old PATCHLEVEL+1.
	4. Create old/DEPENDS containing only 'depends new'.
	5. Create old/TRIGGERS with 'on_cast old dispel_self'.
	6. Add new/CONFLICTS containing 'conflicts old y', the y makes sure the
	  spell will cast without user intervention.
	7. Put a comment into old/HISTORY that the spell is deprecated and why
	  (e.g. * Deprecated in favour of... or * Deprecated because...).
	8. If this was a spell rename, document that rename in the Grimoire
	  ChangeLog.

When this process is used, a user casting the deprecated old will get new
installed, removing old in the process.

Change all the spells that depended in any way on the deprecated spell to
either point to the new one or simply remove the depends if it isn't needed
anymore.

Deprecated spells should be removed from the test grimoire once the
deprecation has made its way to stable.

If the deprecation is a rename, and the old spell had some persistent
variables from configuration settings (CONFIGURE or PREPARE), you should
transfer those settings as defaults to the new spell. Basically, no user
settings should be lost. So how do you do that?
	1. Create old/EXPORTS and put all persistent variables you want to
	  transfer in it, one variable name per line.
	2. Create old/REPAIR^none^EXPORTS with the exact same content (as the
	  EXPORTS file gets read from the tablet, see REPAIR FILES).
	3. Use persistent_read old OLD_VARIABLE VARIABLE_DEFAULT in new/PREPARE
	  or new/CONFIGURE.
	4. Use ${VARIABLE_DEFAULT:-new_default} as default setting for the
	  corresponding variable in the new spell.

	Subsection: ChangeLog
Any addition/deletion/move of a spell in a grimoire(s) requires a ChangeLog
entry in the affected grimoire(s). Modifying any of the grimoire generic
files (e.g. FUNCTIONS) or non-spell specific files (such as section-wide
files) also requires a ChangeLog entry.

The reason to include new spells in the ChangeLog, although they technically
have their own change logs (the spell HISTORY files) is that sorcery will offer
to show the grimoire ChangeLog on a scribe udpate. With new spells in there
it's easy to see what's been added.

The format of ChangeLog entries is as follows (all lines should be wrapped
to <80 columns):
<date>[space]<name>[space]<e-mail address>
[tab]*[space]<modified filename>[colon][space]<description>
[tab][space][space]<extra description for this file>
[tab]*[space]<modified filename>[colon][space]<description>
[tab][space][space]<extra description for this file>
[newline]

Example:
2006-11-13 Eric Sandall <sandalle@sourcemage.org>
	* FUNCTIONS: Modifyed nspr_update to not fail if the patch doesn't exist
	  since firefox 2.0 does not require the nss security patch.

2006-10-13 Andrew Stitt <astitt@sourcemage.org>
	* groups: Added smgl:158 group for SMGL services
	* accounts: Added sorcery:157:157 user for building Sorcery as a non-
	  priviledged user.

	Subsection: API_VERSION
This file defines which API version a package, section, or entire grimoire
uses. All packages below where this is defined use the stated API version
unless a package or section below overrides it.

	Subsection: Repair files
Repair files are used for replacing spell files or section/grimoire libraries
in the tablet.

REPAIR files can be in spell directories, section directories or the grimoire
base.

The format of the filename is: REPAIR^ID^FILENAME

FILENAME can be anything, its not limited to spell files, you can replace a
patch file if you really want to.

ID can be one of the four things:
	* a spell's version
	* a spell's UPDATED field
	* the md5sum of FILENAME
	* the exact string 'none'

The first two are relatively straightforward, if FILENAME exists in the
spell/section/grimoire dir and the spell's version or updated field matches ID,
then the file is replaced. If the md5sum of the file in the tablet is the same
as ID then the file is replaced. (remember that theres a section/grimoire dir
for each spell).

If the file does NOT exist in the tablet, AND the value of ID is 'none' the
file is added.

So, you can replace any spell file, or section/grimoire library very easily
now. It doesnt make a whole lot of sense to use the version or updated values
for section and grimoire files, but they're there if you want it.

An optimization is put in place such that if we are going to replace the file
and the file's md5sum is the same as the repair file we skip the replace since
the replace has presumably already been done.

Cache files are not updated at this time.

The entire tablet is scrubbed after each scribe update. `cleanse --tablet` also
will do this. There is an additional option to cleanse, --tablet_spell which
takes a single parameter as a spell name to scrub so you can quickly verify
that things are working without scrubbing the entire tablet.

TODO:
	* ^all^
	  Allow special keyword 'all' to unconditionally update a file in the
	  tablet, bug 10869
	* anything else that changed

Repair files dont apply to trigger registration, which is done during cast,
they repair files that will be executed at a later date. So there is little
point in repairing TRIGGERS or UP_TRIGGERS.

	Subsection: FUNCTIONS
A grimoire library for commonly used functions and readability functions.
Functions may be added if they are used in more than one package (e.g.
mozilla_remove_nspr_nss is used for all Mozilla products).

Section 6: Filters
	Subsection I: excluded

Example:
	^/home

	Subsection II: protected

Example:
	^/bin/awk$

	Subsection III: volatiles
This filter contains a list (can be regular expressions) of files that are
known to change (e.g. gconf configuration files, modified by almost every
GNOME package). We know these files will change and that they are supposed
to change, so here we mark them so `cleanse` is aware and will not report
them as broken.

Example:
	^/etc
This marks all files in /etc as known to be changeable and still be
considered okay.

Section 7: Compatibility
	Subsection I: libcompat
This library is used for forward compatibility with the next release of
Sorcery. Dummy functions for future Sorcery functions are added here so
that the grimoire developers may work in advance to have these features
supported once the new features are available in a stable Sorcery release.

	Subsection II: libgcc
This library adds multi-gcc version support (used to set which gcc version
a package is compiling with).

Section 8: Accounts
	Subsection I: libaccount
This grimoire library contains functions for creating, checking, and
retrieving information about account and group information.

	Subsection II: accounts
Accounts used by programs (usually daemons) during their operation. When
adding an account with a group, add the group first as you will need to
know the group id (GID) in advance. The format of account entries is:
	<account>:<UID>:<Primary GID>:<GID>:<GID>:... etc.
where UID is the prior listed UID + 1.

Example:
	musicdaemon:155:29
	iplog:156:156			<--- This is the one we just added
	(note that the GID is from the groups example below)

	Subsection III: groups
Groups used by programs (usually daemons) during their operation. The format
of group entries is:
	<group>:<GID>:
where GID is the prior listed GID + 1.

Example:
	powerdev:155:
	iplog:156:		<--- this is the one we just added

Appendix:
	* File Hierarchy Standards
	  See http://www.pathname.com/fhs/2.2/
	* Keywords
	* Licenses
	  See http://wiki.sourcemage.org/LicenseList
	* Linux Standards Base
	  See http://www.freestandards.org/en/LSB



M GrimoireGuruHandbook.tex => GrimoireGuruHandbook.tex +3 -0
@@ 1382,6 1382,9 @@ Example:
	^/bin/awk$
\end{verbatim}

Files listed in protected will not be dispelled by Sorcery itself and are
expected to be handled by the spell itself.

\section{volatiles}
This filter contains a list (can be regular expressions) of files that are
known to change (e.g. gconf configuration files, modified by almost every