4 ___/ \__|__/ _|_ |____ ( ___) (__
7 © 1 9 9 5 S t r a y l i g h t
9 _____________________________________________________________________________
14 If you use C or the objasm assembler, and you need to use SWIs, then
15 you'll probably want to have a file defining names for all the SWIs
16 you'll be using, which you can include in any files which need it.
17 SWIList is a small program designed to generate such files.
19 There are lots of programs which do this job, although SWIList
20 provides several important features which the others don't:
22 * It's language independent. So you can use the same program to
23 generate SWI files for C, assembler, or any other language you
24 need. All you have to do is describe the language to SWIList.
26 * It doesn't just scan the modules in memory. You can drop module
27 files onto SWIList's icon in order to add their SWIs to the list.
28 SWIList also keeps a file of all the names so far, which you can
29 save, so you can add new modules easily when you obtain (or
32 _____________________________________________________________________________
39 SWIList runs when you double-click its icon in a Filer window. It
40 will add its icon to the icon bar in the traditional way. If you
41 haven't yet saved a SWI dump (see below), SWIList will take a little
42 while to read in all the modules currently loaded.
47 If you click /menu/ on the SWIList icon, the main menu will be
48 opened, from which you can choose the following options:
50 Info Displays a dialogue box showing information about the
51 SWIList application, including the version number,
52 which you should note with any bug reports.
54 Save list Displays a submenu of languages. Choosing one of
55 the items from this submenu opens a dialogue box
56 which will let you save a SWI list file in the
60 Save dump Displays a dialogue box which lets you save the
61 `SWI dump' -- a file containing all the SWI names
62 currently in memory. More information about SWI
65 Rescan modules Discards all the SWI names currently in memory and
66 rescans the loaded modules. This can take a short
69 Quit Removes the SWIList application from memory.
74 A *SWI dump* contains information about SWI names and numbers. It's
75 a binary file, not intended for `user consumption'. SWIList will
76 attempt to load the file `SWIdump' from its application directory
77 when it starts up; if it can't find this then it will scan the
78 modules in memory. This feature allows you to add to the SWIs
79 currently recognised when new modules come along, rather than having
80 to redo the whole lot from scratch.
85 In order to make SWIList language independent, all the information
86 about specific languages is contained in a file called `Format'
87 in SWIList's application directory. You can alter the existing
88 formats, or ad your own for languages which aren't already supported
91 The file's layout is fairly straightforward. The description of
92 how to format each language is held in a `chunk', headed by the
93 name of the language in square brackets (`[', `]'). (Actually, this
94 isn't quite true -- the thing in the brackets is the menu item text,
95 so we've followed it with `...' because the item leads to a dialogue
98 SWIList's output files are structured, and the format description
99 echoes this. At the top of an output file is a header. Then, for
100 each SWI-providing module, there is a header line, and this is
101 followed by a piece of text for each individual SWI. Finally, the
102 file is finished off with a footer.
104 The format for a language is divided into four sections, separated
107 1. The header text for the output. This is where you'd set up any
108 macros needed, and ensure that the file is only included once,
111 2. The header line (or lines) for each module. This is usually
114 3. The text to define each individual SWI. Don't forget to define
115 the `X' versions of the SWIs here.
117 4. The footer text for the output file.
119 The text within each section can contain *format specifiers*, which
120 are replaced with appropriate text while the file is being written.
121 A format specifier begins with a `%' character. The replacement text
122 is determined by the next character:
124 `%m' Replaced by the name of the module whose SWIs are being
125 written. This is usually used in the module separator lines.
127 `%s' Replaced by the name of the SWI currently being defined.
128 This is intended to be used when defining the individual
131 `%n' Replaced by the number of the SWI currently being defined.
132 The number is written in hex, so be sure to include the
133 appropriate specifier for the language (e.g. `&' in assembler
136 `%x' Replaced by the number of the `X' version of the SWI being
137 defined, also in hex.
139 `%p' Replaced by a `%' character, just in case you need one.
141 `%d' Replaced by the current date and time. The default format
142 of the date is determined by an entry in SWIList's `Messages'
143 file, although you can supply your own by placing it in
144 square brackets immediately after the `%d'. The syntax of
145 date formats is as described for the Alarm application,
146 and the SWI OS_ConvertDateAndTime.
148 For an example, which should help make everything clear, see the
149 `Format' file supplied.
154 The Risc PC boot system sets up a system variable `Choices$Path'
155 which allows applications to find configuration files kept separately
156 from the application directory. If you have a Risc PC, or have set
157 up the `Choices$Path' variable, SWIList will search for the `Format'
158 and `SWIDump' files there before it looks in its application
161 _____________________________________________________________________________
166 SWIList was written entirely in ARM Assembler. It gobbles large
167 amounts of memory because it's using the Sapphire library which is
168 completely excessive for SWIList's fairly modest needs. Some of the
169 more advanced features of SWIList would have been difficult to
170 implement without Sapphire however, and I doubt that I could have
171 been bothered. For example:
173 * RAM transfer support, for both loading and saving (including
174 formatted SWI list files).
176 * The format file support.
178 * The dynamic menu of formats.
180 * All the little luxuries like pointer changing and DragASprite
181 support (including the icon being hidden when it's dragged).
185 The SWIList source code uses the BASIC assembler and Straylight's
186 BASIC Assembler Supplement (BAS), which allows AOF object files
187 to be generated from BASIC; the object was then linked to the
188 Sapphire library. Sapphire was however written using Acorn's objasm
189 assembler, which was a considerably more pleasant experience.
191 _____________________________________________________________________________