mirror of
https://github.com/cc65/cc65.git
synced 2024-12-25 02:29:52 +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 ---
|