6502/cc65
1
0
Fork 0
mirror of https://github.com/cc65/cc65.git synced 2024-06-15 17:30:06 +00:00
Code Issues Projects Releases Wiki Activity

Added grc.sgml converted from grc.txt by Greg King

Browse Source 
git-svn-id: svn://svn.cc65.org/cc65/trunk@3565 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
izydorst 2005-08-05 12:25:09 +00:00
parent 209954a4a2
commit 6a5726abab
3 changed files with 389 additions and 374 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/Makefile
View File

@ -24,6 +24,7 @@ SGML = apple2.sgml \
dio.sgml \
funcref.sgml \
geos.sgml \
grc.sgml \
index.sgml \
intro.sgml \
ld65.sgml \

388
doc/grc.sgml Normal file
View File

@ -0,0 +1,388 @@
<!doctype linuxdoc system>
<article>
<!-- Title information -->
<title>grc -- GEOS Resource Compiler
<author><url name="Maciej 'YTM/Elysium' Witkowiak" url="mailto:ytm@elysium.pl">
<and><url name="Greg King" url="mailto:gngking@erols.com">
<date>VII 2000; VI,VII 2002; 2005-8-3
<abstract>
This document describes a compiler that can create GEOS headers and menues for,
and VLIR files from, cc65-compiled programs.
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview
<p><bf/grc/ is a part of cc65's GEOS support. The tool is necessary to
generate required and optional resources. A required resource for every GEOS
application is the header, that is: an icon, some strings, and some addresses.
Optional resources might be menu definitions, other headers (e.g., for data
files of an app.), dialog definitions, etc. Without an application's header,
GEOS is unable to load and start it.
Currently, <bf/grc/ supports only menues and the required header definition,
along with support for building VLIR-structured files.
<bf/grc/ generates output in three formats: C header, <bf/ca65/ source (.s),
and, for linking VLIR, <bf/ld65/ configuration script. That is because
application header data must be in assembly format, while menu definitions can
be translated easily into C. The purpose of the C file is to include it as a
header in only one project file. The assembly source should be processed by
<bf/ca65/, and linked as the first object (read about <ref
name="the building process" id="building-seq">). The VLIR structure currently
is supported for only projects that are written entirely in assembly code.
<bf/grc/ can be used also as a handy VLIR linker -- used to build
VLIR-structured <tt/.cvt/ files out of prepared binary chains.
<sect>Usage
<p>grc accepts the following options:<tscreen><verb>
-f force the writing of the output files
-o name name the .c output file
-s name name the .s output file
-l name name the ld65 output file
-h show this help
</verb></tscreen>
When used as a VLIR linker, the correct syntax is:<tscreen><verb>
grc -vlir output.cvt header.bin vlir0.bin vlir1.bin ...
</verb></tscreen>
Default output names are made from input names with extensions replaced by
<tt/.h/ and <tt/.s/. <bf/grc/ will not overwrite existing files unless forced
to do so. That is done to avoid situations where you have <tt/test.c/ and
<tt/test.grc/ files. Both would put their output into <tt/test.s/. For that
reason, you should name your resource-files differently than sources, e.g.,
<tt/resource.grc/ or <tt/apphead.grc/.
<sect>Resource file format
<p>A resource file has the name extension <tt/.grc/. That is not required, but
it will make for an easier recognition of the file's purpose. Also, <bf/cl65/
recognizes those files. <bf/grc/'s parser is very weak, at the moment; so,
read the comments carefully, and write resources exactly as they are written
here. Look out for CAPS. and small letters. Everything after a '<tt/;/',
until the end of the line, is considered as a comment, and ignored. See the
included <ref name="commented example .grc file" id="example-grc"> for a
better view of the problem.
<sect1>Menu definition
<p><tscreen><verb>
MENU menuName leftx,topy <ORIENTATION> {
"item name 1" <MENU_TYPE> pointer
...
"item name x" <MENU_TYPE> pointer
}</verb></tscreen>
The definition starts with the keyword <tt/MENU/, then goes the menu's name,
which will be represented in C as <tt/const void/. Then are the co-ordinates
of the top left corner of the menu box. The position of the bottom right
corner is estimated, based on the length of item names and the menu's
orientation. It means that the menu box always will be as large as it should
be. Then, there's the orientation keyword; it can be either <tt/HORIZONTAL/ or
<tt/VERTICAL/. Between <tt/&lcub;/ and <tt/&rcub;/, there's the menu's
content. It consists of item definitions. First is an item name -- it has to
be in quotes. Next is a menu-type bit. It can be <tt/MENU_ACTION/ or
<tt/SUB_MENU/; either of them can be combined with the <tt/DYN_SUB_MENU/ bit
(see <url name="the GEOSLib documentation" url="geos.html"> for descriptions of
them). You can use C logical operators in expressions, but you have to do it
without spaces. So, a dynamically created submenu will be something like:
<tscreen><verb>
"dynamic" SUB_MENU|DYN_SUB_MENU create_dynamic</verb></tscreen>
The last part of the item definition is a pointer which can be any name that is
present in the C source code that includes the generated header. It can point
to a function or to another menu definition.
If you are doing sub(sub)menu definitions, remember to place the lowest level
definition first, and the top-level menu as the last one. That way, the C
compiler won't complain about unknown names.
<sect1>Header definition
<p><tscreen><verb>
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
}</verb></tscreen>
The header definition describes the GEOS header sector which is unique to
each file. Currently, there's no way to change the default <bf/grc/ icon
(an empty frame). It will be possible in the next version. The definition
starts with the keyword <tt/HEADER/, then goes the GEOS file-type. You can use
only <tt/APPLICATION/ here at the moment. Then, there are (each one in quotes)
the DOS file-name (up to 16 characters), the GEOS Class name (up to 12
characters), and the version info (up to 4 characters). The version should be
written as &dquot;<tt/V/x.y&dquot;, where <em/x/ is the major, and <em/y/ is
the minor, version number. Those fields, along with both braces, are required.
The lines between braces are optional, and will be replaced by default and
current values. The keyword <tt/author/ and its value in quotes name the
programmer, and can be up to 63 bytes long. <tt/info/ (in the same format) can
have up to 95 characters. If the <tt/date/ field is omitted, then the time of
that compilation will be placed into the header. Note that, if you do specify
the date, you have to write all 5 numbers. The <tt/dostype/ can be <tt/SEQ/,
<tt/PRG/, or <tt/USR/. <tt/USR/ is used by default; GEOS usually doesn't care.
The <tt/mode/ can be <tt/any/, <tt/40only/, <tt/80only/, or <tt/c64only/; and,
it describes system requirements. <tt/any/ will work on both 64-GEOS and
128-GEOS, in 40- and 80-column modes. <tt/40only/ will work on 128-GEOS in
40-column mode only. <tt/80only/ will work on only 128-GEOS in 80-column mode,
and <tt/c64only/ will work on only 64-GEOS. The default value for
<tt/structure/ is <tt/SEQ/ (sequential). You can put <tt/VLIR/ there, too; but
then, you also have to put in a third type of resource -- a VLIR-table
description.
<sect1>VLIR table description
<p><tscreen><verb>
VLIR headname address {
vlir0
blank
vlir2
blank
vlir4
}</verb></tscreen>
The first element is the keyword <tt/VLIR/, then goes the name for the header
binary file (read below), and the base address for all VLIR chains that are
different from 0. It can be either decimal (e.g., <tt/4096/) or hexadecimal
with a <tt/0x/ prefix (e.g., <tt/0x1000/). Then, between braces are the names
of VLIR chain binaries or the keyword <tt/blank/ which denotes empty chains.
In the example, chains #1 and #3 are missing. The names between braces are
the names of binaries that contain code for each VLIR part. They matter only
for the generated <bf/ld65/ configuration file, and will be the names of the
resulting binary files after linking. Each one will contain one VLIR chain;
and, they will have to be put together, in the correct order, into a VLIR
<tt/.cvt/ file, by <bf/grc/ in its VLIR linker mode.
The <tt/headname/ will be the name for the binary file which will contain only
a GEOS <tt/.cvt/ header made out of compiling the <tt/.s/ header file that also
was generated by <bf/grc/. At the end of the resulting <bf/ld65/ config. file
(<tt/.cfg/), in comments, there will be information about what commands are
required for putting the stuff together. Read <ref name="this description"
id="building-vlir"> for details.
<sect>Building a GEOS sequential application<label id="building-seq">
<p>Before proceeding, please read the <url name="compiler" url="cc65.html">,
<url name="assembler" url="ca65.html">, and <url name="linker" url="ld65.html">
documentation, and find the appropriate sections about building programs, in
general.
GEOS support in cc65 is based on the <em/Convert v2.5/ format, well-known in
the GEOS world. It means that each file built with the cc65 package has to be
deconverted, in GEOS, before it can be run. You can read a step-by-step
description of that in the GEOS section of the <url name="cc65 Compiler Intro"
url="intro.html">.
Each project consists of four parts, two are provided by cc65. Those parts
are:<enum>
<item>application header
<item>start-up object
<item>application objects
<item>system library
</enum>
<bf/2./ and <bf/4./ are with cc65; you have to write the application,
yourself. ;-)
The application header is defined in the <tt/HEADER/ section of the <tt/.grc/
file, and processed into an assembly <tt/.s/ file. You must assemble it, with
<bf/ca65/, into the object <tt/.o/ format.
<sect1>Building a GEOS application without cl65
<p>Assume that there are three input files: &dquot;<tt/test.c/&dquot; (a C
source), &dquot;<tt/test.h/&dquot; (a header file), and
&dquot;<tt/resource.grc/&dquot; (with menu and header definitions). Note the
fact that I <em/don't recommend/ naming that file &dquot;<tt/test.grc/&dquot;,
because you will have to be very careful with names (<bf/grc/ will make
&dquot;<tt/test.s/&dquot; and &dquot;<tt/test.h/&dquot; out of
&dquot;<tt/test.grc/&dquot;, by default; and, you don't want that because
&dquot;<tt/test.s/&dquot; is compiled from &dquot;<tt/test.c/&dquot;, and
&dquot;<tt/test.h/&dquot; is something completely different)!
<bf/One important thing/ -- the top of &dquot;<tt/test.c/&dquot; looks like:
<tscreen><verb>
#include <geos.h>
#include "resource.h"
</verb></tscreen>
There are no other includes.
<sect2>First step -- compiling the resources
<p><verb>
$ grc resource.grc
</verb>
will produce two output files: &dquot;<tt/resource.h/&dquot; and
&dquot;<tt/resource.s/&dquot;.
Note that &dquot;<tt/resource.h/&dquot; is included at the top of
&dquot;<tt/test.c/&dquot;. So, resource compiling <em/must be/ the first step.
<sect2>Second step -- assembling the application header
<p><verb>
$ ca65 -t geos resource.s
</verb>
And, voil&aacute; -- &dquot;<tt/resource.o/&dquot; is ready.
<sect2>Third step -- compiling the code
<p><verb>
$ cc65 -t geos -O test.c
$ ca65 -t geos test.s
</verb>
That way, you have a &dquot;<tt/test.o/&dquot; object file which
contains all of the executable code.
<sect2>Fourth and last step -- linking it together
<p><verb>
$ ld65 -t geos -o test.cvt resource.o geos.o test.o geos.lib
</verb>
&dquot;<tt/resource.o/&dquot; comes first because it contains the
header. The next one is &dquot;<tt/geos.o/&dquot;, a required starter-code
file; then, the actual application code in &dquot;<tt/test.o/&dquot;, and the
last is the GEOS system library.
The resulting file &dquot;<tt/test.cvt/&dquot; is an executable that's
contained in the well-known GEOS <em/Convert/ format. Note that it's name
(<tt/test/) isn't important; the real name, after deconverting, is the DOS name
that was given in the header definition.
At each step, a <tt/-t geos/ was present on the command-line. That switch is
required for the correct process of GEOS sequential app. building.
<sect>Building a GEOS VLIR application<label id="building-vlir">
<p>Currently, you can build VLIR applications only if your code is written in
assembly -- no C code allowed.
In your sources, only the command <tt/.segment &dquot;/<em/NAME/<tt/&dquot;/
will decide which code/data goes where. File-names don't matter. Segments
<tt/CODE/, <tt/RODATA/, <tt/DATA/, and <tt/BSS/ go into VLIR part #0. Segment
<tt/VLIR1/ goes into VLIR part #1, <tt/VLIR2/ goes into VLIR part #2, and so
on.
The GEOS resource file's contents are similar to <ref
name="the sequential-file example" id="building-seq">, but there also is a
<tt/VLIR/ section and a <tt/structure VLIR/ tag. Here is that part:<tscreen>
<verb>
VLIR vlir-head.bin 0x3000 {
vlir-0.bin ; CODE, RODATA, DATA, BSS
vlir-1.bin ; VLIR1
vlir-2.bin ; VLIR2
}</verb></tscreen>
(Source files are only <tt/.s/.)
OK, we have &dquot;<tt/cvthead.grc/&dquot;, so let's allow <bf/grc/ to compile
it:<verb>
$ grc cvthead.grc
</verb>
Now, there are two new files: &dquot;<tt/cvthead.cfg/&dquot; and
&dquot;<tt/cvthead.s/&dquot; -- the first one is a config. file for <bf/ld65/,
and the second one contains the GEOS <tt/.cvt/ header. It can be assembled:
<verb>
$ ca65 -t geos cvthead.s
</verb>
Now, we have &dquot;<tt/cvthead.o/&dquot;. The rest of the assembly
sources can be assembled:<verb>
$ ca65 -t geos vlir0.s
$ ca65 -t geos vlir1.s
$ ca65 -t geos vlir2.s
</verb>
Note that the file-names here, although similar to those from the
<tt/VLIR/ section of the <tt/.grc/ file, are not significant. The only thing
that matters is which code will go into which segment.
Now, we can generate binaries. This time, the order of the arguments on the
command-line is not important.<verb>
$ ld65 -C cvthead.cfg vlir1.o cvthead.o vlir0.o vlir2.o
</verb>
As defined in the <tt/.grc/ file, we now have the binary parts of the
VLIR file: &dquot;<tt/vlir-head.bin/&dquot;, &dquot;<tt/vlir-0.bin/&dquot;,
&dquot;<tt/vlir-1.bin/&dquot;, and &dquot;<tt/vlir-2.bin/&dquot;.
The last step is to put them together in the right order -- the order of the
arguments <em/is important/ this time! As suggested in the comments at the end
of &dquot;<tt/cvthead.cfg/&dquot;, we do:<verb>
$ grc -vlir output.cvt vlir-head.bin vlir-0.bin vlir-1.bin vlir-2.bin
</verb>
That is the end. The file &dquot;<tt/output.cvt/&dquot; can be
deconverted under GEOS. Note that <tt/-C cvthead.cfg/ was used on the
<bf/ld65/ command-line instead of the switch <tt/-t geos/.
<sect>Bugs and feedback
<p>This is the first release of <bf/grc/, and it contains bugs, for sure! I am
aware of them; I know that the parser is weak, and if you don't follow the
grammar rules strictly, then everything will crash. However, if you find an
interesting bug, mail me. :-) Mail me also for help with writing your
<tt/.grc/ file correctly if you have problems with it. I would appreciate
comments also, and help on this file because I am sure that it can be written
better.
<sect>Legal stuff
<p><bf/grc/ is covered by the same license as the whole cc65 package, so you
should see its documentation for more info. Anyway, if you like it, and want
to encourage me to work more on it, send me a postcard with a sight of your
neighbourhood, city, region, etc. Or, just e-mail me with info that you
actually used it. See <url name="the GEOSLib documentation" url="geos.html">
for addresses.
<appendix>
<sect>Appendix A -- example.grc<label id="example-grc">
<p><tscreen><verb>
; Note that MENU can define both menues and submenues.
; If you want to use any C operators (such as "|", "&", etc.), do it WITHOUT
; any spaces between the arguments (the parser is simple and weak).
MENU subMenu1 15,0 VERTICAL
; This is a vertical menu, placed at (15,0).
{
; There are three items, all of them will call functions.
; The first and third ones are normal functions, see GEOSLib documentation for
; information about what the second function should return (it's a dynamic one).
"subitem1" MENU_ACTION smenu1
"subitem2" 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.
; Because it is a top-level menu, you would register it in your C source by
; using: DoMenu(&ero;mainMenu);
{
; There are two items -- a submenu and an action.
; This calls a submenu named subMenu1 (see previous definition).
"first sub-menu" SUB_MENU subMenu1
; This will work the same as an EnterDeskTop() call in C source code.
"quit" MENU_ACTION EnterDeskTop
}
;; Format: HEADER <GEOS_TYPE> "dosname" "classname" "version"
HEADER APPLICATION "MyFirstApp" "Class Name" "V1.0"
; This is a header for an APPLICATION which will be seen in the directory as a
; file named MyFirstApp with the Class-string "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 all UPPER- or lower-case)
; structure seq ; can be: SEQ, VLIR (only UPPER- or lower-case)
mode c64only ; can be: any, 40only, 80only, c64only
}</verb></tscreen>
</article>

374
doc/grc.txt
View File

@ -1,374 +0,0 @@
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 and top lever menu as the last one. 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á - 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 ---