summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorEric Sandall2007-05-15 16:52:52 -0700
committerEric Sandall2007-05-15 16:52:52 -0700
commit7a57aa4b8384ab4bec5aca47af6dd7450fae7742 (patch)
tree44825c3258d1e105e6767b05ce06bdaa83fef462
parente138c334481161c7c579a20043a4bf0645afce95 (diff)
Remove GrimoireGuruHandbook: Old copy, now using GrimoireGuruHandbook.texHEADmaster
-rw-r--r--GrimoireGuruHandbook931
-rw-r--r--GrimoireGuruHandbook.tex3
2 files changed, 3 insertions, 931 deletions
diff --git a/GrimoireGuruHandbook b/GrimoireGuruHandbook
deleted file mode 100644
index 1e0b5de..0000000
--- a/GrimoireGuruHandbook
+++ /dev/null
@@ -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
-
diff --git a/GrimoireGuruHandbook.tex b/GrimoireGuruHandbook.tex
index 6f6e015..4519505 100644
--- a/GrimoireGuruHandbook.tex
+++ b/GrimoireGuruHandbook.tex
@@ -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