1 <!doctype linuxdoc system>
4 <!-- Title information -->
6 <title>grc65 -- GEOS Resource Compiler
7 <author><url name="Maciej 'YTM/Elysium' Witkowiak" url="mailto:ytm@elysium.pl">
8 <and><url name="Greg King" url="mailto:gngking@erols.com">
9 <date>VII 2000; VI,VII 2002; 2005-8-3
11 This document describes a compiler that can create GEOS headers and menues for
12 cc65-compiled programs.
15 <!-- Table of contents -->
18 <!-- Begin the document -->
21 <p><bf/grc65/ is a part of cc65's GEOS support. The tool is necessary to
22 generate required and optional resources. A required resource for every GEOS
23 application is the header, that is: an icon, some strings, and some addresses.
24 Optional resources might be menu definitions, other headers (e.g., for data
25 files of an app.), dialog definitions, etc. Without an application's header,
26 GEOS is unable to load and start it.
28 Currently, <bf/grc65/ supports only menues and the required header definition,
29 along with support for building VLIR-structured files.
31 <bf/grc65/ generates output in two formats: C header and <bf/ca65/ source (.s).
32 That is because the application header data must be in assembly format, while
33 the menu definitions can be translated easily into C. The purpose of the C
34 file is to include it as a header in only one project file. The assembly source
35 should be processed by <bf/ca65/ and linked to the application (read about
36 <ref name="the building process" id="building-seq">).
41 <p>grc65 accepts the following options:
44 ---------------------------------------------------------------------------
45 Usage: grc65 [options] file
47 -V Print the version number
49 -o name Name the C output file
50 -s name Name the asm output file
51 -t sys Set the target system
54 --help Help (this text)
55 --target sys Set the target system
56 --version Print the version number
57 ---------------------------------------------------------------------------
59 Default output names are made from input names with extensions replaced by
64 <sect>Resource file format
65 <p>A resource file has the name extension <tt/.grc/. That is not required, but
66 it will make for an easier recognition of the file's purpose. Also, <bf/cl65/
67 recognizes those files. <bf/grc65/'s parser is very weak, at the moment; so,
68 read the comments carefully, and write resources exactly as they are written
69 here. Look out for CAPS. and small letters. Everything after a '<tt/;/',
70 until the end of the line, is considered as a comment, and ignored. See the
71 included <ref name="commented example .grc file" id="example-grc"> for a
72 better view of the problem.
75 <sect1>Menu definition
77 MENU menuName leftx,topy <ORIENTATION> {
78 "item name 1" <MENU_TYPE> pointer
80 "item name x" <MENU_TYPE> pointer
82 The definition starts with the keyword <tt/MENU/, then goes the menu's name,
83 which will be represented in C as <tt/const void/. Then are the co-ordinates
84 of the top left corner of the menu box. The position of the bottom right
85 corner is estimated, based on the length of item names and the menu's
86 orientation. It means that the menu box always will be as large as it should
87 be. Then, there's the orientation keyword; it can be either <tt/HORIZONTAL/ or
88 <tt/VERTICAL/. Between <tt/{/ and <tt/}/, there's the menu's
89 content. It consists of item definitions. First is an item name -- it has to
90 be in quotes. Next is a menu-type bit. It can be <tt/MENU_ACTION/ or
91 <tt/SUB_MENU/; either of them can be combined with the <tt/DYN_SUB_MENU/ bit
92 (see <url name="the GEOSLib documentation" url="geos.html"> for descriptions of
93 them). You can use C logical operators in expressions, but you have to do it
94 without spaces. So, a dynamically created submenu will be something like:
96 "dynamic" SUB_MENU|DYN_SUB_MENU create_dynamic</verb></tscreen>
97 The last part of the item definition is a pointer which can be any name that is
98 present in the C source code that includes the generated header. It can point
99 to a function or to another menu definition.
101 If you are doing sub(sub)menu definitions, remember to place the lowest level
102 definition first, and the top-level menu as the last one. That way, the C
103 compiler won't complain about unknown names.
106 <sect1>Header definition
108 HEADER <GEOS_TYPE> "dosname" "classname" "version" {
110 info "This is my killer-app!"
117 The header definition describes the GEOS header sector which is unique to
118 each file. The definition starts with the keyword <tt/HEADER/, then goes the
119 GEOS file-type. You can use only <tt/APPLICATION/ here at the moment. Then,
120 there are (each one in quotes) the DOS file-name (up to 16 characters), the GEOS
121 Class name (up to 12 characters), and the version info (up to 4 characters).
122 The version should be written as &dquot;<tt/V/x.y&dquot;, where <em/x/ is the
123 major, and <em/y/ is the minor, version number. Those fields, along with both
124 braces, are required. The lines between braces are optional, and will be replaced
125 by default and current values. The keyword <tt/author/ and its value in quotes name
126 the programmer, and can be up to 63 bytes long. <tt/info/ (in the same format) can
127 have up to 95 characters. If the <tt/date/ field is omitted, then the time of
128 that compilation will be placed into the header. Note that, if you do specify
129 the date, you have to write all 5 numbers. The <tt/dostype/ can be <tt/SEQ/,
130 <tt/PRG/, or <tt/USR/. <tt/USR/ is used by default; GEOS usually doesn't care.
131 The <tt/mode/ can be <tt/any/, <tt/40only/, <tt/80only/, or <tt/c64only/; and,
132 it describes system requirements. <tt/any/ will work on both 64-GEOS and
133 128-GEOS, in 40- and 80-column modes. <tt/40only/ will work on 128-GEOS in
134 40-column mode only. <tt/80only/ will work on only 128-GEOS in 80-column mode,
135 and <tt/c64only/ will work on only 64-GEOS. The default value for
136 <tt/structure/ is <tt/SEQ/ (sequential). You can put <tt/VLIR/ there, too; but
137 then, you also have to put in a third type of resource -- a VLIR-table
138 description. The value of <tt/icon/ is a quoted file-name. The first 63 bytes of
139 this file are expected to represent a standard monochrome VIC sprite. The file gets
140 accessed when the generated assembly source is be processed by <bf/ca65/. Examples
141 for programs generating such files are <em/Sprite Painter/ and <em/SpritePad/.
144 <sect1>VLIR table description
153 The first element is the keyword <tt/VLIR/, then goes the size for all VLIR chains
154 that are different from 0. It can be either decimal (e.g., <tt/4096/) or hexadecimal
155 with a <tt/0x/ prefix (e.g., <tt/0x1000/). Then, between braces are the VLIR chain
156 numbers used by the application. Skipped numbers denote empty chains. In the example,
157 chains #3 is missing. Read <ref name="this description" id="building-vlir"> for details.
161 <sect>Building a GEOS sequential application<label id="building-seq">
162 <p>Before proceeding, please read the <url name="compiler" url="cc65.html">,
163 <url name="assembler" url="ca65.html">, and <url name="linker" url="ld65.html">
164 documentation, and find the appropriate sections about building programs, in
167 GEOS support in cc65 is based on the <em/Convert v2.5/ format, well-known in
168 the GEOS world. It means that each file built with the cc65 package has to be
169 deconverted, in GEOS, before it can be run. You can read a step-by-step
170 description of that in the GEOS section of the <url name="cc65 Compiler Intro"
173 Each project consists of four parts, two are provided by cc65. Those parts
175 <item>application header
176 <item>start-up object
177 <item>application objects
180 <bf/2./ and <bf/4./ are with cc65; you have to write the application,
183 The application header is defined in the <tt/HEADER/ section of the <tt/.grc/
184 file, and processed into an assembly <tt/.s/ file. You must assemble it, with
185 <bf/ca65/, into the object <tt/.o/ format.
188 <sect1>Building a GEOS application without cl65
189 <p>Assume that there are three input files: &dquot;<tt/test.c/&dquot; (a C
190 source), &dquot;<tt/test.h/&dquot; (a header file), and
191 &dquot;<tt/resource.grc/&dquot; (with menu and header definitions). Note the
192 fact that I <em/don't recommend/ naming that file &dquot;<tt/test.grc/&dquot;,
193 because you will have to be very careful with names (<bf/grc65/ will make
194 &dquot;<tt/test.s/&dquot; and &dquot;<tt/test.h/&dquot; out of
195 &dquot;<tt/test.grc/&dquot;, by default; and, you don't want that because
196 &dquot;<tt/test.s/&dquot; is compiled from &dquot;<tt/test.c/&dquot;, and
197 &dquot;<tt/test.h/&dquot; is something completely different)!
199 <bf/One important thing/ -- the top of &dquot;<tt/test.c/&dquot; looks like:
202 #include "resource.h"
204 There are no other includes.
206 <sect2>First step -- compiling the resources
210 will produce two output files: &dquot;<tt/resource.h/&dquot; and
211 &dquot;<tt/resource.s/&dquot;.
213 Note that &dquot;<tt/resource.h/&dquot; is included at the top of
214 &dquot;<tt/test.c/&dquot;. So, resource compiling <em/must be/ the first step.
216 <sect2>Second step -- assembling the application header
218 $ ca65 -t geos-cbm resource.s
220 And, voilá -- &dquot;<tt/resource.o/&dquot; is ready.
222 <sect2>Third step -- compiling the code
224 $ cc65 -t geos-cbm -O test.c
225 $ ca65 -t geos-cbm test.s
227 That way, you have a &dquot;<tt/test.o/&dquot; object file which
228 contains all of the executable code.
230 <sect2>Fourth and last step -- linking it together
232 $ ld65 -o test.cvt -t geos-cbm resource.o geos.o test.o geos.lib
234 &dquot;<tt/resource.o/&dquot; comes first because it contains the
235 header. The next one is &dquot;<tt/geos.o/&dquot;, a required starter-code
236 file; then, the actual application code in &dquot;<tt/test.o/&dquot;, and the
237 last is the GEOS system library.
239 The resulting file &dquot;<tt/test.cvt/&dquot; is an executable that's
240 contained in the well-known GEOS <em/Convert/ format. Note that its name
241 (<tt/test/) isn't important; the real name, after deconverting, is the DOS name
242 that was given in the header definition.
244 At each step, a <tt/-t geos-cbm/ was present on the command-line. That switch is
245 required for the correct process of GEOS sequential app. building.
249 <sect>Building a GEOS VLIR application<label id="building-vlir">
250 <p>Currently, you can build VLIR applications only if your code is written in
251 assembly -- no C code allowed.
253 In your sources, only the command <tt/.segment &dquot;/<em/NAME/<tt/&dquot;/
254 will decide which code/data goes where. File-names don't matter. Segments
255 <tt/CODE/, <tt/RODATA/, <tt/DATA/, and <tt/BSS/ go into VLIR part #0. Segment
256 <tt/VLIR1/ goes into VLIR part #1, <tt/VLIR2/ goes into VLIR part #2, and so
259 The GEOS resource file's contents are similar to <ref
260 name="the sequential-file example" id="building-seq">, but there also is a
261 <tt/VLIR/ section and a <tt/structure VLIR/ tag. Here is that part:<tscreen>
263 VLIR vlir-head.bin 0x3000 {
264 vlir-0.bin ; CODE, RODATA, DATA, BSS
268 (Source files are only <tt/.s/.)
270 OK, we have &dquot;<tt/cvthead.grc/&dquot;, so let's allow <bf/grc65/ to compile
274 Now, there are two new files: &dquot;<tt/cvthead.cfg/&dquot; and
275 &dquot;<tt/cvthead.s/&dquot; -- the first one is a config. file for <bf/ld65/,
276 and the second one contains the GEOS <tt/.cvt/ header. It can be assembled:
278 $ ca65 -t geos-cbm cvthead.s
280 Now, we have &dquot;<tt/cvthead.o/&dquot;. The rest of the assembly
281 sources can be assembled:<verb>
282 $ ca65 -t geos-cbm vlir0.s
283 $ ca65 -t geos-cbm vlir1.s
284 $ ca65 -t geos-cbm vlir2.s
286 Note that the file-names here, although similar to those from the
287 <tt/VLIR/ section of the <tt/.grc/ file, are not significant. The only thing
288 that matters is which code will go into which segment.
290 Now, we can generate binaries. This time, the order of the arguments on the
291 command-line is not important.<verb>
292 $ ld65 -C cvthead.cfg vlir1.o cvthead.o vlir0.o vlir2.o
294 As defined in the <tt/.grc/ file, we now have the binary parts of the
295 VLIR file: &dquot;<tt/vlir-head.bin/&dquot;, &dquot;<tt/vlir-0.bin/&dquot;,
296 &dquot;<tt/vlir-1.bin/&dquot;, and &dquot;<tt/vlir-2.bin/&dquot;.
298 The last step is to put them together in the right order -- the order of the
299 arguments <em/is important/ this time! As suggested in the comments at the end
300 of &dquot;<tt/cvthead.cfg/&dquot;, we do:<verb>
301 $ grc65 -vlir output.cvt vlir-head.bin vlir-0.bin vlir-1.bin vlir-2.bin
303 That is the end. The file &dquot;<tt/output.cvt/&dquot; can be
304 deconverted under GEOS. Note that <tt/-C cvthead.cfg/ was used on the
305 <bf/ld65/ command-line instead of the switch <tt/-t cbm-geos/.
309 <sect>Bugs and feedback
310 <p>This is the first release of <bf/grc65/, and it contains bugs, for sure! I
311 am aware of them; I know that the parser is weak, and if you don't follow the
312 grammar rules strictly, then everything will crash. However, if you find an
313 interesting bug, mail me. :-) Mail me also for help with writing your
314 <tt/.grc/ file correctly if you have problems with it. I would appreciate
315 comments also, and help on this file because I am sure that it can be written
321 <p><bf/grc65/ is covered by the same license as the whole cc65 package, so you
322 should see its documentation for more info. Anyway, if you like it, and want
323 to encourage me to work more on it, send me a postcard with a sight of your
324 neighbourhood, city, region, etc. Or, just e-mail me with info that you
325 actually used it. See <url name="the GEOSLib documentation" url="geos.html">
331 <sect>Appendix A -- example.grc<label id="example-grc">
333 ; Note that MENU can define both menues and submenues.
334 ; If you want to use any C operators (such as "|", "&", etc.), do it WITHOUT
335 ; any spaces between the arguments (the parser is simple and weak).
337 MENU subMenu1 15,0 VERTICAL
338 ; This is a vertical menu, placed at (15,0).
340 ; There are three items, all of them will call functions.
341 ; The first and third ones are normal functions, see GEOSLib documentation for
342 ; information about what the second function should return (it's a dynamic one).
343 "subitem1" MENU_ACTION smenu1
344 "subitem2" MENU_ACTION|DYN_SUB_MENU smenu2
345 "subitem3" MENU_ACTION smenu3
348 ;; Format: MENU "name" left,top ALIGN { "itemname" TYPE pointer ... }
350 MENU mainMenu 0,0 HORIZONTAL
351 ; Here, we have our main menu, placed at (0,0), and it is a horizontal menu.
352 ; Because it is a top-level menu, you would register it in your C source by
353 ; using: DoMenu(&ero;mainMenu);
355 ; There are two items -- a submenu and an action.
356 ; This calls a submenu named subMenu1 (see previous definition).
357 "first sub-menu" SUB_MENU subMenu1
358 ; This will work the same as an EnterDeskTop() call in C source code.
359 "quit" MENU_ACTION EnterDeskTop
362 ;; Format: HEADER <GEOS_TYPE> "dosname" "classname" "version"
364 HEADER APPLICATION "MyFirstApp" "Class Name" "V1.0"
365 ; This is a header for an APPLICATION which will be seen in the directory as a
366 ; file named MyFirstApp with the Class-string "Class Name V1.0"
368 ; Not all fields are required, default and current values will be used.
369 author "Maciej Witkowiak" ; always in quotes!
370 info "Information text" ; always in quotes!
371 ; date yy mm dd hh ss ; always 5 fields!
372 ; dostype seq ; can be: PRG, SEQ, USR (only all UPPER- or lower-case)
373 ; structure seq ; can be: SEQ, VLIR (only UPPER- or lower-case)
374 mode c64only ; can be: any, 40only, 80only, c64only