diff options
author | Eric Sandall | 2007-05-15 16:52:52 -0700 |
---|---|---|
committer | Eric Sandall | 2007-05-15 16:52:52 -0700 |
commit | 7a57aa4b8384ab4bec5aca47af6dd7450fae7742 (patch) | |
tree | 44825c3258d1e105e6767b05ce06bdaa83fef462 | |
parent | e138c334481161c7c579a20043a4bf0645afce95 (diff) |
-rw-r--r-- | GrimoireGuruHandbook | 931 | ||||
-rw-r--r-- | GrimoireGuruHandbook.tex | 3 |
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 |