Skip to Content.
Sympa Menu

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

sm-commit AT lists.ibiblio.org

Subject: Source Mage code commit list

List archive

Chronological Thread  
  • From: Eric Sandall <scm AT mail.sourcemage.org>
  • To: sm-commit AT lists.ibiblio.org
  • Subject: [SM-Commit] GIT changes to master tome rdp by Eric Sandall (9b76c1add038f3f6fb415f26eb7c0d10674403e2)
  • Date: Sun, 7 Jan 2007 20:52:00 -0600

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 AT 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).



  • [SM-Commit] GIT changes to master tome rdp by Eric Sandall (9b76c1add038f3f6fb415f26eb7c0d10674403e2), Eric Sandall, 01/07/2007

Archive powered by MHonArc 2.6.24.

Top of Page