mirror of
https://github.com/cc65/cc65.git
synced 2024-06-01 13:41:34 +00:00
Added grc doc file from Maciek
git-svn-id: svn://svn.cc65.org/cc65/trunk@150 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
cuz
parent
e2de9f5873
commit
9cc7dc1284
274
doc/grc.txt
Normal file
274
doc/grc.txt
Normal file
|
|
@ -0,0 +1,274 @@
|
|||
|
||||
|
||||
|
||||
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á - 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 ---
|
||||
Loading…
Reference in New Issue
Block a user