Added grc.sgml converted from grc.txt by Greg King
git-svn-id: svn://svn.cc65.org/cc65/trunk@3565 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
izydorst
@@ -24,6 +24,7 @@ SGML = apple2.sgml \
|
|||||||
dio.sgml \
|
dio.sgml \
|
||||||
funcref.sgml \
|
funcref.sgml \
|
||||||
geos.sgml \
|
geos.sgml \
|
||||||
|
grc.sgml \
|
||||||
index.sgml \
|
index.sgml \
|
||||||
intro.sgml \
|
intro.sgml \
|
||||||
ld65.sgml \
|
ld65.sgml \
|
||||||
|
|||||||
388
doc/grc.sgml
Normal file
388
doc/grc.sgml
Normal 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/{/ and <tt/}/, 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á -- &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
374
doc/grc.txt
@@ -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<69> - 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 ---
|
|
||||||
Reference in New Issue
Block a user