diff --git a/doc/Makefile b/doc/Makefile index 0a419ebb2..289d816fd 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -10,7 +10,10 @@ SGML = ar65.sgml \ cc65.sgml \ cl65.sgml \ dio.sgml \ - ld65.sgml + geos.sgml \ + index.sgml \ + ld65.sgml \ + library.sgml TXT = $(SGML:.sgml=.txt) HTML = $(SGML:.sgml=.html) @@ -50,6 +53,10 @@ info: $(INFO) .PHONY: dvi dvi: $(DVI) +# The index.html target is special, since it does not get splitted +index.html: index.sgml + sgml2html --split=0 $< + clean: rm -f *~ diff --git a/doc/index.sgml b/doc/index.sgml new file mode 100644 index 000000000..8d37aa7e4 --- /dev/null +++ b/doc/index.sgml @@ -0,0 +1,71 @@ + + +
+cc65 documentation overview +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>03.12.2000 + +<abstract> +Main documentation page, contains links to other available stuff. +</abstract> + +<sect>Documentation overview<p> + +<descrip> + + <tag><htmlurl url="BUGS" name="BUGS"></tag> + Known compiler bugs. + + <tag><htmlurl url="CREDITS" name="CREDITS"></tag> + Who helped with the compiler and tools? + + <tag><htmlurl url="ar65.html" name="ar65.html"></tag> + Describes the ar65 archiver. + + <tag><htmlurl url="ca65.html" name="ca65.html"></tag> + Describes the ca65 macro assembler. + + <tag><htmlurl url="cc65.html" name="cc65.html"></tag> + Describes the cc65 C compiler. + + <tag><htmlurl url="cl65.html" name="cl65.html"></tag> + Describes the cl65 compile & link utility. + + <tag><htmlurl url="coding.txt" name="coding.txt"></tag> + Containes hints on creating the most effective code with cc65. + + <tag><htmlurl url="compile.txt" name="compile.txt"></tag> + How to compile cc65 and the support tools. + + <tag><htmlurl url="debugging.txt" name="debugging.txt"></tag> + Debug programs using the VICE emulator. + + <tag><htmlurl url="geos.html" name="geos.html"></tag> + GEOSLib manual in several formats. + + <tag><htmlurl url="grc.txt" name="grc.txt"></tag> + grc.txt - Describes the GEOS resource compiler (grc). + + <tag><htmlurl url="index.html" name="index.html"></tag> + This file. + + <tag><htmlurl url="internal.txt" name="internal.txt"></tag> + internal.doc - A somewhat older text describing several cc65 internals. + + <tag><htmlurl url="intro.txt" name="intro.txt"></tag> + Describes the use of the tools by a short "hello world" example. + + <tag><htmlurl url="ld65.html" name="ld65.html"></tag> + Describes the ld65 linker. + + <tag><htmlurl url="library.html" name="library.html"></tag> + Describes the cc65 runtime and C libraries. + + <tag><htmlurl url="newvers.txt" name="newvers.txt"></tag> + Somewhat outdated. Lists the differences between the current cc65 release + and the original atari version created by J.R Dunning. + +</descrip> + +</article> + diff --git a/doc/internal.doc b/doc/internal.txt similarity index 100% rename from doc/internal.doc rename to doc/internal.txt diff --git a/doc/library.sgml b/doc/library.sgml new file mode 100644 index 000000000..c3a6a65ce --- /dev/null +++ b/doc/library.sgml @@ -0,0 +1,251 @@ +<!doctype linuxdoc system> + +<article> + +<title>cc65 Library Overview +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>02.12.2000 + +<abstract> +An overview over the runtime and C libraries that come with the cc65 compiler, +including a discussion of the differences to the ISO standard. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains a description of the library routines available for the +cc65 C compiler. It is not complete in some areas, so if you miss something, +have a look into the header files. All functions, that are not defined by the +ISO C standard have a short comment in the headers, explaining their use. + + + +<sect>ISO C compatible library<p> + +The C library contains a large subset of the ISO C library. Functions are +usually missing in areas, where there is no support on typical 6502 systems. +Wide character sets are an example for this. + +I will not go into detail about the ISO functions. If a function is not +mentioned here explicitly, expect it to be available and to behave as defined +in the C standard. + +Functions that are NOT available: + +<itemize> + + <item>ftell/fseek/fgetpos/fsetpos + + <item>tmpfile/tmpnam + + <item>The scanf family of functions + + <item>time/asctime/ctime/difftime/asctime/gmtime/localtime/mktime/strftime + + <item>system + + <item>All functions that handle floating point numbers in some manner. + + <item>The div and ldiv functions (because cc65 is not able to return + structs). + + <item>All functions handling wide character strings. + + <item>Signals and all related functions (having SIGSEGV would be cool:-) + + <item>rename/remove/rewind + + <item>setbuf/setvbuf/ungetc + +</itemize> + +Functions that are limited in any way: + +<itemize> + + <item>fopen/fread/fwrite/fclose/fputs/fgets/fscanf.... + + These functions are built on open/read/write/close. Neither of these low + level functions is currently available for the supported systems, and so, + fopen and friends do not work. However, the functions exist and are tested + to some degree under the ACE operating systems (which is no longer + supported). + + + <item>The va_... family of macros + + The macros do not work completely as defined by the standard. Since cc65 has + the wrong calling order, the (non-standard) va_fix macro must be used to + access fixed parameters in functions with a variable parameter size. See + newvers.txt for a discussion of the problem. + + <item>strcspn/strpbrk/strspn + + These functions have a length limitation of 256 for the second string + argument. Since this string gives a character set, and there are only 256 + distinct characters, this shouldn't be a problem. + + <item>getenv + + Since there is no such thing as an environment on all supported systems, the + getenv function will always return a NULL pointer. + + + <item>locale + + There is no other locale than the "C" locale. The native locale is identical + to the "C" locale. + +</itemize> + + +In addition to these limitations, some more functions are limited if inlined +versions are requested by using -Os: + +<itemize> + + <item>The strlen function only works for strings with a maximum length of + 255 characters. + + <item>The isxxx character classification functions from <tt/<ctype.h>/ + will give unpredictable results if the argument is not in character range + (0..255). This limitation may be removed by #undef'ing the function name + (when using -Os, the functions are actually macros that expand to inline + assembler code, but the real functions are still available if the macro + definition is removed). + +</itemize> + + + +<sect>CPU specific stuff - 6502.h<p> + +The header file 6502.h contains some functions that make only sense with the +6502 CPU. Examples are macros to insert more or less useful instructions into +your C code, or a function to call arbitrary machine language subroutines, +passing registers in and out. + + + +<sect>Target specific stuff<p> + +For each supported system there's a header file that contains calls or defines +specific for this system. So, when programming for the C64, include c64.h, for +the C128, include c128.h and so on. To make the task for the Commodore systems +easier, there is also a header file named cbm.h that will define stuff common +for all CBM systems, and include the header file for the specific target +system. + +The header files contain + +<itemize> + + <item>Defines for special keys (like function keys) + + <item>Defines for special characters (like the graphics characters) + + <item>Variables with a fixed address in memory that may be used to access + special hardware. For the C64 and C128 there is a variable struct named + <tt/SID/. Writing to the fields of this struct will write to the SID device + instead. Using these variables will make your program more readable and more + portable. Don't fear ineffective code when using these variables, the + compiler will translate reads and writes to these structs into direct memory + accesses. + + <item>Other routines that make only sense for a specific system. One example + are routines to write memory locations in the system bank for the CBM + 600/700 family (called B128/B256 in the US). + +</itemize> + + +<sect>Direct console I/O - <tt/conio.h/<p> + +The <tt/conio.h/ header file contains a large set of functions that do screen +and keyboard I/O. The functions will write directly to the screen or poll the +keyboard directly with no more help from the operating system than needed. +This has some disadvantages, but on the other side it's fast and reasonably +portable. conio implementations exist for the following targets: + + <itemize> + <item>atari + <item>c64 + <item>c128 + <item>plus4 + <item>cbm610 (all CBM series-II computers with 80 column video) + <item>pet (all CBM PET systems except the 2001) + <item>apple2 + </itemize> + +The conio.h header file does also include the system specific header files +which define constants for special characters and keys. + + + +<sect>Using the joystick - <tt/joystick.h/<p> + +For systems that have a joystick, <tt/joystick.h/ will define a subroutine to +read the current value, including constants to evaluate the result of this +function. To help in writing portable code, the header file will define the +symbol <tt/__JOYSTICK__/ on systems that have a joystick. + + + +<sect>Using a mouse - <tt/mouse.h/<p> + +Some target machines support a mouse. Mouse support is currently in beta and +available for the following targets: + + <itemize> + <item>atari + <item>c64 + </itemize> + +The available functions are declared in <tt/mouse.h/ To help writing portable +code, the header file will define the symbol <tt/__MOUSE__/ in systems that +support a mouse. + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +This C runtime library implementation for the cc65 compiler is (C) +Copyright 1998-1999 Ullrich von Bassewitz. For usage of the binaries +and/or sources the following conditions do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + + + diff --git a/doc/library.txt b/doc/library.txt deleted file mode 100644 index 22c44fb25..000000000 --- a/doc/library.txt +++ /dev/null @@ -1,239 +0,0 @@ - - - Description of the C library for the cc65 C compiler - - (C) Copyright 1998-1999 Ullrich von Bassewitz - (uz@musoftware.de) - - - -Contents --------- - - 1. Overview - - 2. ISO C compatible library - - 3. CPU specific stuff - 6502.h - - 4. System specific stuff - - 5. Direct console I/O - conio.h - - 6. Using the joystick - joystick.h - - 7. Bugs/Feedback - - 8. Copyright - - - -1. Overview ------------ - -This file contains a description of the library routines available for the -cc65 C compiler. It is not complete in some areas, so if you miss -something, have a look into the header files. All functions, that are not -defined by the ISO C standard have a short comment in the headers, -explaining their use. - - - -2. ISO C compatible library ---------------------------- - -The C library contains a large subset of the ISO C library. Functions are -usually missing in areas, where there is no support on typical 6502 -systems. Wide character sets are an example for this. - -I will not go into detail about the ISO functions. If a function is not -mentioned here explicitly, expect it to be available and to behave as -defined in the C standard. - - -Functions that are NOT available: - - * ftell/fseek/fgetpos/fsetpos - - * tmpfile/tmpnam - - * The scanf family of functions - - * time/asctime/ctime/difftime/asctime/gmtime/localtime/mktime/strftime - - * system - - * All functions that handle floating point numbers in some manner. - - * The div and ldiv functions (because cc65 is not able to return - structs). - - * All functions handling wide character strings. - - * Signals and all related functions (having SIGSEGV would be cool:-) - - * rename/remove/rewind - - * setbuf/setvbuf/ungetc - - - -Functions that are limited in any way: - - * fopen/fread/fwrite/fclose/fputs/fgets/fscanf.... - - These functions are built on open/read/write/close. Neither of these - low level functions is currently available for the supported systems, - and so, fopen and friends do not work. However, the functions exist - and are tested to some degree under the ACE operating systems (which - is no longer supported). - - - * The va_... family of macros - - The macros do not work completely as defined by the standard. Since cc65 - has the wrong calling order, the (non-standard) va_fix macro must be used - to access fixed parameters in functions with a variable parameter size. - See newvers.txt for a discussion of the problem. - - - * strcspn/strpbrk/strspn - - These functions have a length limitation of 256 for the second string - argument. Since this string gives a character set, and there are only 256 - distinct characters, this shouldn't be a problem. - - - * Since there is no such thing as an environment on all supported - systems, the getenv function will always return a NULL pointer. - - - * There is no other locale than the "C" locale. The native locale is - identical to the "C" locale. - - -In addition to these limitations, some more functions are limited if inlined -versions are requested by using -Os: - - * The strlen function only works for strings with a maximum length of - 255 characters. - - * The isxxx character classification functions from <ctype.h> will give - unpredictable results if the argument is not in character range - (0..255). This limitation may be removed by #undef'ing the function - name (when using -Os, the functions are actually macros that expand to - inline assembler code, but the real functions are still available if - the macro definition is removed). - - - -3. CPU specific stuff - 6502.h ------------------------------- - -The header file 6502.h contains some functions that make only sense with -the 6502 CPU. Examples are macros to insert more or less useful -instructions into your C code, or a function to call arbitrary machine -language subroutines, passing registers in and out. - - - -4. System specific stuff ------------------------- - -For each supported system there's a header file that contains calls or -defines specific for this system. So, when programming for the C64, -include c64.h, for the C128, include c128.h and so on. To make the task -for the Commodore systems easier, there is also a header file named cbm.h -that will define stuff common for all CBM systems, and include the header -file for the specific target system. - -The header files contain - - * Defines for special keys (like function keys) - - * Defines for special characters (like the graphics characters) - - * Variables with a fixed address in memory that may be used to access - special hardware. For the C64 and C128 there is a variable struct - named "sid". Writing to the fields of this struct will write to the - SID device instead. Using these variables will make your program more - readable and more portable. Don't fear ineffective code when using - these variables, the compiler will translate reads and writes to these - structs into direct memory accesses. - - * Other routines that make only sense for a specific system. One example - are routines to write memory locations in the system bank for the CBM - 600/700 family (called B128/B256 in the US). - - - -5. Direct console I/O - conio.h -------------------------------- - -The conio header file contains a large set of functions that do screen and -keyboard I/O. The functions will write directly to the screen or poll the -keyboard directly with no more help from the operating system than needed. -This has some disadvantages, but on the other side it's fast and -reasonably portable. conio implementations exist for the following -targets: - - c64 - c128 - plus/4 - cbm610 (that is, the complete 600/700 series) - pet (all PETs except the 2001) - apple 2 - atari - -The conio.h header file does also include the system specific header files -which define constants for special characters and keys. - - - -6. Using the joystick - joystick.h ----------------------------------- - -For systems that have a joystick, joystick.h will define a subroutine to -read the current value, including constants to evaluate the result of this -function. To help in writing portable code, the header file will define -the symbol __JOYSTICK__ on systems that have a joystick. - - - -7. Bugs/Feedback ----------------- - -If you have problems using the library, if you find any bugs, or if you've -written some extensions or otherwise interesting programs, I would be glad -to hear from you. Feel free to contact me by email (uz@musoftware.de). - - - -8. Copyright ------------- - -This C runtime library implementation for the cc65 compiler is (C) -Copyright 1998-1999 Ullrich von Bassewitz. For usage of the binaries -and/or sources the following conditions do apply: - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -2. Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -3. This notice may not be removed or altered from any source - distribution. - - - - - diff --git a/doc/readme.txt b/doc/readme.txt deleted file mode 100644 index 6e35dd158..000000000 --- a/doc/readme.txt +++ /dev/null @@ -1,43 +0,0 @@ - -Documentation overview: - - - BUGS - Known compiler bugs. - - CREDITS - Who helped with the compiler and tools? - - ar65.txt - Describes the ar65 archiver. - - ca65.txt - Describes the ca65 macro assembler. - - cc65.txt - Describes the cc65 C compiler. - - cl65.txt - Describes the cl65 compile & link utility. - - coding.txt - Containes hints on creating the most effective code - with cc65. - - compile.txt - How to compile cc65 and the support tools. - - debugging.txt - Debug programs using the VICE emulator. - - geos.* - GEOSLib manual in several formats. - - grc.txt - Describes the GEOS resource compiler (grc). - - internal.doc - A somewhat older text describing several cc65 internals. - - intro.txt - Describes the use of the tools by a short "hello world" - example. - - ld65.txt - Describes the ld65 linker. - - library.txt - Describes the cc65 runtime and C libraries. - - newvers.txt - Somewhat outdated. Lists the differences between the - current cc65 release and the original atari version - created by J.R Dunning. - - readme.txt - This file. - -