mirror of
https://github.com/cc65/cc65.git
synced 2024-06-02 04:41:35 +00:00
More SGML conversions, index page
git-svn-id: svn://svn.cc65.org/cc65/trunk@529 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
cuz
parent
c26903e302
commit
0d2f5c0ab5
|
|
@ -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 *~
|
||||
|
||||
|
|
|
|||
71
doc/index.sgml
Normal file
71
doc/index.sgml
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
<title>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>
|
||||
|
||||
251
doc/library.sgml
Normal file
251
doc/library.sgml
Normal file
|
|
@ -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>
|
||||
|
||||
|
||||
|
||||
239
doc/library.txt
239
doc/library.txt
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user