[SM-Commit] GIT changes to master tome rdp by Eric Sandall (9b76c1add038f3f6fb415f26eb7c0d10674403e2)

Eric Sandall scm at mail.sourcemage.org
Sun Jan 7 21:52:00 EST 2007


GIT changes to master tome rdp by Eric Sandall <sandalle at sourcemage.org>:

 GrimoireGuruHandbook |  553 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 536 insertions(+), 17 deletions(-)

New commits:
commit 9b76c1add038f3f6fb415f26eb7c0d10674403e2
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add header for PRE_SUB_DEPENDS

commit abf5c4ea899d54f1fcb5096a806f0613c574cbcc
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add TRIGGERS to GrimoireGuruHandbook

commit 3901ec0772fcc32f510c6ecfadbd17780641752a
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add repair files to GrimoireGuruHandbook

commit 2f75a5f8e25def7fc98941545ce3d1e42692a445
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Reorganize PRE_RESURRECT and POST_RESURRECT in GrimoireGuruHandbook

commit f59c20c2ce6f25850dad6d26eb23cd36fab2830a
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add PROVIDES to GrimoireGuruHandbook

commit 727481dc4e160afcb9585bda2a4a41ecd79fd978
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add POST_REMOVE to GrimoireGuruHandbook

commit eff18ed71b4365071cb4d10872c296194756172f
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add PRE_REMOVE to GrimoireGuruHandbook

commit 77c1cdb0e0e5d876664fdcdbdd31d426c4586157
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add section headers for PRE_REMOVE, POST_REMOVE, PRE_RESURRECT, and POST_RESURRECT to GrimoireGuruHandbook

commit 6884948f0f29145c71bf4ce6c15cda4c354f72e8
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Remove Subsection numbers until organization is complete in GrimoireGuruHandbook

commit ff6b13501e9d83944779c09dae9c749b937e351e
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add FINAL to GrimoireGuruHandbook

commit bac9cdf76bcf1a6781b7188946ee0b1b4d7a72fd
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add INSTALL to GrimoireGuruHandbook

commit fb80b4635f60ba15128d2b47b2600fa368870fd5
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add PRE_INSTALL to GrimoireGuruHandbook

commit b13531ec5b2c0c482c49182ca85d426cec5581fc
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add PRE_BUILD to GrimoireGuruHandbook

commit 903e2f57b1203fdbd0a6f8b235c06e6343acb295
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add CONFLICTS to GrimoireGuruHandbook

commit 8d74dc9a1a2f4b55b9642a806b1901c137530224
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add reasoning to some ChangeLog usage in GrimoireGuruHandbook

commit d2e667dcaae68abf166c79003bd4a71ca08d27c5
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add multi-version support information to PREPARE and DETAILS in GrimoireGuruHandbook

commit 077f6e61a20dab59dd95c680c46e76148e1cb2dc
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add CONFIGURE to GrimoireGuruHandbook

commit 0cdcf3e77f15b839d5853973721a96388d60cde5
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add DETAILS to GrimoireGuruHandbook

commit 0fba144dd344ac0ee071068618843c30f077c126
Author: Eric Sandall <sandalle at sourcemage.org>
Commit: Eric Sandall <sandalle at sourcemage.org>

    Add PREPARE to GrimoireGuruHandbook

diff --git a/GrimoireGuruHandbook b/GrimoireGuruHandbook
index 4214364..0ed7513 100644
--- a/GrimoireGuruHandbook
+++ b/GrimoireGuruHandbook
@@ -198,19 +198,460 @@ stable-rc-0.6), you will use the followi
 	  and then up to the server (origin).
 
 Section 5: Writing a spell
-	Subsection I: DETAILS
-	Subsection II: PREPARE
-	Subsection III: CONFIGURE
-	Subsection IV: DEPENDS
-	Subsection V: PRE_BUILD
-	Subsection VI: BUILD
-	Subsection VII: PRE_INSTALL
-	Subsection VIII: INSTALL
-	Subsection IX: FINAL
-	Subsection X: TRIGGERS
-	Subsection XI: UP_TRIGGERS
-	Subsection XII: SUB_DEPENDS
-	Subsection XIII: HISTORY
+	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>
@@ -230,7 +671,28 @@ Example:
 	* DEPENDS: Added optional dependency on foo
 	  Removed dependency on bar (bogus entry)
 
-	Subsection XIV: Deprecation
+	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
@@ -275,12 +737,17 @@ settings should be lost. So how do you d
 	4. Use ${VARIABLE_DEFAULT:-new_default} as default setting for the
 	  corresponding variable in the new spell.
 
-	Subsection XV: ChangeLog
+	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>
@@ -300,12 +767,64 @@ Example:
 	* accounts: Added sorcery:157:157 user for building Sorcery as a non-
 	  priviledged user.
 
-	Subsection XV: API_VERSION
+	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 XVI: FUNCTIONS
+	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).



More information about the SM-Commit mailing list