Added grc doc file from Maciek

[cc65] / doc / grc.txt

    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 ---