-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathGrimoireGuruHandbook.tex
1459 lines (1228 loc) · 45.7 KB
/
GrimoireGuruHandbook.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\documentclass[a4paper,10pt]{book}
\begin{document}
\title{Grimoire Guru Handbook v3.0}
\begin{titlepage}
\begin{center}
\begin{Huge}
Grimoire Guru Handbook v3.0
\end{Huge}
\begin{LARGE}
for Source Mage GNU/Linux (http://www.sourcemage.org/)
\end{LARGE}
\end{center}
\end{titlepage}
\chapter{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 [email protected] 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\footnote
{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.
\chapter{Bug tracking}
We are currently using Bugzilla, which is accessible from
http://bugs.sourcemage.org/.
\section{Creating an account}
\section{Searching for bug reports}
\section{Creating a bug report}
\section{Taking ownership of a bug}
\section{Requesting integration to stable(-rc)}
\chapter{Patch creation}
We prefer patches to be submitted with the diff options -Naur.
\chapter{SCM Usage}
\section{Requesting an account}
Here I am assuming you have been invited to obtain write permissions to our
repositories.
Send an e-mail to [email protected] 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:
\begin{verbatim}
$ ssh-keygen
\end{verbatim}
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/.
\section{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:
\begin{itemize}
\item[cauldron] ISO scripts and configuration files
\item[grimoire] Master grimoire repository
\item[grimoire/games] Games grimoire repository
\item[grimoire/xorg-modular] Development work on modular X.org
\item[grimoire/z-rejected] Grimoire for binary packages and ones with licensing
issues
\item[misc/archspecs] Architecture specifications
\item[misc/prometheus] Spell QA script
\item[misc/quill] Spell updater/creator script
\item[sorcery] Our package manager
\item[tome/rdp] Rogue Documentation Project
\end{itemize}
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:
\begin{verbatim}
$ git clone ssh://scm.sourcemage.org/smgl/grimoire
\end{verbatim}
This will create a directory called 'grimoire' in your current directory.
\section{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:
\begin{verbatim}
[user]
name = Eric Sandall
email = [email protected]
\end{verbatim}
\section{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/)
\begin{verbatim}
$ git pull
\end{verbatim}
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.
\section{Viewing local branches}
Local branches are branches made by you, with only one, ``master'', being
created for you. To view your local branches, run:
\begin{verbatim}
$ git branch
* master
\end{verbatim}
The "*" before "master" means that this is the currently checked out
(working) branch. You may modify local branches as much as you want and you
will not affect anyone else until you push your changes back to the server
(see below).
\section{Viewing remote branches}
The main grimoire that you have checked out has many branches. You may view
the available remote branches by running:
\begin{verbatim}
$ git branch -r
origin/HEAD
origin/devel
origin/devel-iceweasel
origin/devel-shadow
origin/master
origin/stable-0.3
origin/stable-0.4
origin/stable-0.6
origin/stable-0.7
origin/stable-0.8
origin/stable-rc-0.4
origin/stable-rc-0.5
origin/stable-rc-0.6
origin/stable-rc-0.7
origin/stable-rc-0.8
\end{verbatim}
All of the branches listed with origin/ are 'remote' branches, ones that are
available for everyone to use.
\section{Selecting your working branch}
To checkout another branch (say origin/devel) to work on, you would run:
\begin{verbatim}
$ git checkout -b devel origin/devel
Switched to a new branch "devel
\end{verbatim}
Now check what local branches you have
\begin{verbatim}
$ git branch
* devel
master
\end{verbatim}
You are now working on a local branch of origin/devel called ``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.
\section{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
\begin{enumerate}
\item Make sure we are up-to-date with upstream
\begin{verbatim}
$ git pull
\end{verbatim}
\item Make necessary changes to the git files
\begin{verbatim}
$ cd devel/git
$ vi DETAILS HISTORY
\end{verbatim}
Change VERSION from 1.4.3.4 to 1.4.3.5
Add update entry to HISTORY
\item Mark the files you wish to update
\begin{verbatim}
$ git update-index DETAILS HISTORY
\end{verbatim}
\item Check which files are slated to be committed
\begin{verbatim}
$ git status
# Updated but not checked in:
# (will commit)
#
# modified: devel/git/DETAILS
# modified: devel/git/HISTORY
#
\end{verbatim}
\end{enumerate}
\section{Committing changes}
Now that we have made our modifications, we should submit them. To commit
all of your flagged files (from `git status`), run:
\begin{verbatim}
$ git commit
\end{verbatim}
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:
\begin{verbatim}
$ git commit DETAILS HISTORY
\end{verbatim}
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:
\begin{verbatim}
$ git commit -m "git: Updated to 1.4.3.5"
\end{verbatim}
If ever you make changes you wish to undo, before running `git commit`, you
may run the following:
\begin{verbatim}
$ git checkout -f <list of files to revert to origin>
\end{verbatim}
Note that `git commit` only updates your local copy of the repository, not
the server repository where everyone pulls from.
\section{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:
\begin{verbatim}
$ git push <destination> <source>
\end{verbatim}
Since we are working in master and want to push to the upstream server, we
would run:
\begin{verbatim}
$ git push origin master
\end{verbatim}
Note that destination will almost always be 'origin'.
\section{Resolving conflicts}
When you receive a conflict (usually denoted by the lines):
\begin{verbatim}
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.
\end{verbatim}
Inside the conflicting file you will see the line \begin{verbatim}<<<<<
.merge_file_stuff\end{verbatim},
which begins the new changes, and a \begin{verbatim}>>>>>>
.merge_file_otherstuff\end{verbatim}, which
ends the new changes. Once you resolve the conflict by editing the file
and remove what should not be there, you will run \textdollar git update-index
<files>
and then commit your changes.
\section{Creating your own local branch}
If you are planning on doing an update which might take a while (e.g.
openoffice) you will want to work in your own branch, so you only have to
resolve conflicts once when you merge back to the master branch.
\begin{enumerate}
\item First, make sure we're up-to-date, no point in missing any
commits ;)
\begin{verbatim}
$ git checkout master
$ git pull
\end{verbatim}
\item Now we'll create our own local branch and check it out in one
command
\begin{verbatim}
$ git checkout -b devel-openoffice
Switched to a new branch "devel-openoffice
\end{verbatim}
We may now proceed the long process of getting openoffice to compile. Commit
as often as you want to this branch, it won't hurt anyone. When you want to
work on the rest of the grimoire again, make sure everything is commited and
then checkout ``master'' (or whichever branch you want to work on) and proceed
as normal, devel-openoffice will always be waiting for you. :)
\end{enumerate}
\section{Checking out other branches}
Checking out another branch will allow you to work on it. Let's say we have
the following remote branches:
\begin{verbatim}
$ git branch -r
origin/HEAD
origin/devel
origin/devel-iceweasel
origin/devel-java
origin/devel-oo
origin/devel-shadow
origin/master
origin/origin
\end{verbatim}
Now, we'd like to try out some of the shadow work that's going on, so let's
check it out.
\begin{verbatim}
$ git checkout -b shadow origin/devel-shadow
Switched to a new branch "shadow"
$ git branch
master
* shadow
\end{verbatim}
We now have our own local ``shadow'' branch to play with, which is linked to
the upstream origin/devel-shadow.
\section{Deleting a local branch}
Sometimes a branch is a lost cause, or already merged and no longer needed.
You will need to not have the soon to be deleted branch checked out
(``master'' is always a good branch to hang out in) and then you may delete it:
\begin{verbatim}
$ git checkout master
$ git branch -d devel-openoffice
\end{verbatim}
This will only delete the branch if it has been fully merged. If this is a
lost cause branch, feel free to be more forceful:
\begin{verbatim}
$ git branch -D devel-openoffice
\end{verbatim}
This will remove ``devel-openoffice'' no matter its status.
\section{Renaming a local branch}
If you no longer like the name you've given to a remote branch, fear not!
Renaming is as simple as ``branch -m <old branch> <new branch>'':
\begin{verbatim}
$ git branch -m devel-openoffice openoffice
\end{verbatim}
\section{Creating your own remote branch}
We have our devel-openoffice branch on our machine, but others are wanting to
help with it, so we'll push it to the upstream grimoire.git on sourcemage.org.
\begin{enumerate}
\item Check out the branch we wish to push
\begin{verbatim}
$ git checkout devel-openoffice
\end{verbatim}
\item Now we push our currently checked out branch onto the remote
\begin{verbatim}
$ git push ssh://scm.sourcemage.org/smgl/grimoi
re devel-openoffice:devel-openoffice
updating 'refs/heads/devel-openoffice'
from 0000000000000000000000000000000000000000
to fa9869a20bbfb479fafd63ef41e890919df3b6d9
Generating pack...
Done counting 0 objects.
Writing 0 objects.
Unpacking 0 objects
refs/heads/foo: 0000000000000000000000000000000000000000 ->
fa9869a20bbfb479fafd63ef41e890919df3b6d9
Total 0 (delta 0), reused 0 (delta 0)
\end{verbatim}
\item We'll need to go back to master for some updates
\begin{verbatim}
$ git checkout master
$ git pull
* refs/remotes/origin/devel-openoffice: storing branch 'devel-openoffice' of
/home/sandalle/tmp/grimoire/
commit: fa9869a
Already up-to-date.
\end{verbatim}
devel-openoffice should now be a remote branch
\item Check that devel-openoffice is remote
\begin{verbatim}
$ git branch -r
origin/HEAD
origin/devel-openoffice
origin/master
\end{verbatim}
\end{enumerate}
You are now set to collaborate on the devel-openoffice branch with other
developers. :)
\section{Integrating between branches}
Let's say we want to merge some fixes from our test (``master'') grimoire into
stable-rc and stable. To update one of these (say stable-rc-0.8), you will use
the following steps:
\begin{enumerate}
\item Checkout the the origin/stable-rc-0.8 branch and call it stable-rc-0.6
locally.
\begin{verbatim}
$ git checkout -b stable-rc-0.8 origin/stable-rc-0.8
\end{verbatim}
\item Merge (cherry-pick) the commit id you want (in this example,
fa9869a20bbfb479fafd63ef41e890919df3b6d9) into the current branch
\begin{verbatim}
$ git cherry-pick fa9869a20bbfb479fafd63ef41e890919df3b6d9
\end{verbatim}
\item Synchronize the local stable-rc-0.8 with upstream origin/stable-rc-0.8
\begin{verbatim}
$ git pull origin origin/stable-rc-0.8
\end{verbatim}
\item Push your changes from stable-rc-0.8 into origin/stable-rc-0.8 and then
up to the server (origin).
\begin{verbatim}
$ git push origin stable-rc-0.8:origin/stable-rc-0.8
\end{verbatim}
\end{enumerate}
\section{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.8 was just released, and your current local branches
look like this:
\begin{verbatim}
$ git branch -r
origin/HEAD
origin/devel
origin/devel-iceweasel
origin/devel-shadow
origin/master
origin/stable-0.3
origin/stable-0.4
origin/stable-0.6
origin/stable-rc-0.4
origin/stable-rc-0.5
origin/stable-rc-0.6
origin/stable-rc-0.7
\end{verbatim}
New remote branches will automatically be added on your next pull, so just run
(preferably with the local master checked out):
\begin{verbatim}
$ git pull
\end{verbatim}
And then you should now have the new remote branches:
\begin{verbatim}
$ git branch -r
origin/HEAD
origin/devel
origin/devel-iceweasel
origin/devel-shadow
origin/master
origin/stable-0.3
origin/stable-0.4
origin/stable-0.6
origin/stable-0.7
origin/stable-0.8
origin/stable-rc-0.4
origin/stable-rc-0.5
origin/stable-rc-0.6
origin/stable-rc-0.7
origin/stable-rc-0.8
\end{verbatim}
\chapter{Writing a spell}
\section{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:
\begin{verbatim}
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:[email protected]:/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
\end{verbatim}
DETAILS:
\begin{verbatim}
VERSION=${PREPARE_VERSION:-"2.1.3"}
SOURCE=$SPELL-$VERSION.tar.bz2
SOURCE_URL[0]=${PREPARE_SOURCE_URL[0]:-http://www.fun.org/download/$SOURCE}
\end{verbatim}
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:
\begin{itemize}
\item[SOURCE\_CACHE] the directory where the sources reside:
/var/spool/sorcery
\item[SCRIPT\_DIRECTORY] the spell script directory in the codex:
/path/to/grimoire/section/spell
\item[SPELL\_DIRECTORY] this is the same as \textdollar SCRIPT\_DIRECTORY and
is deprecated
\item[SECTION\_DIRECTORY] path/to/grimoire/section
\item[GRIMOIRE] /path/to/grimoire
\end{itemize}
For more info on these variables, check /var/lib/sorcery/modules/libcodex
An important usecase for PREPARE is in multi version spells.
\section{DETAILS}
This file contains information about the application which the spell is for.
\subsection{SPELL}
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:
\begin{verbatim}
SPELL="xzgv"
\end{verbatim}
\subsection{VERSION}
VERSION
This specifies the current version number of the application in
question. Please be exact.
Example:
\begin{verbatim}
VERSION="0.7"
\end{verbatim}
\subsection{SOURCE}
SOURCE
Specifies the name of the source file of the application. Must be the
full name not including any path information.
Example:
\begin{verbatim}
SOURCE="$SPELL-$VERSION.tar.gz"
\end{verbatim}
SOURCEn
Specifies the names of additional source files for the application.
The numbering starts with 2.
Example:
\begin{verbatim}
SOURCE2="xzgv-addons.tar.gz"
\end{verbatim}
\subsection{SOURCE\_DIRECTORY}
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
\textdollar SPELL-\textdollar VERSION, or perhaps just \textdollar
SPELL etc.). \textdollar 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:
\begin{verbatim}
SOURCE_DIRECTORY=$BUILD_DIRECTORY/$SPELL-$VERSION
\end{verbatim}
\subsection{SOURCE\_URL}
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:
\begin{verbatim}
SOURCE_URL[0]=http://xzgv.browser.org/$SOURCE
\end{verbatim}
SOURCEn\_URL[*]
Arrays specifying the download links for additional SOURCEn entries.
The numbering starts with 2 (SOURCE2\_URL).
Example:
\begin{verbatim}
SOURCE2_URL[0]=http://xzgv.browser.org/$SOURCE2
\end{verbatim}
\subsection{FORCE\_DOWNLOAD}
FORCE\_DOWNLOAD=on
When set to 'on', the source will be downloaded by sorcery,
regardless of it being present in the spool directory.
Example:
\begin{verbatim}
FORCE_DOWNLOAD=on
\end{verbatim}
Example:
\begin{verbatim}
FORCE_DOWNLOAD[2]=on
\end{verbatim}
for SOURCE2 not SOURCE[2]!
Example:
\begin{verbatim}
FORCE_DOWNLOAD[n]=on
\end{verbatim}
for SOURCEn not SOURCE[n]!
\subsection{SOURCE\_HASH}
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:
\begin{verbatim}
SOURCE_HASH=sha512:<hash>:UPSTREAM_HASH
(actual hash ommited due to insane length)
\end{verbatim}
\subsection{SOURCE\_GPG}
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:
\begin{verbatim}
SOURCE_GPG="gurus.gpg:$SOURCE.sig:WORKS_FOR_ME"
\end{verbatim}
\subsection{SOURCE\_IGNORE}
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:
\begin{verbatim}
SOURCE2_IGNORE=signature
\end{verbatim}
\subsection{WEB\_SITE}
WEB\_SITE
Used to document the applications "official" website (if there is one).
Example:
\begin{verbatim}
WEB_SITE=http://xzgv.browser.org/
\end{verbatim}
\subsection{ENTERED}
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:
\begin{verbatim}
ENTERED=20020406
\end{verbatim}
\subsection{UPDATED}
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:
\begin{verbatim}
UPDATED=20020406
\end{verbatim}
\subsection{PATCHLEVEL}
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:
\begin{verbatim}
PATCHLEVEL=2
\end{verbatim}
\subsection{SECURITY\_PATCH}
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:
\begin{verbatim}
SECURITY_PATCH=3
\end{verbatim}
\subsection{LICENSE}
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:
\begin{verbatim}
LICENSE[0]=GPL
\end{verbatim}
\subsection{KEYWORDS}
KEYWORDS
\subsection{SHORT}
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:
\begin{verbatim}
SHORT="xzgv is a GTK+/Imlib-based picture viewer for X."
\end{verbatim}
\subsection{DOCS}
DOCS Optional tag used to override the implicit DOCS variable to change what
docs are installed.
Example:
Implicit DOCS:
\begin{verbatim}
DOCS="README* FAQ* CHAN* doc* DOC* conf SETUP LICENSE COPYING NEWS"
\end{verbatim}
New DOCS:
\begin{verbatim}
DOCS="README* BUGS NEWS COPYING data/COPYING.* docs/html docs/example.lircrc"
DOCS="$DOCS etc/*.conf"
\end{verbatim}
\subsection{DESCRIPTION}
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:
\begin{verbatim}
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
\end{verbatim}
\section{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:
\begin{verbatim}
persistent_add VAR BLAH SPELL_OPTION
\end{verbatim}
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:
\begin{itemize}
\item[config\_query]
\item[config\_query\_string]
\item[config\_query\_list]
\item[config\_query\_option]
\item[config\_query\_multi]
this is GRIMOIRE FUNCTIONS specific for the time being
\end{itemize}
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:
\begin{verbatim}
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
\end{verbatim}
config\_query\_option is a bit different, it does not overwrite content of
\textdollar SPELL\_OPTION, rather the result is appended to it. If you want to
use the parameters passed via config\_query\_option, you will need to manually
add it. This is generally done in BUILD with:
\begin{verbatim}
OPTS="$SPELL_OPTION \
$OPTS" &&
default_build
\end{verbatim}
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
\begin{verbatim}
source $GRIMOIRE/config_query_multi.function
\end{verbatim}
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.
\section{DEPENDS}
\subsection{depends}
Denotes that a spell requires another spell to work.
Syntax:
\begin{verbatim}
depends <'spell'> ['flags'] ['description'] ['grimoire']
\end{verbatim}
Example: This package requires gtk+2 to be installed before compiling
\begin{verbatim}
depends 'gtk+2'
\end{verbatim}
Example: This package requires gtk+2 to be installed before compiling and
needs '--with-gtk' passed to ./configure
\begin{verbatim}
depends 'gtk+2' '--with-gtk'
\end{verbatim}
Example: This package requires a provider of GECKO before compiling
\begin{verbatim}
depends 'GECKO'
\end{verbatim}
Example: This package requires a provider of JDK, available only in the
z-rejected grimoire, before compiling:
\begin{verbatim}
depends 'JDK' '' '' 'z-rejected'
\end{verbatim}
\subsection{optional\_depends}
The given package will build added functionality if this package is installed
before compilation.
Syntax:
\begin{verbatim}
optional_depends <'spell'> \
<'enabling flags'> \
<'disabling flags'> \
<'description'> \
['grimoire']
\end{verbatim}
Example: Optionally require gtk+2 for a GTK based GUI
\begin{verbatim}
optional_depends 'gtk+2' \
'--enable-gui' \
'--disable-gui' \
'for a GTK+-based GUI'
\end{verbatim}
Example: Optionally require JAVA (only available in z-rejected) for a JAVA
interface.
\begin{verbatim}
optional_depends 'JAVA' \
'--with-java=$INSTALL_ROOT/usr/lib/jdk' \
'--without-java' \
'for JAVA console' \
'z-rejected'
\end{verbatim}
\subsection{sub\_depends}
Not available in Sorcery 1.13.6, so overridden in libcompat to use depends and
optional\_depends.
\subsection{suggest\_depends}
Not available in Sorcery 1.13.6, so overridden in libcompat to use
optional\_depends.
\subsection{runtime\_depends}
Not available in Sorcery 1.13.6, so overridden in libcompat to use
depends.
\subsection{force\_depends}
Causes a dependent spell to be recast when it might not otherwise be. This is
intended to be called on an already enabled dependency. It can be thought of
as an inverse of up\_trigger (although it is *not* a trigger)
\section{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:
\begin{verbatim}
conflicts freeglut
\end{verbatim}
and for multiple conflicts:
\begin{verbatim}
conflicts freeglut
conflicts openglut
\end{verbatim}
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
\begin{verbatim}
conflicts freeglut y
\end{verbatim}
\section{DOWNLOAD}
\section{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:
\begin{verbatim}
default_pre_build &&
cd $SOURCE_DIRECTORY &&
unpack_file 2 &&
patch -p0 < $SCRIPT_DIRECTORY/gcc4.patch
\end{verbatim}
Another use for this file is for spells using badly packaged sources that don't
unpack into a directory.
Example: