empathicqubit/cc65
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updated first part of the grc65 doc.

Browse source 
git-svn-id: svn://svn.cc65.org/cc65/trunk@5321 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
ol.sc 2011-12-27 02:09:27 +00:00
parent 2f646eb01a
commit 9b1ff636c5
1 changed files with 37 additions and 57 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

94
doc/grc65.sgml
View file

@ -8,8 +8,8 @@
<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
and VLIR files from, cc65-compiled programs. cc65-compiled programs.
</abstract> </abstract>
<!-- Table of contents --> <!-- Table of contents -->
@ -28,30 +28,21 @@ 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 VLIR-structured files. along with support for building VLIR-structured files.
<bf/grc65/ generates output in three formats: C header, <bf/ca65/ source (.s), <bf/grc65/ generates output in two formats: C header and <bf/ca65/ source (.s).
and, for linking VLIR, <bf/ld65/ configuration script. That is because That is because the application header data must be in assembly format, while
application header data must be in assembly format, while menu definitions can the menu definitions can be translated easily into C. The purpose of the C
be translated easily into C. The purpose of the C file is to include it as a file is to include it as a header in only one project file. The assembly source
header in only one project file. The assembly source should be processed by should be processed by <bf/ca65/ and linked to the application (read about
<bf/ca65/, and linked as the first object (read about <ref name="the building <ref name="the building process" id="building-seq">).
process" id="building-seq">). The VLIR structure currently is supported for
only projects that are written entirely in assembly code.
<bf/grc65/ can be used also as a handy VLIR linker -- used to build
VLIR-structured <tt/.cvt/ files out of prepared binary chains.
<sect>Usage <sect>Usage
<p>grc65 accepts the following options:<tscreen><verb> <p>grc65 accepts the following options:<tscreen><verb>
-f force the writing of the output files -h, -? this help
-o name name the .c output file -f force writing files
-s name name the .s output file -o name name the C output file
-l name name the ld65 output file -s name name the asm output file
-h show this help
</verb></tscreen>
When used as a VLIR linker, the correct syntax is:<tscreen><verb>
grc65 -vlir output.cvt header.bin vlir0.bin vlir1.bin ...
</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/. <bf/grc65/ will not overwrite existing files unless forced <tt/.h/ and <tt/.s/. <bf/grc65/ will not overwrite existing files unless forced
@ -113,19 +104,18 @@ HEADER <GEOS_TYPE> "dosname" "classname" "version" {
dostype SEQ dostype SEQ
mode any mode any
structure SEQ structure SEQ
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. Currently, there's no way to change the default <bf/grc65/ icon each file. The definition starts with the keyword <tt/HEADER/, then goes the
(an empty frame). It will be possible in the next version. The definition GEOS file-type. You can use only <tt/APPLICATION/ here at the moment. Then,
starts with the keyword <tt/HEADER/, then goes the GEOS file-type. You can use there are (each one in quotes) the DOS file-name (up to 16 characters), the GEOS
only <tt/APPLICATION/ here at the moment. Then, there are (each one in quotes) Class name (up to 12 characters), and the version info (up to 4 characters).
the DOS file-name (up to 16 characters), the GEOS Class name (up to 12 The version should be written as &dquot;<tt/V/x.y&dquot;, where <em/x/ is the
characters), and the version info (up to 4 characters). The version should be major, and <em/y/ is the minor, version number. Those fields, along with both
written as &dquot;<tt/V/x.y&dquot;, where <em/x/ is the major, and <em/y/ is braces, are required. The lines between braces are optional, and will be replaced
the minor, version number. Those fields, along with both braces, are required. by default and current values. The keyword <tt/author/ and its value in quotes name
The lines between braces are optional, and will be replaced by default and the programmer, and can be up to 63 bytes long. <tt/info/ (in the same format) can
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 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/,
@ -137,36 +127,26 @@ it describes system requirements. <tt/any/ will work on both 64-GEOS and
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 VLIR-table then, you also have to put in a third type of resource -- a VLIR-table
description. description. 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 when the generated assembly source is be processed by <bf/ca65/. Examples
for programs generating such files are <em/Sprite Painter/ and <em/SpritePad/.
<sect1>VLIR table description <sect1>VLIR table description
<p><tscreen><verb> <p><tscreen><verb>
VLIR headname address { VLIR size {
vlir0 0
blank 1
vlir2 2
blank 4
vlir4 5
}</verb></tscreen> }</verb></tscreen>
The first element is the keyword <tt/VLIR/, then goes the name for the header The first element is the keyword <tt/VLIR/, then goes the size for all VLIR chains
binary file (read below), and the base address for all VLIR chains that are that are different from 0. It can be either decimal (e.g., <tt/4096/) or hexadecimal
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 VLIR chain
with a <tt/0x/ prefix (e.g., <tt/0x1000/). Then, between braces are the names numbers used by the application. Skipped numbers denote empty chains. In the example,
of VLIR chain binaries or the keyword <tt/blank/ which denotes empty chains. chains #3 is missing. Read <ref name="this description" id="building-vlir"> for details.
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/grc65/ 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/grc65/. 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.