mirror of
https://github.com/cc65/cc65.git
synced 2025-02-07 04:31:38 +00:00
Adjusted line endings and fixed some more typos.
git-svn-id: svn://svn.cc65.org/cc65/trunk@5389 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
ol.sc
parent
90631777fc
commit
d273c5de93
768
doc/grc65.sgml
768
doc/grc65.sgml
@ -1,384 +1,384 @@
|
|||||||
<!doctype linuxdoc system>
|
<!doctype linuxdoc system>
|
||||||
<article>
|
<article>
|
||||||
|
|
||||||
<!-- Title information -->
|
<!-- Title information -->
|
||||||
|
|
||||||
<title>grc65 -- GEOS Resource Compiler
|
<title>grc65 -- GEOS Resource Compiler
|
||||||
<author><url name="Maciej 'YTM/Elysium' Witkowiak" url="mailto:ytm@elysium.pl">
|
<author><url name="Maciej 'YTM/Elysium' Witkowiak" url="mailto:ytm@elysium.pl">
|
||||||
<and><url name="Greg King" url="mailto:gngking@erols.com">
|
<and><url name="Greg King" url="mailto:gngking@erols.com">
|
||||||
<date>VII 2000; VI,VII 2002; 2005-8-3
|
<date>VII 2000; VI,VII 2002; 2005-8-3
|
||||||
<abstract>
|
<abstract>
|
||||||
This document describes a compiler that can create GEOS headers and menues for
|
This document describes a compiler that can create GEOS headers and menues for
|
||||||
cc65-compiled programs.
|
cc65-compiled programs.
|
||||||
</abstract>
|
</abstract>
|
||||||
|
|
||||||
<!-- Table of contents -->
|
<!-- Table of contents -->
|
||||||
<toc>
|
<toc>
|
||||||
|
|
||||||
<!-- Begin the document -->
|
<!-- Begin the document -->
|
||||||
|
|
||||||
<sect>Overview
|
<sect>Overview
|
||||||
<p><bf/grc65/ is a part of cc65's GEOS support. The tool is necessary to
|
<p><bf/grc65/ is a part of cc65's GEOS support. The tool is necessary to
|
||||||
generate required and optional resources. A required resource for every GEOS
|
generate required and optional resources. A required resource for every GEOS
|
||||||
application is the header, that is: an icon, some strings, and some addresses.
|
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
|
Optional resources might be menu definitions, other headers (e.g., for data
|
||||||
files of an app.), dialog definitions, etc. Without an application's header,
|
files of an app.), dialog definitions, etc. Without an application's header,
|
||||||
GEOS is unable to load and start it.
|
GEOS is unable to load and start it.
|
||||||
|
|
||||||
Currently, <bf/grc65/ supports only menues and the required header definition,
|
Currently, <bf/grc65/ supports only menues and the required header definition,
|
||||||
along with support for building applications with VLIR-structured overlays.
|
along with support for building applications with VLIR-structured overlays.
|
||||||
|
|
||||||
<bf/grc65/ generates output in two formats: C header and <bf/ca65/ source (.s).
|
<bf/grc65/ generates output in two formats: C header and <bf/ca65/ source (.s).
|
||||||
That is because the application header data must be in assembly format, while
|
That is because the application header data must be in assembly format, while
|
||||||
the menu definitions can be translated easily into C. The purpose of the C
|
the 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
|
file is to include it as a header in only one project file. The assembly source
|
||||||
should be processed by <bf/ca65/ and linked to the application (read about
|
should be processed by <bf/ca65/ and linked to the application (read about
|
||||||
<ref name="the building process" id="building-seq">).
|
<ref name="the building process" id="building-seq">).
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<sect>Usage
|
<sect>Usage
|
||||||
<p>grc65 accepts the following options:
|
<p>grc65 accepts the following options:
|
||||||
|
|
||||||
<tscreen><verb>
|
<tscreen><verb>
|
||||||
---------------------------------------------------------------------------
|
---------------------------------------------------------------------------
|
||||||
Usage: grc65 [options] file
|
Usage: grc65 [options] file
|
||||||
Short options:
|
Short options:
|
||||||
-V Print the version number
|
-V Print the version number
|
||||||
-h Help (this text)
|
-h Help (this text)
|
||||||
-o name Name the C output file
|
-o name Name the C output file
|
||||||
-s name Name the asm output file
|
-s name Name the asm output file
|
||||||
-t sys Set the target system
|
-t sys Set the target system
|
||||||
|
|
||||||
Long options:
|
Long options:
|
||||||
--help Help (this text)
|
--help Help (this text)
|
||||||
--target sys Set the target system
|
--target sys Set the target system
|
||||||
--version Print the version number
|
--version Print the version number
|
||||||
---------------------------------------------------------------------------
|
---------------------------------------------------------------------------
|
||||||
</verb></tscreen>
|
</verb></tscreen>
|
||||||
Default output names are made from input names with extensions replaced by
|
Default output names are made from input names with extensions replaced by
|
||||||
<tt/.h/ and <tt/.s/.
|
<tt/.h/ and <tt/.s/.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<sect>Resource file format
|
<sect>Resource file format
|
||||||
<p>A resource file has the name extension <tt/.grc/. That is not required, but
|
<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/
|
it will make for an easier recognition of the file's purpose. Also, <bf/cl65/
|
||||||
recognizes those files. <bf/grc65/'s parser is very weak at the moment; so,
|
recognizes those files. <bf/grc65/'s parser is very weak at the moment; so,
|
||||||
read the comments carefully, and write resources exactly as they are written
|
read the comments carefully, and write resources exactly as they are written
|
||||||
here. Look out for CAPS and small letters. Everything after a '<tt/;/'
|
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
|
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
|
included <ref name="commented example .grc file" id="example-grc"> for a
|
||||||
better view of the situation.
|
better view of the situation.
|
||||||
|
|
||||||
|
|
||||||
<sect1>Menu definition
|
<sect1>Menu definition
|
||||||
<p><tscreen><verb>
|
<p><tscreen><verb>
|
||||||
MENU menuName leftx,topy <ORIENTATION> {
|
MENU menuName leftx,topy <ORIENTATION> {
|
||||||
"item name 1" <MENU_TYPE> pointer
|
"item name 1" <MENU_TYPE> pointer
|
||||||
...
|
...
|
||||||
"item name x" <MENU_TYPE> pointer
|
"item name x" <MENU_TYPE> pointer
|
||||||
}</verb></tscreen>
|
}</verb></tscreen>
|
||||||
The definition starts with the keyword <tt/MENU/, then comes the menu's name,
|
The definition starts with the keyword <tt/MENU/, then comes the menu's name,
|
||||||
which will be represented in C as <tt/const void/. Then are the co-ordinates
|
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
|
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
|
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
|
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
|
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
|
<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
|
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
|
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
|
<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
|
(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
|
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:
|
without spaces. So a dynamically created submenu will be something like:
|
||||||
<tscreen><verb>
|
<tscreen><verb>
|
||||||
"dynamic" SUB_MENU|DYN_SUB_MENU create_dynamic</verb></tscreen>
|
"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
|
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
|
present in the C source code that includes the generated header. It can point
|
||||||
to a function or to another menu definition.
|
to a function or to another menu definition.
|
||||||
|
|
||||||
If you are doing sub(sub)menu definitions, remember to place the lowest level
|
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
|
definition first, and the top-level menu as the last one. That way the C
|
||||||
compiler won't complain about unknown names.
|
compiler won't complain about unknown names.
|
||||||
|
|
||||||
|
|
||||||
<sect1>Header definition
|
<sect1>Header definition
|
||||||
<p><tscreen><verb>
|
<p><tscreen><verb>
|
||||||
HEADER <GEOS_TYPE> "dosname" "classname" "version" {
|
HEADER <GEOS_TYPE> "dosname" "classname" "version" {
|
||||||
author "Joe Schmoe"
|
author "Joe Schmoe"
|
||||||
info "This is my killer-app!"
|
info "This is my killer-app!"
|
||||||
date yy mm dd hh ss
|
date yy mm dd hh ss
|
||||||
dostype SEQ
|
dostype SEQ
|
||||||
mode any
|
mode any
|
||||||
structure SEQ
|
structure SEQ
|
||||||
icon "sprite.raw"
|
icon "sprite.raw"
|
||||||
}</verb></tscreen>
|
}</verb></tscreen>
|
||||||
The header definition describes the GEOS header sector which is unique to
|
The header definition describes the GEOS header sector which is unique to
|
||||||
each file. The definition starts with the keyword <tt/HEADER/, then goes the
|
each file. 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,
|
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
|
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).
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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/,
|
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.
|
<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,
|
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
|
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
|
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,
|
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
|
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
|
<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 memory definition.
|
then, you also have to put in a third type of resource -- a memory definition.
|
||||||
The value of <tt/icon/ is a quoted file-name. The first 63 bytes of this file
|
The value of <tt/icon/ is a quoted file-name. The first 63 bytes of this file
|
||||||
are expected to represent a standard monochrome VIC sprite. The file gets accessed
|
are expected to represent a standard monochrome VIC sprite. The file gets accessed
|
||||||
when the generated assembly source is be processed by <bf/ca65/. Examples for
|
when the generated assembly source is be processed by <bf/ca65/. Examples for
|
||||||
programs generating such files are <em/Sprite Painter/ and <em/SpritePad/. The
|
programs generating such files are <em/Sprite Painter/ and <em/SpritePad/. The
|
||||||
default <tt/icon/ is an empty frame internally represented in the generated assembly
|
default <tt/icon/ is an empty frame internally represented in the generated assembly
|
||||||
file.
|
file.
|
||||||
|
|
||||||
|
|
||||||
<sect1>Memory definition
|
<sect1>Memory definition
|
||||||
<p><tscreen><verb>
|
<p><tscreen><verb>
|
||||||
MEMORY {
|
MEMORY {
|
||||||
stacksize 0x0800
|
stacksize 0x0800
|
||||||
overlaysize 0x2000
|
overlaysize 0x2000
|
||||||
overlaynums 0 1 2 4 5
|
overlaynums 0 1 2 4 5
|
||||||
}</verb></tscreen>
|
}</verb></tscreen>
|
||||||
The memory definition is unique to each file and describes several attributes related
|
The memory definition is unique to each file and describes several attributes related
|
||||||
to the memory layout. It consists of the keyword <tt/MEMORY/ followed by braces which
|
to the memory layout. It consists of the keyword <tt/MEMORY/ followed by braces which
|
||||||
contain optional lines. The value of <tt/stacksize/ can be either decimal (e.g.
|
contain optional lines. The value of <tt/stacksize/ can be either decimal (e.g.
|
||||||
<tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g. <tt/0x1000/). The default value
|
<tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g. <tt/0x1000/). The default value
|
||||||
of 0x400 comes from the linker configuration file. The value of <tt/backbuffer/ can be
|
of 0x400 comes from the linker configuration file. The value of <tt/backbuffer/ can be
|
||||||
either <tt/yes/ or <tt/no/. The further means that the application uses the system-supplied
|
either <tt/yes/ or <tt/no/. The further means that the application uses the system-supplied
|
||||||
background screen buffer while the latter means that the program uses the memory of the
|
background screen buffer while the latter means that the program uses the memory of the
|
||||||
background screen buffer for own purposes. The default value of <tt/yes/ comes from the
|
background screen buffer for own purposes. The default value of <tt/yes/ comes from the
|
||||||
linker configuration file. If the <tt/structure/ in the header definition is set to the
|
linker configuration file. If the <tt/structure/ in the header definition is set to the
|
||||||
value <tt/VLIR/ then it is possible and necessary to provide here the attributes of the
|
value <tt/VLIR/ then it is possible and necessary to provide here the attributes of the
|
||||||
VLIR overlays. <tt/overlaysize/ defines the maximal size for all VLIR records but number
|
VLIR overlays. <tt/overlaysize/ defines the maximal size for all VLIR records but number
|
||||||
0. It can be either decimal (e.g. <tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g.
|
0. It can be either decimal (e.g. <tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g.
|
||||||
<tt/0x1000/). <tt/overlaynums/ defines the VLIR record numbers used by the application.
|
<tt/0x1000/). <tt/overlaynums/ defines the VLIR record numbers used by the application.
|
||||||
Skipped numbers denote empty records. In the example, record number 3 is missing. Read
|
Skipped numbers denote empty records. In the example, record number 3 is missing. Read
|
||||||
<ref name="this description" id="building-vlir"> for details.
|
<ref name="this description" id="building-vlir"> for details.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<sect>Building a GEOS sequential application<label id="building-seq">
|
<sect>Building a GEOS sequential application<label id="building-seq">
|
||||||
<p>Before proceeding, please read the <url name="compiler" url="cc65.html">,
|
<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">
|
<url name="assembler" url="ca65.html">, and <url name="linker" url="ld65.html">
|
||||||
documentation, and find the appropriate sections about building programs, in
|
documentation, and find the appropriate sections about building programs, in
|
||||||
general.
|
general.
|
||||||
|
|
||||||
GEOS support in cc65 is based on the <em/Convert v2.5/ format, well-known in
|
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
|
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
|
deconverted in GEOS, before it can be run. You can read a step-by-step
|
||||||
description of that in the <url name="GEOS section of the cc65 Compiler Intro"
|
description of that in the <url name="GEOS section of the cc65 Compiler Intro"
|
||||||
url="intro-6.html#ss6.5">.
|
url="intro-6.html#ss6.5">.
|
||||||
|
|
||||||
Each project consists of four parts, two are provided by cc65. Those parts
|
Each project consists of four parts, two are provided by cc65. Those parts
|
||||||
are:<enum>
|
are:<enum>
|
||||||
<item>application header
|
<item>application header
|
||||||
<item>start-up object
|
<item>start-up object
|
||||||
<item>application objects
|
<item>application objects
|
||||||
<item>system library
|
<item>system library
|
||||||
</enum>
|
</enum>
|
||||||
<bf/2./ and <bf/4./ come with cc65; however you have to write the application
|
<bf/2./ and <bf/4./ come with cc65; however you have to write the application
|
||||||
yourself ;-)
|
yourself ;-)
|
||||||
|
|
||||||
The application header is defined in the <tt/HEADER/ section of the <tt/.grc/
|
The application header is defined in the <tt/HEADER/ section of the <tt/.grc/
|
||||||
file and is processed into an assembly <tt/.s/ file. You must assemble it, with
|
file and is processed into an assembly <tt/.s/ file. You must assemble it, with
|
||||||
<bf/ca65/, into the object <tt/.o/ format.
|
<bf/ca65/, into the object <tt/.o/ format.
|
||||||
|
|
||||||
Assume that there are three input files: &dquot;<tt/test.c/&dquot; (a C
|
Assume that there are three input files: &dquot;<tt/test.c/&dquot; (a C
|
||||||
source), &dquot;<tt/test.h/&dquot; (a header file), and
|
source), &dquot;<tt/test.h/&dquot; (a header file), and
|
||||||
&dquot;<tt/testres.grc/&dquot; (with menu and header definitions). Note the
|
&dquot;<tt/testres.grc/&dquot; (with menu and header definitions). Note the
|
||||||
fact that I <em/don't recommend/ naming that file &dquot;<tt/test.grc/&dquot;
|
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/grc65/ will make
|
because you will have to be very careful with names (<bf/grc65/ will make
|
||||||
&dquot;<tt/test.s/&dquot; and &dquot;<tt/test.h/&dquot; out of
|
&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.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.s/&dquot; is compiled from &dquot;<tt/test.c/&dquot;, and
|
||||||
&dquot;<tt/test.h/&dquot; is something completely different)!
|
&dquot;<tt/test.h/&dquot; is something completely different)!
|
||||||
|
|
||||||
<bf/One important thing/ -- the top of &dquot;<tt/test.c/&dquot; looks like:
|
<bf/One important thing/ -- the top of &dquot;<tt/test.c/&dquot; looks like:
|
||||||
<tscreen><verb>
|
<tscreen><verb>
|
||||||
#include <geos.h>
|
#include <geos.h>
|
||||||
#include "testres.h"
|
#include "testres.h"
|
||||||
</verb></tscreen>
|
</verb></tscreen>
|
||||||
There are no other includes.
|
There are no other includes.
|
||||||
|
|
||||||
|
|
||||||
<sect1>Building the GEOS application using cl65
|
<sect1>Building the GEOS application using cl65
|
||||||
<p>This is a simple one step process:
|
<p>This is a simple one step process:
|
||||||
<tscreen><verb>
|
<tscreen><verb>
|
||||||
cl65 -t geos-cbm -O -o test.cvt testres.grc test.c
|
cl65 -t geos-cbm -O -o test.cvt testres.grc test.c
|
||||||
</verb></tscreen>
|
</verb></tscreen>
|
||||||
Always place the <tt/.grc/ file as first input file on the command-line in order
|
Always place the <tt/.grc/ file as first input file on the command-line in order
|
||||||
to make sure that the generated <tt/.h/ file is available when it is needed for
|
to make sure that the generated <tt/.h/ file is available when it is needed for
|
||||||
inclusion by a <tt/.c/ file.
|
inclusion by a <tt/.c/ file.
|
||||||
|
|
||||||
|
|
||||||
<sect1>Building the GEOS application without cl65
|
<sect1>Building the GEOS application without cl65
|
||||||
<sect2>First step -- compiling the resources
|
<sect2>First step -- compiling the resources
|
||||||
<tscreen><verb>
|
<tscreen><verb>
|
||||||
grc65 -t geos-cbm testres.grc
|
grc65 -t geos-cbm testres.grc
|
||||||
</verb></tscreen>
|
</verb></tscreen>
|
||||||
will produce two output files: &dquot;<tt/testres.h/&dquot; and
|
will produce two output files: &dquot;<tt/testres.h/&dquot; and
|
||||||
&dquot;<tt/testres.s/&dquot;.
|
&dquot;<tt/testres.s/&dquot;.
|
||||||
|
|
||||||
Note that &dquot;<tt/testres.h/&dquot; is included at the top of
|
Note that &dquot;<tt/testres.h/&dquot; is included at the top of
|
||||||
&dquot;<tt/test.c/&dquot;. So, resource compiling <em/must be/ the first step.
|
&dquot;<tt/test.c/&dquot;. So, resource compiling <em/must be/ the first step.
|
||||||
|
|
||||||
<sect2>Second step -- assembling the application header
|
<sect2>Second step -- assembling the application header
|
||||||
<tscreen><verb>
|
<tscreen><verb>
|
||||||
ca65 -t geos-cbm testres.s
|
ca65 -t geos-cbm testres.s
|
||||||
</verb></tscreen>
|
</verb></tscreen>
|
||||||
And, voilá -- &dquot;<tt/testres.o/&dquot; is ready.
|
And, voilá -- &dquot;<tt/testres.o/&dquot; is ready.
|
||||||
|
|
||||||
<sect2>Third step -- compiling the code
|
<sect2>Third step -- compiling the code
|
||||||
<tscreen><verb>
|
<tscreen><verb>
|
||||||
cc65 -t geos-cbm -O test.c
|
cc65 -t geos-cbm -O test.c
|
||||||
ca65 -t geos-cbm test.s
|
ca65 -t geos-cbm test.s
|
||||||
</verb></tscreen>
|
</verb></tscreen>
|
||||||
That way, you have a &dquot;<tt/test.o/&dquot; object file which
|
That way, you have a &dquot;<tt/test.o/&dquot; object file which
|
||||||
contains all of the executable code.
|
contains all of the executable code.
|
||||||
|
|
||||||
<sect2>Fourth and last step -- linking it together
|
<sect2>Fourth and last step -- linking it together
|
||||||
<tscreen><verb>
|
<tscreen><verb>
|
||||||
ld65 -t geos-cbm -o test.cvt testres.o test.o geos.lib
|
ld65 -t geos-cbm -o test.cvt testres.o test.o geos.lib
|
||||||
</verb></tscreen>
|
</verb></tscreen>
|
||||||
The last file is the GEOS system library.
|
The last file is the GEOS system library.
|
||||||
|
|
||||||
The resulting file &dquot;<tt/test.cvt/&dquot; is an executable that's
|
The resulting file &dquot;<tt/test.cvt/&dquot; is an executable that's
|
||||||
contained in the well-known GEOS <em/Convert/ format. Note that its name
|
contained in the well-known GEOS <em/Convert/ format. Note that its name
|
||||||
(<tt/test.cvt/) isn't important; the real name, after deconverting, is the DOS name
|
(<tt/test.cvt/) isn't important; the real name, after deconverting, is the DOS name
|
||||||
that was given in the header definition.
|
that was given in the header definition.
|
||||||
|
|
||||||
At each step, a <tt/-t geos-cbm/ was present on the command-line. That switch is
|
At each step, a <tt/-t geos-cbm/ was present on the command-line. That switch is
|
||||||
required for the correct process of GEOS sequential application building.
|
required for the correct process of GEOS sequential application building.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<sect>Building a GEOS VLIR overlay application<label id="building-vlir">
|
<sect>Building a GEOS VLIR overlay application<label id="building-vlir">
|
||||||
<p>Large GEOS applications typically don't fit in one piece in their designated
|
<p>Large GEOS applications typically don't fit in one piece in their designated
|
||||||
memeory area. They are therefore split into overlays which are loaded into memory
|
memory area. They are therefore split into overlays which are loaded into memory
|
||||||
on demand. The individual overlays are stored as records of a VLIR (Variable
|
on demand. The individual overlays are stored as records of a VLIR (Variable
|
||||||
Length Index Record) file. When GEOS starts a VLIR overlay appliation it loads
|
Length Index Record) file. When GEOS starts a VLIR overlay appliation it loads
|
||||||
record number 0 which is supposed to contain the main program. The record numbers
|
record number 0 which is supposed to contain the main program. The record numbers
|
||||||
starting with 1 are to be used for the actual overlays.
|
starting with 1 are to be used for the actual overlays.
|
||||||
|
|
||||||
In "<tt>cc65/samples/geos</tt>" there's a VLIR overlay demo application consisting
|
In "<tt>cc65/samples/geos</tt>" there's a VLIR overlay demo application consisting
|
||||||
of the files "<tt/overlay-demo.c/" and "<tt/overlay-demores.grc/".
|
of the files "<tt/overlay-demo.c/" and "<tt/overlay-demores.grc/".
|
||||||
|
|
||||||
|
|
||||||
<sect1>Building the GEOS application using cl65
|
<sect1>Building the GEOS application using cl65
|
||||||
<p>This is a simple one step process:
|
<p>This is a simple one step process:
|
||||||
<tscreen><verb>
|
<tscreen><verb>
|
||||||
cl65 -t geos-cbm -O -o overlay-demo.cvt -m overlay-demo.map overlay-demores.grc overlay-demo.c
|
cl65 -t geos-cbm -O -o overlay-demo.cvt -m overlay-demo.map overlay-demores.grc overlay-demo.c
|
||||||
</verb></tscreen>
|
</verb></tscreen>
|
||||||
Always place the <tt/.grc/ file as first input file on the command-line in order
|
Always place the <tt/.grc/ file as first input file on the command-line in order
|
||||||
to make sure that the generated <tt/.h/ file is available when it is needed for
|
to make sure that the generated <tt/.h/ file is available when it is needed for
|
||||||
inclusion by a <tt/.c/ file.
|
inclusion by a <tt/.c/ file.
|
||||||
|
|
||||||
You will almost certainly want to generate a map file that shows (beside a lot of
|
You will almost certainly want to generate a map file that shows (beside a lot of
|
||||||
other infos) how large your individual overlays are. This info is necessary to tune
|
other infos) how large your individual overlays are. This info is necessary to tune
|
||||||
the distribution of code into the overlays and optimizes the memory area reserved
|
the distribution of code into the overlays and to optimize the memory area reserved
|
||||||
for the overlays.
|
for the overlays.
|
||||||
|
|
||||||
|
|
||||||
<sect1>Building the GEOS application without cl65
|
<sect1>Building the GEOS application without cl65
|
||||||
<sect2>First step -- compiling the resources
|
<sect2>First step -- compiling the resources
|
||||||
<tscreen><verb>
|
<tscreen><verb>
|
||||||
grc65 -t geos-cbm overlay-demores.grc
|
grc65 -t geos-cbm overlay-demores.grc
|
||||||
</verb></tscreen>
|
</verb></tscreen>
|
||||||
|
|
||||||
<sect2>Second step -- assembling the application header
|
<sect2>Second step -- assembling the application header
|
||||||
<tscreen><verb>
|
<tscreen><verb>
|
||||||
ca65 -t geos-cbm overlay-demores.s
|
ca65 -t geos-cbm overlay-demores.s
|
||||||
</verb></tscreen>
|
</verb></tscreen>
|
||||||
|
|
||||||
<sect2>Third step -- compiling the code
|
<sect2>Third step -- compiling the code
|
||||||
<tscreen><verb>
|
<tscreen><verb>
|
||||||
cc65 -t geos-cbm -O overlay-demo.c
|
cc65 -t geos-cbm -O overlay-demo.c
|
||||||
ca65 -t geos-cbm overlay-demo.s
|
ca65 -t geos-cbm overlay-demo.s
|
||||||
</verb></tscreen>
|
</verb></tscreen>
|
||||||
|
|
||||||
<sect2>Fourth and last step -- linking it together
|
<sect2>Fourth and last step -- linking it together
|
||||||
<tscreen><verb>
|
<tscreen><verb>
|
||||||
ld65 -t geos-cbm -o overlay-demo.cvt -m overlay-demo.map overlay-demores.o overlay-demo.o geos.lib
|
ld65 -t geos-cbm -o overlay-demo.cvt -m overlay-demo.map overlay-demores.o overlay-demo.o geos.lib
|
||||||
</verb></tscreen>
|
</verb></tscreen>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<sect>Bugs and feedback
|
<sect>Bugs and feedback
|
||||||
<p>This is the first release of <bf/grc65/, and it contains bugs, for sure! I
|
<p>This is the first release of <bf/grc65/, 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
|
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
|
grammar rules strictly, then everything will crash. However, if you find an
|
||||||
interesting bug, mail me. :-) Mail me also for help with writing your
|
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
|
<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
|
comments also, and help on this file because I am sure that it can be written
|
||||||
better.
|
better.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<sect>Legal stuff
|
<sect>Legal stuff
|
||||||
<p><bf/grc65/ is covered by the same license as the whole cc65 package, so you
|
<p><bf/grc65/ 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
|
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
|
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
|
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">
|
actually used it. See <url name="the GEOSLib documentation" url="geos.html">
|
||||||
for addresses.
|
for addresses.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<appendix>
|
<appendix>
|
||||||
<sect>Appendix A -- example.grc<label id="example-grc">
|
<sect>Appendix A -- example.grc<label id="example-grc">
|
||||||
<p><tscreen><verb>
|
<p><tscreen><verb>
|
||||||
; Note that MENU can define both menues and submenues.
|
; Note that MENU can define both menues and submenues.
|
||||||
; If you want to use any C operators (such as "|", "&", etc.), do it WITHOUT
|
; 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).
|
; any spaces between the arguments (the parser is simple and weak).
|
||||||
|
|
||||||
MENU subMenu1 15,0 VERTICAL
|
MENU subMenu1 15,0 VERTICAL
|
||||||
; This is a vertical menu, placed at (15,0).
|
; This is a vertical menu, placed at (15,0).
|
||||||
{
|
{
|
||||||
; There are three items, all of them will call functions.
|
; There are three items, all of them will call functions.
|
||||||
; The first and third ones are normal functions, see GEOSLib documentation for
|
; 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).
|
; information about what the second function should return (it's a dynamic one).
|
||||||
"subitem1" MENU_ACTION smenu1
|
"subitem1" MENU_ACTION smenu1
|
||||||
"subitem2" MENU_ACTION|DYN_SUB_MENU smenu2
|
"subitem2" MENU_ACTION|DYN_SUB_MENU smenu2
|
||||||
"subitem3" MENU_ACTION smenu3
|
"subitem3" MENU_ACTION smenu3
|
||||||
}
|
}
|
||||||
|
|
||||||
;; Format: MENU "name" left,top ALIGN { "itemname" TYPE pointer ... }
|
;; Format: MENU "name" left,top ALIGN { "itemname" TYPE pointer ... }
|
||||||
|
|
||||||
MENU mainMenu 0,0 HORIZONTAL
|
MENU mainMenu 0,0 HORIZONTAL
|
||||||
; Here, we have our main menu, placed at (0,0), and it is a horizontal menu.
|
; 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
|
; Because it is a top-level menu, you would register it in your C source by
|
||||||
; using: DoMenu(&ero;mainMenu);
|
; using: DoMenu(&ero;mainMenu);
|
||||||
{
|
{
|
||||||
; There are two items -- a submenu and an action.
|
; There are two items -- a submenu and an action.
|
||||||
; This calls a submenu named subMenu1 (see previous definition).
|
; This calls a submenu named subMenu1 (see previous definition).
|
||||||
"first sub-menu" SUB_MENU subMenu1
|
"first sub-menu" SUB_MENU subMenu1
|
||||||
; This will work the same as an EnterDeskTop() call in C source code.
|
; This will work the same as an EnterDeskTop() call in C source code.
|
||||||
"quit" MENU_ACTION EnterDeskTop
|
"quit" MENU_ACTION EnterDeskTop
|
||||||
}
|
}
|
||||||
|
|
||||||
;; Format: HEADER <GEOS_TYPE> "dosname" "classname" "version"
|
;; Format: HEADER <GEOS_TYPE> "dosname" "classname" "version"
|
||||||
|
|
||||||
HEADER APPLICATION "MyFirstApp" "Class Name" "V1.0"
|
HEADER APPLICATION "MyFirstApp" "Class Name" "V1.0"
|
||||||
; This is a header for an APPLICATION which will be seen in the directory as a
|
; 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"
|
; file named MyFirstApp with the Class-string "Class Name V1.0"
|
||||||
{
|
{
|
||||||
; Not all fields are required, default and current values will be used.
|
; Not all fields are required, default and current values will be used.
|
||||||
author "Maciej Witkowiak" ; always in quotes!
|
author "Maciej Witkowiak" ; always in quotes!
|
||||||
info "Information text" ; always in quotes!
|
info "Information text" ; always in quotes!
|
||||||
; date yy mm dd hh ss ; always 5 fields!
|
; date yy mm dd hh ss ; always 5 fields!
|
||||||
; dostype seq ; can be: PRG, SEQ, USR (only all UPPER- or lower-case)
|
; dostype seq ; can be: PRG, SEQ, USR (only all UPPER- or lower-case)
|
||||||
; structure seq ; can be: SEQ, VLIR (only UPPER- or lower-case)
|
; structure seq ; can be: SEQ, VLIR (only UPPER- or lower-case)
|
||||||
mode c64only ; can be: any, 40only, 80only, c64only
|
mode c64only ; can be: any, 40only, 80only, c64only
|
||||||
}</verb></tscreen>
|
}</verb></tscreen>
|
||||||
</article>
|
</article>
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user