mirror of
https://github.com/cc65/cc65.git
synced 2024-08-20 09:29:12 +00:00
275 lines
9.8 KiB
Plaintext
275 lines
9.8 KiB
Plaintext
|
||
|
||
|
||
grc - GEOS resource compiler
|
||
|
||
Maciej 'YTM/Alliance' Witkowiak
|
||
<ytm@friko.onet.pl>
|
||
|
||
VII 2000
|
||
|
||
|
||
|
||
|
||
|
||
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.
|
||
|
||
grc generates output in two formats - as C header and ca65 source (.s). This
|
||
is because application header data must be in assembler fromat 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).
|
||
|
||
2. Usage
|
||
--------
|
||
|
||
grc accepts following options:
|
||
-f force writting output files
|
||
-o name name C output file
|
||
-s name name S output file
|
||
-h help
|
||
|
||
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.
|
||
|
||
Currently grc supports only two types of resources - menu and header.
|
||
|
||
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
|
||
}
|
||
|
||
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.
|
||
|
||
|
||
4. Building GEOS application
|
||
----------------------------
|
||
|
||
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
|
||
|
||
$ ld -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. 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.
|
||
|
||
|
||
6. 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)
|
||
mode c64only ; can be any, 40only, 80only, c64only
|
||
}
|
||
|
||
--- cut here ---
|