[SourceMage_Wiki] [TitleIndex] [WordIndex

Spellwriting for Dummies

v 1.8

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the no invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found here.

Introduction: Why should you read this book?

Let's start off with some pretty standard stuff. The author (that's me Torgeir Ulvedal Nes; I have always wanted to call myself an author-Nobel prize here I come) is in no way whatsoever responsible for what happens to you from reading this document. If you print out this document and walk peacefully along the street reading it and suddenly get hit by a bus, or sue someone else (like the driver of the bus) the author is not liable for damages. Or you might find that the Grimoire team gets pissed because you write bad spells. Hopefully this will not happen, but who knows.

Also this is just a way I have found which makes the process of writing a spell easier. If you find this method stupid don't use it. But for me it works excellently.

Suggested Note: It is also possible to use Quill to do most of the work for you ;) -- ShadowScythe

Preliminary work: Making the real work easier.

Create your own local grimoire and populate it with a section and a spell template (named default).

Note: Placing your spells under a section directory (ex: mysection) is a requirement.

Now you need to let sorcery know about your grimoire, this is done through the /etc/sorcery/local/grimoire file: GRIMOIRE_DIR[0]=/var/lib/sorcery/codex/stable This is what it looks like if you only have the stable grimoire, there may be more entries for additional grimoires like games or z-rejected. Now add a new line to that file for your new grimoire: GRIMOIRE_DIR[1]=/home/user/mygrimoire

The reason for adding your personal grimoire to the end is so that when your spells get into the official grimoire, possibly corrected by the Grimoire team, the corrected spell will be cast, even if you forget to remove the spell from mygrimoire. (Making your personal grimoire the first one in the list can be useful if you want to have your own version of an official spell, since sorcery searches for spell in the grimoire order defined in /etc/sorcery/local/grimoire.)

Now let's move back to ~/mygrimoire/mysection/default/.

What you have done is created the three files most basic spells need. The DEPENDS file is optional. (I keep forgetting to chmod +x so when I have those two files in the default spell, I'm pretty much in the clear.) Two other common spell files are not included right now: BUILD and INSTALL. By omitting these files, you tell cast to use the default_build and default_install functions. It would be nice to check the wiki-pages on these files. This way you might know that what you're doing is just running a script that takes care of the usual ./configure && make && make install recipe, but in a more sorcerous way. The reference for the spellfiles is found here.

Generate the SHA512 Hash

You will need to generate a SHA512 hash sum of the package you are creating the spell for. You can cast the hashsum spell which will give you a few utilities, one of which is the sha512sum command. Simply perform the following to generate a SHA512 sum:

$ sha512sum <spell-source>

This will simply output the hash, which is what you'll need for the next step. Note that if you are editing an existing spell, do not change the sha512sum without verifying what has changed in the upstream tarball. The sha512 sum is the primary means of integrity verification for upstream sources and a sha512 failure indicates a change that needs to be looked at.

The DETAILS File

Now we are editing the DETAILS file of the default spell. What we are going to put in here is as follows:

           SPELL=(name of program)
         VERSION=(current stable version)
          SOURCE=$SPELL-$VERSION.tar.gz
SOURCE_DIRECTORY=$BUILD_DIRECTORY/$SPELL-$VERSION
   SOURCE_URL[0]=http://(download address)/$SOURCE
        WEB_SITE=http://(website address)
         ENTERED=20060526 (change this to when you wrote the spell)
     SOURCE_HASH=sha512:(sha512 hash of the source file)
      LICENSE[0]=(see http://wiki.sourcemage.org/LicenseList for acceptable license abbreviations, else include the license URL)
           SHORT="(a short description of the program (it shouldn't exceed 80 characters))"
cat << EOF
(a longer description of the program)
EOF

The clue here is that the "=" should be lined up. This is really important. If this starts getting out off hand, suddenly people will think you don't need to have line breaks in the file. and just write everything on one line. So remember: Other people will read your spells. If you forget this, the Grimoire team will come to your house to kick your ass! Just like in Jay and Silent Bob Strike Back.

Now put the following in the HISTORY file:

 2006-05-26  Your Name <your e-mail address>
        * DEPENDS, DETAILS, HISTORY: created this spell

Please note that there is only one tab and that is the only time and place a tab is ever used in any of the spell files. At all other times, spaces are used instead.

Now it is time to get ready to write your first spell.

Your first spell: This is the exciting part !

Since you are reading this I presume your favorite program is not yet in the Grimoire. Do not despair. It will be soon. So now we put on our pointy wizard hats, and get down to business. First you need to go to freshmeat, sourceforge or the program's homepage. Do the following:

"name" = usually the name of the program as it appears in the file you will download

Edit the contents as follows:

        SPELL="name"
      VERSION="version also as it appears in the filename"
       SOURCE=$SPELL-$VERSION.tar.gz
SOURCE_URL[0]=http://(download address)/$SOURCE

where "(download address)" = absolute path excluding filename. Note that $SOURCE is built from $SPELL + $VERSION.

If the name of spell does not correspond with the name of file you must modify SOURCE too:

        SPELL=blablabla
       SOURCE=BlaBlaBla-$VERSION.tar.bz2

Then edit the HISTORY file and put the correct date in there. Now exit your editor, and hold on, now the fun is about to begin.

To update your local codex with the new spell:

If you are like me you normally write cast "whatever" press enter, and quickly jump to another tty to do something useful! Please don't. Instead cast "name" and watch what happens, because we are now moving into the next chapter... What do to if the spell doesn't work.

The spell doesn't work: What to do.

After you pressed return at the end off last chapter one of three things can happen.

The spell works: :Damn, you're really good! :Go to Chapter 5: Cleaning up

The download won't start! :Check to see if you wrote the download URL right. :Check that the file exists on the given URL :Ask someone else for help

The spell fails: :!!! Problem Detected !!! appears on your monitor. :It's time to start pulling your hair, screaming in despair! :And then start the debugging.

A common error is that it can't find configure. Do a {ls /usr/src/}}} and see if you have a directory that is named "name". If you do, change

to

try to cast again.

In case you wonder why you did this. BUILD_DIRECTORY is /usr/src. Normally programs put their source code in a directory named "name of program"-"version of program" but some developers find out that they wanna be smart and call the directory just "name of program" hence you have to change the name so cast will know where to find the source code. If it still does not work you normally have to make a BUILD file.

Ask at the #sourcemage irc channel on irc.freenode.net or just figure it out!

If it gets a bit out in the configure part and then fails miserably, it is probably a missing dependency. Often the configure log will indicate what dependency is missing, otherwise check the documentation for the program. It will probably not say anything about it since developers are often hopeless when it comes to telling you what their program depends on. So then read the compile log gaze compile "name" to see if you can figure yout what is missing. Right before !!! Problem Detected !!! the name off the missing file should appear. Then you just have to figure out which package gives that file, which can be done with the gaze command.

Or ask at the #sourcemage irc channel on irc.freenode.net. If you have long errors, you can paste them into #sourcemage-dump. Please do not paste anything in other sourcemage irc channels.

When you know the name off the missing program open DEPENDS and insert

remember no && after the last entry. See DEPENDS for more information on that file.

After going through some massive debugging. Your spell should soon be ready for the grimoire. We just have to finish it off!

The spell works: Congratulations!

This is the part of spell writing I find kinda boring! But it is really important. So just hang in there.

Checklist

That just about does it. Now you just have to submit the spell.

Submit a spell at http://bugs.sourcemage.org/, under the "New Spells" module. Please remember to include the name of the spell (and only one spell per bug, otherwise it gets messy and annoys maintainers ;)) and it's section in the body along with a description of the spell and it's tarball. Don't forget to submit the tarball. See: Spell_Submission

The greatest source of information on how to write spells resides locally on your hard drive. Read other people's spells and you will learn how to write your own great spells.

Have fun!

Notes

TO-DO

Any comment on this document can be sent to torgeir@nes.ac

Hope it has been of some help!


2013-02-24 16:25