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