1 <!doctype linuxdoc system>
\r
4 <!-- Title information -->
\r
6 <title>grc65 -- GEOS Resource Compiler
\r
7 <author><url name="Maciej 'YTM/Elysium' Witkowiak" url="mailto:ytm@elysium.pl">
\r
8 <and><url name="Greg King" url="mailto:gngking@erols.com">
\r
9 <date>VII 2000; VI,VII 2002; 2005-8-3
\r
11 This document describes a compiler that can create GEOS headers and menues for
\r
12 cc65-compiled programs.
\r
15 <!-- Table of contents -->
\r
18 <!-- Begin the document -->
\r
21 <p><bf/grc65/ is a part of cc65's GEOS support. The tool is necessary to
\r
22 generate required and optional resources. A required resource for every GEOS
\r
23 application is the header, that is: an icon, some strings, and some addresses.
\r
24 Optional resources might be menu definitions, other headers (e.g., for data
\r
25 files of an app.), dialog definitions, etc. Without an application's header,
\r
26 GEOS is unable to load and start it.
\r
28 Currently, <bf/grc65/ supports only menues and the required header definition,
\r
29 along with support for building applications with VLIR-structured overlays.
\r
31 <bf/grc65/ generates output in two formats: C header and <bf/ca65/ source (.s).
\r
32 That is because the application header data must be in assembly format, while
\r
33 the menu definitions can be translated easily into C. The purpose of the C
\r
34 file is to include it as a header in only one project file. The assembly source
\r
35 should be processed by <bf/ca65/ and linked to the application (read about
\r
36 <ref name="the building process" id="building-seq">).
\r
41 <p>grc65 accepts the following options:
\r
44 ---------------------------------------------------------------------------
\r
45 Usage: grc65 [options] file
\r
47 -V Print the version number
\r
49 -o name Name the C output file
\r
50 -s name Name the asm output file
\r
51 -t sys Set the target system
\r
54 --help Help (this text)
\r
55 --target sys Set the target system
\r
56 --version Print the version number
\r
57 ---------------------------------------------------------------------------
\r
59 Default output names are made from input names with extensions replaced by
\r
60 <tt/.h/ and <tt/.s/.
\r
64 <sect>Resource file format
\r
65 <p>A resource file has the name extension <tt/.grc/. That is not required, but
\r
66 it will make for an easier recognition of the file's purpose. Also, <bf/cl65/
\r
67 recognizes those files. <bf/grc65/'s parser is very weak at the moment; so,
\r
68 read the comments carefully, and write resources exactly as they are written
\r
69 here. Look out for CAPS and small letters. Everything after a '<tt/;/'
\r
70 until the end of the line is considered as a comment and ignored. See the
\r
71 included <ref name="commented example .grc file" id="example-grc"> for a
\r
72 better view of the situation.
\r
75 <sect1>Menu definition
\r
77 MENU menuName leftx,topy <ORIENTATION> {
\r
78 "item name 1" <MENU_TYPE> pointer
\r
80 "item name x" <MENU_TYPE> pointer
\r
82 The definition starts with the keyword <tt/MENU/, then comes the menu's name,
\r
83 which will be represented in C as <tt/const void/. Then are the co-ordinates
\r
84 of the top left corner of the menu box. The position of the bottom right
\r
85 corner is estimated, based on the length of item names and the menu's
\r
86 orientation. It means that the menu box always will be as large as it should
\r
87 be. Then, there's the orientation keyword; it can be either <tt/HORIZONTAL/ or
\r
88 <tt/VERTICAL/. Between <tt/{/ and <tt/}/, there's the menu's
\r
89 content. It consists of item definitions. First is an item name -- it has to
\r
90 be in quotes. Next is a menu-type bit. It can be <tt/MENU_ACTION/ or
\r
91 <tt/SUB_MENU/; either of them can be combined with the <tt/DYN_SUB_MENU/ bit
\r
92 (see <url name="the GEOSLib documentation" url="geos.html"> for descriptions of
\r
93 them). You can use C logical operators in expressions, but you have to do it
\r
94 without spaces. So a dynamically created submenu will be something like:
\r
96 "dynamic" SUB_MENU|DYN_SUB_MENU create_dynamic</verb></tscreen>
\r
97 The last part of the item definition is a pointer which can be any name that is
\r
98 present in the C source code that includes the generated header. It can point
\r
99 to a function or to another menu definition.
\r
101 If you are doing sub(sub)menu definitions, remember to place the lowest level
\r
102 definition first, and the top-level menu as the last one. That way the C
\r
103 compiler won't complain about unknown names.
\r
106 <sect1>Header definition
\r
108 HEADER <GEOS_TYPE> "dosname" "classname" "version" {
\r
109 author "Joe Schmoe"
\r
110 info "This is my killer-app!"
\r
111 date yy mm dd hh ss
\r
117 The header definition describes the GEOS header sector which is unique to
\r
118 each file. The definition starts with the keyword <tt/HEADER/, then goes the
\r
119 GEOS file-type. You can use only <tt/APPLICATION/ here at the moment. Then,
\r
120 there are (each one in quotes) the DOS file-name (up to 16 characters), the GEOS
\r
121 Class name (up to 12 characters), and the version info (up to 4 characters).
\r
122 The version should be written as &dquot;<tt/V/x.y&dquot;, where <em/x/ is the
\r
123 major, and <em/y/ is the minor, version number. Those fields, along with both
\r
124 braces, are required. The lines between braces are optional, and will be replaced
\r
125 by default and current values. The keyword <tt/author/ and its value in quotes name
\r
126 the programmer, and can be up to 63 bytes long. <tt/info/ (in the same format) can
\r
127 have up to 95 characters. If the <tt/date/ field is omitted, then the time of
\r
128 that compilation will be placed into the header. Note that, if you do specify
\r
129 the date, you have to write all 5 numbers. The <tt/dostype/ can be <tt/SEQ/,
\r
130 <tt/PRG/, or <tt/USR/. <tt/USR/ is used by default; GEOS usually doesn't care.
\r
131 The <tt/mode/ can be <tt/any/, <tt/40only/, <tt/80only/, or <tt/c64only/; and,
\r
132 it describes system requirements. <tt/any/ will work on both 64-GEOS and
\r
133 128-GEOS, in 40- and 80-column modes. <tt/40only/ will work on 128-GEOS in
\r
134 40-column mode only. <tt/80only/ will work on only 128-GEOS in 80-column mode,
\r
135 and <tt/c64only/ will work on only 64-GEOS. The default value for
\r
136 <tt/structure/ is <tt/SEQ/ (sequential). You can put <tt/VLIR/ there, too; but
\r
137 then, you also have to put in a third type of resource -- a memory definition.
\r
138 The value of <tt/icon/ is a quoted file-name. The first 63 bytes of this file
\r
139 are expected to represent a standard monochrome VIC sprite. The file gets accessed
\r
140 when the generated assembly source is be processed by <bf/ca65/. Examples for
\r
141 programs generating such files are <em/Sprite Painter/ and <em/SpritePad/. The
\r
142 default <tt/icon/ is an empty frame internally represented in the generated assembly
\r
146 <sect1>Memory definition
\r
151 overlaynums 0 1 2 4 5
\r
153 The memory definition is unique to each file and describes several attributes related
\r
154 to the memory layout. It consists of the keyword <tt/MEMORY/ followed by braces which
\r
155 contain optional lines. The value of <tt/stacksize/ can be either decimal (e.g.
\r
156 <tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g. <tt/0x1000/). The default value
\r
157 of 0x400 comes from the linker configuration file. The value of <tt/backbuffer/ can be
\r
158 either <tt/yes/ or <tt/no/. The further means that the application uses the system-supplied
\r
159 background screen buffer while the latter means that the program uses the memory of the
\r
160 background screen buffer for own purposes. The default value of <tt/yes/ comes from the
\r
161 linker configuration file. If the <tt/structure/ in the header definition is set to the
\r
162 value <tt/VLIR/ then it is possible and necessary to provide here the attributes of the
\r
163 VLIR overlays. <tt/overlaysize/ defines the maximal size for all VLIR records but number
\r
164 0. It can be either decimal (e.g. <tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g.
\r
165 <tt/0x1000/). <tt/overlaynums/ defines the VLIR record numbers used by the application.
\r
166 Skipped numbers denote empty records. In the example, record number 3 is missing. Read
\r
167 <ref name="this description" id="building-vlir"> for details.
\r
171 <sect>Building a GEOS sequential application<label id="building-seq">
\r
172 <p>Before proceeding, please read the <url name="compiler" url="cc65.html">,
\r
173 <url name="assembler" url="ca65.html">, and <url name="linker" url="ld65.html">
\r
174 documentation, and find the appropriate sections about building programs, in
\r
177 GEOS support in cc65 is based on the <em/Convert v2.5/ format, well-known in
\r
178 the GEOS world. It means that each file built with the cc65 package has to be
\r
179 deconverted in GEOS, before it can be run. You can read a step-by-step
\r
180 description of that in the <url name="GEOS section of the cc65 Compiler Intro"
\r
181 url="intro-6.html#ss6.5">.
\r
183 Each project consists of four parts, two are provided by cc65. Those parts
\r
185 <item>application header
\r
186 <item>start-up object
\r
187 <item>application objects
\r
188 <item>system library
\r
190 <bf/2./ and <bf/4./ come with cc65; however you have to write the application
\r
193 The application header is defined in the <tt/HEADER/ section of the <tt/.grc/
\r
194 file and is processed into an assembly <tt/.s/ file. You must assemble it, with
\r
195 <bf/ca65/, into the object <tt/.o/ format.
\r
197 Assume that there are three input files: &dquot;<tt/test.c/&dquot; (a C
\r
198 source), &dquot;<tt/test.h/&dquot; (a header file), and
\r
199 &dquot;<tt/testres.grc/&dquot; (with menu and header definitions). Note the
\r
200 fact that I <em/don't recommend/ naming that file &dquot;<tt/test.grc/&dquot;
\r
201 because you will have to be very careful with names (<bf/grc65/ will make
\r
202 &dquot;<tt/test.s/&dquot; and &dquot;<tt/test.h/&dquot; out of
\r
203 &dquot;<tt/test.grc/&dquot; by default; and you don't want that because
\r
204 &dquot;<tt/test.s/&dquot; is compiled from &dquot;<tt/test.c/&dquot;, and
\r
205 &dquot;<tt/test.h/&dquot; is something completely different)!
\r
207 <bf/One important thing/ -- the top of &dquot;<tt/test.c/&dquot; looks like:
\r
210 #include "testres.h"
\r
212 There are no other includes.
\r
215 <sect1>Building the GEOS application using cl65
\r
216 <p>This is a simple one step process:
\r
218 cl65 -t geos-cbm -O -o test.cvt testres.grc test.c
\r
220 Always place the <tt/.grc/ file as first input file on the command-line in order
\r
221 to make sure that the generated <tt/.h/ file is available when it is needed for
\r
222 inclusion by a <tt/.c/ file.
\r
225 <sect1>Building the GEOS application without cl65
\r
226 <sect2>First step -- compiling the resources
\r
228 grc65 -t geos-cbm testres.grc
\r
230 will produce two output files: &dquot;<tt/testres.h/&dquot; and
\r
231 &dquot;<tt/testres.s/&dquot;.
\r
233 Note that &dquot;<tt/testres.h/&dquot; is included at the top of
\r
234 &dquot;<tt/test.c/&dquot;. So, resource compiling <em/must be/ the first step.
\r
236 <sect2>Second step -- assembling the application header
\r
238 ca65 -t geos-cbm testres.s
\r
240 And, voilá -- &dquot;<tt/testres.o/&dquot; is ready.
\r
242 <sect2>Third step -- compiling the code
\r
244 cc65 -t geos-cbm -O test.c
\r
245 ca65 -t geos-cbm test.s
\r
247 That way, you have a &dquot;<tt/test.o/&dquot; object file which
\r
248 contains all of the executable code.
\r
250 <sect2>Fourth and last step -- linking it together
\r
252 ld65 -t geos-cbm -o test.cvt testres.o test.o geos.lib
\r
254 The last file is the GEOS system library.
\r
256 The resulting file &dquot;<tt/test.cvt/&dquot; is an executable that's
\r
257 contained in the well-known GEOS <em/Convert/ format. Note that its name
\r
258 (<tt/test.cvt/) isn't important; the real name, after deconverting, is the DOS name
\r
259 that was given in the header definition.
\r
261 At each step, a <tt/-t geos-cbm/ was present on the command-line. That switch is
\r
262 required for the correct process of GEOS sequential application building.
\r
266 <sect>Building a GEOS VLIR overlay application<label id="building-vlir">
\r
267 <p>Large GEOS applications typically don't fit in one piece in their designated
\r
268 memeory area. They are therefore split into overlays which are loaded into memory
\r
269 on demand. The individual overlays are stored as records of a VLIR (Variable
\r
270 Length Index Record) file. When GEOS starts a VLIR overlay appliation it loads
\r
271 record number 0 which is supposed to contain the main program. The record numbers
\r
272 starting with 1 are to be used for the actual overlays.
\r
274 In "<tt>cc65/samples/geos</tt>" there's a VLIR overlay demo application consisting
\r
275 of the files "<tt/overlay-demo.c/" and "<tt/overlay-demores.grc/".
\r
278 <sect1>Building the GEOS application using cl65
\r
279 <p>This is a simple one step process:
\r
281 cl65 -t geos-cbm -O -o overlay-demo.cvt -m overlay-demo.map overlay-demores.grc overlay-demo.c
\r
283 Always place the <tt/.grc/ file as first input file on the command-line in order
\r
284 to make sure that the generated <tt/.h/ file is available when it is needed for
\r
285 inclusion by a <tt/.c/ file.
\r
287 You will almost certainly want to generate a map file that shows (beside a lot of
\r
288 other infos) how large your individual overlays are. This info is necessary to tune
\r
289 the distribution of code into the overlays and optimizes the memory area reserved
\r
293 <sect1>Building the GEOS application without cl65
\r
294 <sect2>First step -- compiling the resources
\r
296 grc65 -t geos-cbm overlay-demores.grc
\r
299 <sect2>Second step -- assembling the application header
\r
301 ca65 -t geos-cbm overlay-demores.s
\r
304 <sect2>Third step -- compiling the code
\r
306 cc65 -t geos-cbm -O overlay-demo.c
\r
307 ca65 -t geos-cbm overlay-demo.s
\r
310 <sect2>Fourth and last step -- linking it together
\r
312 ld65 -t geos-cbm -o overlay-demo.cvt -m overlay-demo.map overlay-demores.o overlay-demo.o geos.lib
\r
317 <sect>Bugs and feedback
\r
318 <p>This is the first release of <bf/grc65/, and it contains bugs, for sure! I
\r
319 am aware of them; I know that the parser is weak, and if you don't follow the
\r
320 grammar rules strictly, then everything will crash. However, if you find an
\r
321 interesting bug, mail me. :-) Mail me also for help with writing your
\r
322 <tt/.grc/ file correctly if you have problems with it. I would appreciate
\r
323 comments also, and help on this file because I am sure that it can be written
\r
329 <p><bf/grc65/ is covered by the same license as the whole cc65 package, so you
\r
330 should see its documentation for more info. Anyway, if you like it, and want
\r
331 to encourage me to work more on it, send me a postcard with a sight of your
\r
332 neighbourhood, city, region, etc. Or, just e-mail me with info that you
\r
333 actually used it. See <url name="the GEOSLib documentation" url="geos.html">
\r
339 <sect>Appendix A -- example.grc<label id="example-grc">
\r
341 ; Note that MENU can define both menues and submenues.
\r
342 ; If you want to use any C operators (such as "|", "&", etc.), do it WITHOUT
\r
343 ; any spaces between the arguments (the parser is simple and weak).
\r
345 MENU subMenu1 15,0 VERTICAL
\r
346 ; This is a vertical menu, placed at (15,0).
\r
348 ; There are three items, all of them will call functions.
\r
349 ; The first and third ones are normal functions, see GEOSLib documentation for
\r
350 ; information about what the second function should return (it's a dynamic one).
\r
351 "subitem1" MENU_ACTION smenu1
\r
352 "subitem2" MENU_ACTION|DYN_SUB_MENU smenu2
\r
353 "subitem3" MENU_ACTION smenu3
\r
356 ;; Format: MENU "name" left,top ALIGN { "itemname" TYPE pointer ... }
\r
358 MENU mainMenu 0,0 HORIZONTAL
\r
359 ; Here, we have our main menu, placed at (0,0), and it is a horizontal menu.
\r
360 ; Because it is a top-level menu, you would register it in your C source by
\r
361 ; using: DoMenu(&ero;mainMenu);
\r
363 ; There are two items -- a submenu and an action.
\r
364 ; This calls a submenu named subMenu1 (see previous definition).
\r
365 "first sub-menu" SUB_MENU subMenu1
\r
366 ; This will work the same as an EnterDeskTop() call in C source code.
\r
367 "quit" MENU_ACTION EnterDeskTop
\r
370 ;; Format: HEADER <GEOS_TYPE> "dosname" "classname" "version"
\r
372 HEADER APPLICATION "MyFirstApp" "Class Name" "V1.0"
\r
373 ; This is a header for an APPLICATION which will be seen in the directory as a
\r
374 ; file named MyFirstApp with the Class-string "Class Name V1.0"
\r
376 ; Not all fields are required, default and current values will be used.
\r
377 author "Maciej Witkowiak" ; always in quotes!
\r
378 info "Information text" ; always in quotes!
\r
379 ; date yy mm dd hh ss ; always 5 fields!
\r
380 ; dostype seq ; can be: PRG, SEQ, USR (only all UPPER- or lower-case)
\r
381 ; structure seq ; can be: SEQ, VLIR (only UPPER- or lower-case)
\r
382 mode c64only ; can be: any, 40only, 80only, c64only
\r
projects / cc65 / blob