4 grc - GEOS resource compiler
6 Maciej 'YTM/Elysium' Witkowiak
18 grc is a part of cc65's GEOS support. This tool is necessary to generate
19 required and optional resources. A required resource for every GEOS app is the
20 header, that is: icon, some strings and addresses. Optional resources might be
21 menu definitions, other headers (e.g. for data files of an app), dialogs
22 definitions etc. Without application header GEOS is unable to load and start
25 Currently, grc supports only menus and required header definition as long with
26 support for building VLIR structured files.
28 grc generates output in three formats - as C header, ca65 source (.s) and for
29 linking VLIR - ld65 configuration file. This is because application header data
30 must be in assembler format while menu definitions can be easily translated
31 into C. The purpose of C file is to include it as header in only one project
32 file. Assembler source should be processed with ca65 and linked as first object
33 (read Building process below). VLIR structure is currently supported only for
34 project written entirely in assembler.
36 grc can be also used as a handy VLIR linker used to build VLIR-structured .cvt
37 file out of prepared binary chains.
42 grc accepts following options:
43 -f force writting output files
44 -o name name C output file
45 -s name name S output file
46 -l name name ld65 output file
49 when used as VLIR linker the correct syntax is:
50 grc -vlir output.cvt header.bin vlir0.bin vlir1.bin...
52 Default output names are made from input name with extension replaced by '.h'
53 and '.s'. grc will not overwrite existing files unless forced to do so.
54 This is to avoid situation where you have test.c and test.grc files. Both would
55 make output into test.s. For this reason you should name your resources files
56 differently than sources, e.g. as resource.grc or apphead.grc.
59 3. Resource file format
60 -----------------------
62 A resource file has name extension '.grc'. This is not required, but it will
63 make easier recognition of file purpose. Also cl65 recognizes these files.
64 Parser is very weak at the moment so read the comments carefully and write
65 resources exactly as it is written here. Look out for CAPS and small letters.
66 Everything after a ';' till the end of line is considered as comment and
68 See included commented example .grc file for better view of the problem.
73 MENU menuName leftx,topy ORIENTATION
75 "item name 1" MENU_TYPE pointer
77 "item name x" MENU_TYPE pointer
80 The definition starts with keyword MENU, then goes menu name, which will be
81 represented in C as const void. Then are coordinates of top left corner
82 of menu box. The position of bottom right corner is estimated basing on length
83 of item names and menu orientation. It means that menu box will be always
84 as large as it should be. Then there's orientation keyword, it can be either
85 HORIZONTAL or VERTICAL.
86 Between { and } there's menu content. It consists of item definitions.
87 First is item name - it has to be in quotes. Next is menu type bit. It can
88 be MENU_ACTION or SUB_MENU, both can be combined with DYN_SUB_MENU bit
89 (see GEOSLib documentation for description of these). You can use C logical
90 operators in expressions but you have to do it without spaces, so dynamically
91 created submenu will be something like:
93 "dynamic" SUB_MENU|DYN_SUB_MENU create_dynamic
95 The last part of the item definition is a pointer which can be any name which
96 is present in source that includes generated header. It can point to a function
97 or to another menu definition.
99 If you are doing sub(sub)menus definitions remember to place the lowest level
100 definition first. This way C compiler won't complain about unknown names.
105 HEADER GEOS_TYPE "dosname" "classname" "version"
108 info "This is my killer-app!"
115 Header definition describes GEOS header sector which is unique to each file.
116 Currently there's no way to change default grc icon (an empty frame). It will
117 be possible in next versions.
118 The definition starts with keyword HEADER, then goes GEOS file type. You can
119 only use APPLICATION here at the moment. Then there are (all in quotes) DOS
120 filename (up to 16 characters), GEOS Class name (up to 12 characters) and
121 version info (up to 4 characters). Version should be written as "Vx.y" where
122 x is the major and y the minor version number. These fields along with both
123 brackets are required. Data between brackets is optional and will be replaced
124 by default and current values.
125 Keyword 'author' and value in quotes describes Author field and can be up to
127 Info (in the same format) can have up to 95 characters.
128 If 'date' field will be ommited then the time of compilation will be placed.
129 Note that if you do specify the date you have to write all 5 numbers.
130 Dostype can by SEQ, PRG or USR. USR is by default, GEOS doesn't care.
131 Mode can be 'any', '40only', '80only', 'c64only' and describes system
132 requirements. 'any' will work both on GEOS64 and GEOS128 in 40 and 80 column
133 modes. '40only' will work on GEOS128 in 40 column mode only. '80only' will
134 work only on GEOS128 and 'c64only' will work only on GEOS64.
135 The default value for 'structure' is SEQ (sequential). You can also put 'VLIR'
136 there but then you have also to place third type of resources - VLIR table
140 c) VLIR table description
142 VLIR headname address {
150 The first element is keyword 'VLIR', then goes the name for header binary name
151 (read below) and base address for all VLIR chains diffrent than 0. It can be
152 either decimal (e.g. '4096') or hexadecimal with '0x' prefix (e.g. '0x1000').
153 Then between brackets are names of vlir chain binaries or keyword 'blank' which
154 denotes empty chains. In this example chains #1 and #3 are missing.
155 The names between brackets are names of binaries containing code for each VLIR
156 part. They matter only for generated ld65 configuration file and will be the
157 names of resulting binary files after linking. Each one will contain one VLIR
158 chain and they will have to be put together into VLIR .cvt by grc in VLIR linker
159 modey in correct order.
160 The 'headname' will be the name for binary which will contain only GEOS .cvt
161 header made out of compiling .s header file generated also by grc.
162 At the end of resulting ld65 config file (.cfg) in comments there will be
163 information what commands are required for putting the stuff together. Read
164 info below and see example somewhere around.
167 4. Building GEOS application (SEQUENTIAL)
168 ----------------------------
170 Before proceeding please read cc65, ca65 and ld65 documentation and find
171 appropriate sections about compiling programs in general.
173 GEOS support in cc65 is based on well-known in GEOS world Convert v2.5 format.
174 It means that each file built with cc65 package has to unconverted before
177 Each project consists of four parts, two are provided by cc65. These parts are:
179 a) application header
181 c) application objects
184 b) and d) are with cc65, you have to write application yourself ;)
186 Application header is defined in HEADER section of .grc file and processed
187 into assembler .s file. You have to compile it with ca65 to object .o format.
190 4a. Building GEOS application without cl65
191 -----------------------------------------
193 Assume that there are three input files: test.c (a C source), test.h (a header
194 file) and resource.grc (with menu and header definition). Note the fact that I
195 DON'T RECOMMEND naming this file test.grc, because you will have to be very
196 careful with names (grc will make test.s and test.h out of test.grc by default
197 and you don't want that, because test.s is compiled test.c and test.h is
198 something completely different).
200 Important thing - the top of test.c looks like:
205 #include "resource.h"
209 There are no other includes.
211 1. First step - compiling resources:
215 will produce two output files: resource.h and resource.s
217 Note that resource.h is included at the top of test.c so resource compiling
218 must be the first step.
220 2. Second step - compiling the code:
222 $ cc65 -t geos -O test.c
223 $ ca65 -t geos test.s
225 This way you have test.o object file which contains all the executable code.
227 3. Third step - compiling the application header
229 $ ca65 -t geos resource.s
231 And voilá - resource.o is ready
233 4. Fourth and the last step - linking it together
235 $ ld65 -t geos -o test.cvt resource.o geos.o test.o geos.lib
237 resource.o comes first because it contains the header. Next one is geos.o, a
238 required starter code, then actual application code in test.o and the last is
240 The resulting file test.cvt is executable in well-known GEOS Convert format.
241 Note that it's name (test) isn't important, the real name after unconverting
242 is the DOS name given in header definition.
244 On each step a '-t geos' was present at the command line. This switch is required
245 for correct process of app building.
248 5. Building GEOS application (VLIR)
249 -----------------------------------
251 Currently you can only build VLIR application if your code is written in
252 assembler. No .c allowed.
254 In your sources only command '.segment "NAME"' will decide which code/data goes
255 where. Filenames doesn't matter.
256 Segments CODE, RODATA, DATA and BSS go into VLIR part #0. Segment VLIR1 go to
257 VLIR part #1, VLIR2 - VLIR part #2 and so on.
259 GEOS resource file contents are similar to seq example but there is also 'VLIR'
260 section and 'structure VLIR' tag. Here is that part:
262 VLIR vlir-head.bin 0x3000 {
263 vlir-0.bin ; CODE, RODATA, DATA, BSS
268 Source files are only .s.
269 Ok. We have 'cvthead.grc' so let's allow grc to compile it:
273 Now there are two new files: cvthead.cfg and cvthead.s - the first one is a
274 config file for ld65 and the second one contains GEOS .cvt header. It can be
279 Now we have cvthead.o. The rest of assembly sources can be also assembled now:
285 Note that filenames here although similar to those from VLIR section of .grc file
286 are not significant. The only thing that matters is which code will go to which
288 Now we can generate binaries. This time order of arguments in command line is
291 $ ld65 -C cvthead.cfg cvthead.o vlir0.o vlir1.o vlir2.o
293 As defined in .grc file, we have now binary parts of VLIR file:
294 vlir-head.bin, vlir-0.bin, vilr-1.bin, vlir-2.bin
296 The last step is to put them together in the right order, order of arguments
297 is important this time. As suggested in comments at the end of cvthead.cfg
300 $ grc -vlir output.cvt vlir-head.bin vlir-0.bin vlir-1.bin vlir-2.bin
302 This is the end. The file 'output.cvt' can be unconverted under GEOS.
303 Note that the switch '-t geos' wasn't present at any stage of this process.
308 This is the first release of grc and it contains bugs for sure. I am aware of
309 them, I know that parser is weak and if you don't strictly follow grammar
310 rules then everything will crash. However if you find an interesting bug mail
311 me :-) Mail me also for help writting your .grc correctly if you have problems
313 I would also appreciate comments and help on this file because I am sure that
314 it can be written better.
320 grc is covered by the same license as whole cc65 package, so see its
321 documentation for more info. Anyway, if you like it and want to ecourage me
322 to work more on it send me a postcard with sight of your neighbourhood, city,
323 region etc or just e-mail with info that you actually used it. See GEOSLib
324 documentation for addresses.
327 Appendix A: example.grc
331 ;Note that MENU is either MENU and SUBMENU
332 ;If you want to use any C operators (like '|', '&' etc.) do it WITHOUT spaces
333 ;between arguments (parser is simple and weak)
335 MENU subMenu1 15,0 VERTICAL
336 ; this is a vertical menu placed at (15,0)
338 ; there are three items, all are calling functions
339 ; first and third are normal functions, see GEOSLib documentation for
340 ; information what should second function return (it's a dynamic one)
341 "subitem1" MENU_ACTION smenu1
342 "mubitem2" MENU_ACTION|DYN_SUB_MENU smenu2
343 "subitem3" MENU_ACTION smenu3
346 ; format: MENU "name" left,top ALIGN { "itemname" TYPE pointer ... }
347 MENU mainMenu 0,0 HORIZONTAL
348 ; here we have our main menu placed at (0,0) and it is a horizontal menu
349 ; since it is a top level menu you would register it in C source using
352 ; there are two items - a submenu and an action menu
353 ; this calls submenu named subMenu1 (see previous definition)
354 "sub menu1" SUB_MENU subMenu1
355 ; this will work the same as EnterDeskTop() call from C source
356 "quit" MENU_ACTION EnterDeskTop
359 ; format: HEADER GEOS_TYPE "dosname" "classname" "version"
360 HEADER APPLICATION "MyFirstApp" "Class Name" "V1.0"
361 ; this is a header for APPLICATION which wille be seen in directory as
362 ; file named MyFirstApp with Class "Class Name V1.0"
364 ; not all fields are required, default and current values will be used
365 author "Maciej Witkowiak" ; always in quotes!
366 info "Information text" ; always in quotes!
367 ; date yy mm dd hh ss ; always 5 fields!
368 ; dostype seq ; can be PRG, SEQ, USR (only UPPER or lower case)
369 ; structure seq ; can be SEQ, VLIR (only UPPER or lower case)
370 mode c64only ; can be any, 40only, 80only, c64only