mirror of
https://github.com/cc65/cc65.git
synced 2024-08-28 18:29:20 +00:00
374 lines
13 KiB
Plaintext
374 lines
13 KiB
Plaintext
|
||
|
||
|
||
grc - GEOS resource compiler
|
||
|
||
Maciej 'YTM/Elysium' Witkowiak
|
||
<ytm@elysium.pl>
|
||
|
||
VII 2000
|
||
VI,VII 2002
|
||
|
||
|
||
|
||
|
||
1. Overview
|
||
-----------
|
||
|
||
grc is a part of cc65's GEOS support. This tool is necessary to generate
|
||
required and optional resources. A required resource for every GEOS app is the
|
||
header, that is: icon, some strings and addresses. Optional resources might be
|
||
menu definitions, other headers (e.g. for data files of an app), dialogs
|
||
definitions etc. Without application header GEOS is unable to load and start
|
||
it.
|
||
|
||
Currently, grc supports only menus and required header definition as long with
|
||
support for building VLIR structured files.
|
||
|
||
grc generates output in three formats - as C header, ca65 source (.s) and for
|
||
linking VLIR - ld65 configuration file. This is because application header data
|
||
must be in assembler format while menu definitions can be easily translated
|
||
into C. The purpose of C file is to include it as header in only one project
|
||
file. Assembler source should be processed with ca65 and linked as first object
|
||
(read Building process below). VLIR structure is currently supported only for
|
||
project written entirely in assembler.
|
||
|
||
grc can be also used as a handy VLIR linker used to build VLIR-structured .cvt
|
||
file out of prepared binary chains.
|
||
|
||
2. Usage
|
||
--------
|
||
|
||
grc accepts following options:
|
||
-f force writting output files
|
||
-o name name C output file
|
||
-s name name S output file
|
||
-l name name ld65 output file
|
||
-h help
|
||
|
||
when used as VLIR linker the correct syntax is:
|
||
grc -vlir output.cvt header.bin vlir0.bin vlir1.bin...
|
||
|
||
Default output names are made from input name with extension replaced by '.h'
|
||
and '.s'. grc will not overwrite existing files unless forced to do so.
|
||
This is to avoid situation where you have test.c and test.grc files. Both would
|
||
make output into test.s. For this reason you should name your resources files
|
||
differently than sources, e.g. as resource.grc or apphead.grc.
|
||
|
||
|
||
3. Resource file format
|
||
-----------------------
|
||
|
||
A resource file has name extension '.grc'. This is not required, but it will
|
||
make easier recognition of file purpose. Also cl65 recognizes these files.
|
||
Parser is very weak at the moment so read the comments carefully and write
|
||
resources exactly as it is written here. Look out for CAPS and small letters.
|
||
Everything after a ';' till the end of line is considered as comment and
|
||
ignored.
|
||
See included commented example .grc file for better view of the problem.
|
||
|
||
|
||
a) menu definition
|
||
|
||
MENU menuName leftx,topy ORIENTATION
|
||
{
|
||
"item name 1" MENU_TYPE pointer
|
||
...
|
||
"item name x" MENU_TYPE pointer
|
||
}
|
||
|
||
The definition starts with keyword MENU, then goes menu name, which will be
|
||
represented in C as const void. Then are coordinates of top left corner
|
||
of menu box. The position of bottom right corner is estimated basing on length
|
||
of item names and menu orientation. It means that menu box will be always
|
||
as large as it should be. Then there's orientation keyword, it can be either
|
||
HORIZONTAL or VERTICAL.
|
||
Between { and } there's menu content. It consists of item definitions.
|
||
First is item name - it has to be in quotes. Next is menu type bit. It can
|
||
be MENU_ACTION or SUB_MENU, both can be combined with DYN_SUB_MENU bit
|
||
(see GEOSLib documentation for description of these). You can use C logical
|
||
operators in expressions but you have to do it without spaces, so dynamically
|
||
created submenu will be something like:
|
||
|
||
"dynamic" SUB_MENU|DYN_SUB_MENU create_dynamic
|
||
|
||
The last part of the item definition is a pointer which can be any name which
|
||
is present in source that includes generated header. It can point to a function
|
||
or to another menu definition.
|
||
|
||
If you are doing sub(sub)menus definitions remember to place the lowest level
|
||
definition first. This way C compiler won't complain about unknown names.
|
||
|
||
|
||
b) header definition
|
||
|
||
HEADER GEOS_TYPE "dosname" "classname" "version"
|
||
{
|
||
author "Joe Schmoe"
|
||
info "This is my killer-app!"
|
||
date yy mm dd hh ss
|
||
dostype SEQ
|
||
mode any
|
||
structure SEQ
|
||
}
|
||
|
||
Header definition describes GEOS header sector which is unique to each file.
|
||
Currently there's no way to change default grc icon (an empty frame). It will
|
||
be possible in next versions.
|
||
The definition starts with keyword HEADER, then goes GEOS file type. You can
|
||
only use APPLICATION here at the moment. Then there are (all in quotes) DOS
|
||
filename (up to 16 characters), GEOS Class name (up to 12 characters) and
|
||
version info (up to 4 characters). Version should be written as "Vx.y" where
|
||
x is the major and y the minor version number. These fields along with both
|
||
brackets are required. Data between brackets is optional and will be replaced
|
||
by default and current values.
|
||
Keyword 'author' and value in quotes describes Author field and can be up to
|
||
63 bytes long.
|
||
Info (in the same format) can have up to 95 characters.
|
||
If 'date' field will be ommited then the time of compilation will be placed.
|
||
Note that if you do specify the date you have to write all 5 numbers.
|
||
Dostype can by SEQ, PRG or USR. USR is by default, GEOS doesn't care.
|
||
Mode can be 'any', '40only', '80only', 'c64only' and describes system
|
||
requirements. 'any' will work both on GEOS64 and GEOS128 in 40 and 80 column
|
||
modes. '40only' will work on GEOS128 in 40 column mode only. '80only' will
|
||
work only on GEOS128 and 'c64only' will work only on GEOS64.
|
||
The default value for 'structure' is SEQ (sequential). You can also put 'VLIR'
|
||
there but then you have also to place third type of resources - VLIR table
|
||
description.
|
||
|
||
|
||
c) VLIR table description
|
||
|
||
VLIR headname address {
|
||
vlir0
|
||
blank
|
||
vlir2
|
||
blank
|
||
vlir4
|
||
}
|
||
|
||
The first element is keyword 'VLIR', then goes the name for header binary name
|
||
(read below) and base address for all VLIR chains diffrent than 0. It can be
|
||
either decimal (e.g. '4096') or hexadecimal with '0x' prefix (e.g. '0x1000').
|
||
Then between brackets are names of vlir chain binaries or keyword 'blank' which
|
||
denotes empty chains. In this example chains #1 and #3 are missing.
|
||
The names between brackets are names of binaries containing code for each VLIR
|
||
part. They matter only for generated ld65 configuration file and will be the
|
||
names of resulting binary files after linking. Each one will contain one VLIR
|
||
chain and they will have to be put together into VLIR .cvt by grc in VLIR linker
|
||
modey in correct order.
|
||
The 'headname' will be the name for binary which will contain only GEOS .cvt
|
||
header made out of compiling .s header file generated also by grc.
|
||
At the end of resulting ld65 config file (.cfg) in comments there will be
|
||
information what commands are required for putting the stuff together. Read
|
||
info below and see example somewhere around.
|
||
|
||
|
||
4. Building GEOS application (SEQUENTIAL)
|
||
----------------------------
|
||
|
||
Before proceeding please read cc65, ca65 and ld65 documentation and find
|
||
appropriate sections about compiling programs in general.
|
||
|
||
GEOS support in cc65 is based on well-known in GEOS world Convert v2.5 format.
|
||
It means that each file built with cc65 package has to unconverted before
|
||
running.
|
||
|
||
Each project consists of four parts, two are provided by cc65. These parts are:
|
||
|
||
a) application header
|
||
b) main object
|
||
c) application objects
|
||
d) system library
|
||
|
||
b) and d) are with cc65, you have to write application yourself ;)
|
||
|
||
Application header is defined in HEADER section of .grc file and processed
|
||
into assembler .s file. You have to compile it with ca65 to object .o format.
|
||
|
||
|
||
4a. Building GEOS application without cl65
|
||
-----------------------------------------
|
||
|
||
Assume that there are three input files: test.c (a C source), test.h (a header
|
||
file) and resource.grc (with menu and header definition). Note the fact that I
|
||
DON'T RECOMMEND naming this file test.grc, because you will have to be very
|
||
careful with names (grc will make test.s and test.h out of test.grc by default
|
||
and you don't want that, because test.s is compiled test.c and test.h is
|
||
something completely different).
|
||
|
||
Important thing - the top of test.c looks like:
|
||
|
||
--- cut here ---
|
||
|
||
#include <geos.h>
|
||
#include "resource.h"
|
||
|
||
--- cut here ---
|
||
|
||
There are no other includes.
|
||
|
||
1. First step - compiling resources:
|
||
|
||
$ grc resource.grc
|
||
|
||
will produce two output files: resource.h and resource.s
|
||
|
||
Note that resource.h is included at the top of test.c so resource compiling
|
||
must be the first step.
|
||
|
||
2. Second step - compiling the code:
|
||
|
||
$ cc65 -t geos -O test.c
|
||
$ ca65 -t geos test.s
|
||
|
||
This way you have test.o object file which contains all the executable code.
|
||
|
||
3. Third step - compiling the application header
|
||
|
||
$ ca65 -t geos resource.s
|
||
|
||
And voil<69> - resource.o is ready
|
||
|
||
4. Fourth and the last step - linking it together
|
||
|
||
$ ld65 -t geos -o test.cvt resource.o geos.o test.o geos.lib
|
||
|
||
resource.o comes first because it contains the header. Next one is geos.o, a
|
||
required starter code, then actual application code in test.o and the last is
|
||
GEOS system library.
|
||
The resulting file test.cvt is executable in well-known GEOS Convert format.
|
||
Note that it's name (test) isn't important, the real name after unconverting
|
||
is the DOS name given in header definition.
|
||
|
||
On each step a '-t geos' was present at the command line. This switch is required
|
||
for correct process of app building.
|
||
|
||
|
||
5. Building GEOS application (VLIR)
|
||
-----------------------------------
|
||
|
||
Currently you can only build VLIR application if your code is written in
|
||
assembler. No .c allowed.
|
||
|
||
In your sources only command '.segment "NAME"' will decide which code/data goes
|
||
where. Filenames doesn't matter.
|
||
Segments CODE, RODATA, DATA and BSS go into VLIR part #0. Segment VLIR1 go to
|
||
VLIR part #1, VLIR2 - VLIR part #2 and so on.
|
||
|
||
GEOS resource file contents are similar to seq example but there is also 'VLIR'
|
||
section and 'structure VLIR' tag. Here is that part:
|
||
|
||
VLIR vlir-head.bin 0x3000 {
|
||
vlir-0.bin ; CODE, RODATA, DATA, BSS
|
||
vlir-1.bin ; VLIR1
|
||
vlir-2.bin ; VLIR2
|
||
}
|
||
|
||
Source files are only .s.
|
||
Ok. We have 'cvthead.grc' so let's allow grc to compile it:
|
||
|
||
$ grc cvthead.grc
|
||
|
||
Now there are two new files: cvthead.cfg and cvthead.s - the first one is a
|
||
config file for ld65 and the second one contains GEOS .cvt header. It can be
|
||
assembled now:
|
||
|
||
$ ca65 cvthead.s
|
||
|
||
Now we have cvthead.o. The rest of assembly sources can be also assembled now:
|
||
|
||
$ ca65 vlir0.s
|
||
$ ca65 vlir1.s
|
||
$ ca65 vlir2.s
|
||
|
||
Note that filenames here although similar to those from VLIR section of .grc file
|
||
are not significant. The only thing that matters is which code will go to which
|
||
segment.
|
||
Now we can generate binaries. This time order of arguments in command line is
|
||
not important.
|
||
|
||
$ ld65 -C cvthead.cfg cvthead.o vlir0.o vlir1.o vlir2.o
|
||
|
||
As defined in .grc file, we have now binary parts of VLIR file:
|
||
vlir-head.bin, vlir-0.bin, vilr-1.bin, vlir-2.bin
|
||
|
||
The last step is to put them together in the right order, order of arguments
|
||
is important this time. As suggested in comments at the end of cvthead.cfg
|
||
we do:
|
||
|
||
$ grc -vlir output.cvt vlir-head.bin vlir-0.bin vlir-1.bin vlir-2.bin
|
||
|
||
This is the end. The file 'output.cvt' can be unconverted under GEOS.
|
||
Note that the switch '-t geos' wasn't present at any stage of this process.
|
||
|
||
6. Bugs and feedback
|
||
--------------------
|
||
|
||
This is the first release of grc and it contains bugs for sure. I am aware of
|
||
them, I know that parser is weak and if you don't strictly follow grammar
|
||
rules then everything will crash. However if you find an interesting bug mail
|
||
me :-) Mail me also for help writting your .grc correctly if you have problems
|
||
with it.
|
||
I would also appreciate comments and help on this file because I am sure that
|
||
it can be written better.
|
||
|
||
|
||
7. Legal stuff
|
||
--------------
|
||
|
||
grc is covered by the same license as whole cc65 package, so see its
|
||
documentation for more info. Anyway, if you like it and want to ecourage me
|
||
to work more on it send me a postcard with sight of your neighbourhood, city,
|
||
region etc or just e-mail with info that you actually used it. See GEOSLib
|
||
documentation for addresses.
|
||
|
||
|
||
Appendix A: example.grc
|
||
|
||
---- cut here ----
|
||
|
||
;Note that MENU is either MENU and SUBMENU
|
||
;If you want to use any C operators (like '|', '&' etc.) do it WITHOUT spaces
|
||
;between arguments (parser is simple and weak)
|
||
|
||
MENU subMenu1 15,0 VERTICAL
|
||
; this is a vertical menu placed at (15,0)
|
||
{
|
||
; there are three items, all are calling functions
|
||
; first and third are normal functions, see GEOSLib documentation for
|
||
; information what should second function return (it's a dynamic one)
|
||
"subitem1" MENU_ACTION smenu1
|
||
"mubitem2" MENU_ACTION|DYN_SUB_MENU smenu2
|
||
"subitem3" MENU_ACTION smenu3
|
||
}
|
||
|
||
; format: MENU "name" left,top ALIGN { "itemname" TYPE pointer ... }
|
||
MENU mainMenu 0,0 HORIZONTAL
|
||
; here we have our main menu placed at (0,0) and it is a horizontal menu
|
||
; since it is a top level menu you would register it in C source using
|
||
; DoMenu(&mainMenu);
|
||
{
|
||
; there are two items - a submenu and an action menu
|
||
; this calls submenu named subMenu1 (see previous definition)
|
||
"sub menu1" SUB_MENU subMenu1
|
||
; this will work the same as EnterDeskTop() call from C source
|
||
"quit" MENU_ACTION EnterDeskTop
|
||
}
|
||
|
||
; format: HEADER GEOS_TYPE "dosname" "classname" "version"
|
||
HEADER APPLICATION "MyFirstApp" "Class Name" "V1.0"
|
||
; this is a header for APPLICATION which wille be seen in directory as
|
||
; file named MyFirstApp with Class "Class Name V1.0"
|
||
{
|
||
; not all fields are required, default and current values will be used
|
||
author "Maciej Witkowiak" ; always in quotes!
|
||
info "Information text" ; always in quotes!
|
||
; date yy mm dd hh ss ; always 5 fields!
|
||
; dostype seq ; can be PRG, SEQ, USR (only UPPER or lower case)
|
||
; structure seq ; can be SEQ, VLIR (only UPPER or lower case)
|
||
mode c64only ; can be any, 40only, 80only, c64only
|
||
}
|
||
|
||
--- cut here ---
|