cc65 version 2.13.0: What's in the box for the apple2 programmer
Oliver Schmidt
Four days ago Uz announced here cc65 2.13.0. and pointed out some new
features and improvements in general. With this posting I'd like to go
into more details regarding Apple][ specific topics:
For cc65 2.13.0 I didn't do just the things I personally considered
cool but rather explicitly worked through a (virtual) list of concerns
brought up by cc65 users:
- 80 column mode
Now there's a function videomode() allowing you to switch between 40
and 80 column mode. It clears the screen only if absolutely necessary
so you can safely call it to assert the desired mode "just in case".
- Make
Now there's documentation on how to use GNU Make with cc65:
http://www.cc65.org/doc/make.html
It contains a fully functional sample Makefile that works both with
cc65 and GCC thus showing how to integrate cc65 into multi toolchain
builds, especially when it comes to state-of-the-art auto dependency
generation.
- Overlays
Now there's a fully functional sample program 'overlaydemo'
demonstrating the (already for years present) cc65 designtime and
runtime overlay support in order to get users on the right track
easily.
- Linker configs
Up to now you could only choose between the builtin linker
configuration and your own linker configuration (by creating a linker
config file). However not every cc65 user is interested in authoring
linker config files...
Now there are secondary linker configurations which are linker config
files in the very same format as user linker config files - but coming
with cc65. Check out the documentation for the various secondary
linker configurations available:
http://www.cc65.org/snapshot-doc/apple2-4.html
- "Native" ProDOS system programs
My personal motivation to run my code as ProDOS system program was the
pure need of as much RAM as possible. From that perspective my
approach of a minimalistic system program acting as bootstrap to load
the actual program (LOADER.SYSTEM) was - and still is - optimal.
However I realized that others may have other reasons to run their
code as system program, and for them the need of the additional
(bootstrap) file is awkward...
Now every cc65 program can run both as binary program (type BIN file)
and as system program (type SYS file). To get a system program You
simply have to link your code to the start address $2000 and copy it
to the ProDOS filesystem as SYS file.
To further simplify the task there's a secondary linker configuration
(apple2[enh]-system.cfg) that
- fixes the start address to $2000
- omits the 4 byte DOS 3.3 header not useful here
So producing a ProDOS system program from test.c for the enhanced //e
can be done by:
cl65 -t apple2enh -C apple2enh-system.cfg hello.c
- Size reduction for certain ProDOS system programs
If your ProDOS system program does file I/O but does not use the C
heap you can reduce the code - and thus program file - size by more
than 1400 bytes by placing the necessary 1 KB ProDOS I/O buffers
between $800 and $2000 instead of allocating them on the C heap. Check
out the documentation to find out how:
http://www.cc65.org/snapshot-doc/apple2-5.html
Have fun, Oliver
datajerk
Congrats and thanks!
John B. Matthews
wrote:
[...]
> - 80 column mode
>
> Now there's a function videomode() allowing you to switch between 40
> and 80 column mode. It clears the screen only if absolutely
> necessary so you can safely call it to assert the desired mode "just
> in case".
Excellent! I see some of my earlier efforts were ignoring the ROM/LC
switches.
[...]
> - "Native" ProDOS system programs
[...]
Works like a dream:
cl65 -t apple2enh -C apple2enh-system.cfg hello.c
ac -d p1.po hello
ac -p p1.po hello sys < hello
Now I see why gcc.mak copies *-*.cfg to ${prefix}/lib/cc65/cfg.
While reading the assembly source for videomode(), I was curious about
calling conventions for assembly routines. I found this Internals
documentation:
<http://www.cc65.org/doc/internal.txt>
Thanks!
--
John B. Matthews
trashgod at gmail dot com
<http://sites.google.com/site/drjohnbmatthews>
Oliver Schmidt
>Congrats and thanks!
You're welcome!
Best, Oliver
Oliver Schmidt
>Excellent! I see some of my earlier efforts were ignoring the ROM/LC
>switches.
Yeah, at some point I "just" recognized it - and the first test were
three lines of inline assembly switching in ROM, JSRing to $C300 and
switching in LC again, which worked right away :-)
Then the rest was only icing on the cake...
>[...]
>> - "Native" ProDOS system programs
>[...]
>
>Works like a dream:
Thanks for the positive feedback :-)
> cl65 -t apple2enh -C apple2enh-system.cfg hello.c
> ac -d p1.po hello
> ac -p p1.po hello sys < hello
That's the very way it's supposed to be used...
The new docs even explicitly point out to use AC option -p (and not
-cc65) with those files !
>Now I see why gcc.mak copies *-*.cfg to ${prefix}/lib/cc65/cfg.
;-)
>Thanks!
You're welcome, Oliver
John B. Matthews
wrote:
> > cl65 -t apple2enh -C apple2enh-system.cfg hello.c
> > ac -d p1.po hello
> > ac -p p1.po hello sys < hello
>
> That's the very way it's supposed to be used...
>
> The new docs even explicitly point out to use AC option -p (and not
> -cc65) with those files !
I found these references to Apple specific material:
<http://www.cc65.org/doc/apple2.html>
<http://www.cc65.org/doc/apple2enh.html>
<http://www.cc65.org/doc/intro-6.html#ss6.1>
but I can't find the specific reference to using secondary
configurations, mentioned here:
<http://www.cc65.org/doc/ld65-5.html#ss5.12>
Sorry if I'm overlooking it. Any pointers?
Bill Buckels
>Now there's a fully functional sample program 'overlaydemo' demonstrating
>the (already for years present) cc65 designtime and runtime overlay support
>in order to get users on the right track easily.
I am assuming that by "overlays", you are able to call functions in the root
module from within the overlay? Otherwise this would not be an overlay. Also
I am assuming that you are able to pass variable numbers of arguments to
overlays and share variables between the root module and overlays and to
nest overlays within overlay? Otherwise this would not be an overlay.
If this is not the case then users have been derailed from the "right track"
by cavalier use of incorrect terminology. However if this is truly overlay
support at the equivalent level of other development environments like
Clarion 2 for MS-DOS or Aztec C for many platforms including Z80, 8086, 68K
and 6502 then congratulations!
Also users who REALLY want to get on the right track with using overlays can
download FULL FEATURED commercial projects from the Aztec C website and need
not fool with demos if they want REAL WORLD code examples.
Bill
John B. Matthews
"John B. Matthews" <nos...@nospam.invalid> wrote:
> I can't find the specific reference to using secondary
> configurations, mentioned here:
>
> <http://www.cc65.org/doc/ld65-5.html#ss5.12>
>
> Sorry if I'm overlooking it. Any pointers?
Oops, my bad. The updated docs can be browsed here:
<http://www.cc65.org/snapshot-doc/apple2enh.html>
And downloaded here:
<ftp://ftp.musoftware.de/pub/uz/cc65/snapshot/
cc65-snapshot-doc-2.13.9.20091016-1.zip>
The overlays{.c,*.cfg} samples explain more:
John B. Matthews
"Bill Buckels" <bbuc...@mts.net> wrote:
> "Oliver Schmidt" <ol...@web.de> wrote:
> >- Overlays
>
> >Now there's a fully functional sample program 'overlaydemo'
> >demonstrating the (already for years present) cc65 designtime and
> >runtime overlay support in order to get users on the right track
> >easily.
>
> I am assuming that by "overlays", you are able to call functions in
> the root module from within the overlay?
I'm still learning how to use custom linker configurations, but the
sample code shows calling both ways:
]-overlaydemo
Log: Calling overlay 1 from main
Log: Calling main from overlay 1
Log: Calling overlay 2 from main
Log: Calling main from overlay 2
Log: Calling overlay 3 from main
Log: Calling main from overlay 3
> Also I am assuming that you are able to pass variable numbers of
> arguments to overlays and share variables between the root module and
> overlays
The demo shows overlain code segments, but shared data segments look
straightforward. AFAICT, you don't have to pass arguments; the shared
symbols are resolved at link time. I think you could even use the
language card, as the Kyan KIX shell does.
BTW, the sample code Makefile expects SYS to be defined, e.g.:
$ make SYS=apple2enh overlaydemo
The default is c64, which didn't quite work. :-)
Bill Buckels
"John B. Matthews" <nos...@nospam.invalid> wrote:
>code shows calling both ways:
Very cool then, Dr. John.
>The default is c64, which didn't quite work. :-)
I ported my Aztec C Apple //e overlay project "What Time Is It?" to the c64
under Aztec C. I swear it's a better program mainly because of the sound
playback on the SID chip... best not to sell the c64 short:)
Here's the Apple Version
http://www.appleoldies.ca/steps.htm
Source: http://www.aztecmuseum.ca/projects.htm
Download - http://www.aztecmuseum.ca/timex.zip
ReadMe - http://www.aztecmuseum.ca/docs/timex.txt
User - http://www.aztecmuseum.ca/docs/timexuser.txt
Here's the c64 Version
http://www.c64classics.ca/index.htm#time
Download - http://www.aztecmuseum.ca/time64.zip
ReadMe - http://www.aztecmuseum.ca/docs/time64.txt
User - http://www.aztecmuseum.ca/docs/time64user.txt
That Aztec C Projects Page has some other Overlay Stuff for the Apple //e on
it as well...
http://www.aztecmuseum.ca/metoox.zip
ReadMe - http://www.aztecmuseum.ca/docs/metoox.txt
User Versions - http://www.appleoldies.ca/metoo.zip
English Manual - http://www.appleoldies.ca/MeToo.pdf
French Manual - http://www.appleoldies.ca/MoiAussi.pdf
I'd take a peek especially at that last one if I were taking a poke at
overlays.
Bill
Oliver Schmidt
>I am assuming that by "overlays", you are able to call functions in the root
>module from within the overlay? Otherwise this would not be an overlay.
Because I agree with that perspective the sample program (maybe you
want to take a look at it ;-) demonstrates this very aspect of
overlays - as John already wrote...
>Also
>I am assuming that you are able to pass variable numbers of arguments to
>overlays and share variables between the root module and overlays and to
>nest overlays within overlay? Otherwise this would not be an overlay.
Because of the complexities I suspect behind your questions about
cross overlay data access the cc65 approach only overlays code so all
data is always shared - as John basically already wrote...
>If this is not the case then users have been derailed from the "right track"
>by cavalier use of incorrect terminology.
If you say so ;-))
>However if this is truly overlay
>support at the equivalent level of other development environments like
>Clarion 2 for MS-DOS or Aztec C for many platforms including Z80, 8086, 68K
>and 6502 then congratulations!
I don't know any of those environments so I can't compare. However I'm
pretty sure that they all very well go beyond what cc65 offers.
>Also users who REALLY want to get on the right track with using overlays can
>download FULL FEATURED commercial projects from the Aztec C website and need
>not fool with demos if they want REAL WORLD code examples.
I case you haven't noticed: This thread is about cc65, not any other C
compiler. If you need yet another thread for your DULL advertisement
please open your OWN but keep this one alone.
(Just imitating your offensive UPPERCASE style for demonstration
purposes...)
Best, Oliver
Bill Buckels
"Oliver Schmidt" <ol...@web.de> wrote:
>I case you haven't noticed: This thread is about cc65, not any other C
>compiler.
In case you haven't noticed the discussion for this fork in the thread was
about overlays and not some DULL advertisement for cc65.
If you need yet another newsgroup for cc65 discussion or your OWN internet
please open one.
(Just imitating your UPPERCASE demonstration for offensive purposes:)
If I want to talk about another C compiler in this thread I will darned well
do so, and I did so darned well:)
John B. Matthews
wrote:
[...]
> The sample program ... demonstrates this very aspect of overlays.
I found the example very instructive, but I noticed a small anomaly.
The comments in the file overlaydemo-apple2enh.cfg helpfully mention
how to transfer the overlays to an Apple disk image, e.g.
# java -jar ac.jar -p prodos.dsk overlaydemo.1 bin < overlaydemo.1
Because the overlays don't have a start header, I think the address
must be specified explicitly, as shown below:
SYS=apple2enh
OVER=overlaydemo
${OVER}: ${OVER}.c
cl65 -t ${SYS} -C ${OVER}-${SYS}.cfg -m ${OVER}.map ${OVER}.c --lib ${SYS}.lib
ac -cc65 prodos.po ${OVER} bin < ${OVER}
ac -p prodos.po ${OVER}.1 bin 0x803 < ${OVER}.1
...
I wonder if it would be helpful to use the make syntax in the comments?
mdj
> Also users who REALLY want to get on the right track with using overlays can
> download FULL FEATURED commercial projects from the Aztec C website and need
> not fool with demos if they want REAL WORLD code examples.
Actually, a contrived example of how to get the boilerplate down for
overlays is exactly what I'd be looking for if I was interested in
using them. Having to wade through an entire application just to find
a few relevant lines of code would be a tedious waste of my time.
I think this is an area where the Aztec-C community could learn a
thing or two from the cc65 community. If only they'd add a section to
their manual on how to avoid bitching and whining about the
comparative feature set of a competing project...
Tongue now firmly out of cheek. Bill, knock it off. Both projects are
providing value to the community, and your extremely inappropriate
imitation of a corporate shill is only damaging your own reputation
and the standing of Aztec-C. Hopefully people out there who really
wanted to ask a question haven't avoided doing so on account of your
antisocial behaviour.
Matt
Bill Buckels
Ok... but some points. cc65 is adding features that have been present in
Aztec C for 20-30 years lile PrODOS SYS programs and Overlays. Good to see
but also in many areas such as standard syntax like inline assembly and
printing to a device without resorting to assembly, Aztec C's approach is
cleaner and probably cc65 should re-examine and try to learn.
There really is no competition nor comparative feature set in cc65... Aztec
C is no longer in devlopment but is still pretty good.
However when you mention these things the whole cc65 says their way is the
right way and that's the end of the discussion. I have found this in both
the c64 and apple2 cc65 users and always want to make sure that new users
understand that Aztec C is an alternative.
Nor amd I wrong for providing "extra" information that I feel is relevant
despite the fact that an OP did not ask a question.
Bill
U. v. Bassewitz
Bill Buckels <bbuc...@mts.net> wrote:
> Ok... but some points. cc65 is adding features that have been present in
> Aztec C for 20-30 years lile PrODOS SYS programs and Overlays.
Would you please stay to the facts? Both of your statements are plain
wrong.
ld65 (the linker that comes with cc65) has been able to do overlays from
day one. Contiki was initially written using cc65, and it has used
overlays in very early stages.
What is new in version 2.13 is just a sample program that helps new users
to get started using overlays. This sample program will also work with
older versions of cc65.
The same is true for ProDOS SYS programs: It has been possible to create
them for a long time. Version 2.13 of cc65 simplifies this, but didn't
add the feature.
> There really is no competition nor comparative feature set in cc65... Aztec
> C is no longer in devlopment but is still pretty good.
I'm for sure biased, but see here for my personal experience with Aztec C:
http://www.cc65.org/mailarchive/2009-10/7171.html
See here for a few benchmark numbers (usual disclaimer about benchmarks
applies):
http://www.cc65.org/mailarchive/2009-10/7172.html
See here for some more numbers comparing cc65 2.12 and 2.13:
http://www.cc65.org/mailarchive/2009-09/6816.html
To compare the numbers listed under b. in above posting to Aztec C, you
may use this list:
http://www-aix.gsi.de/~kraemer/COLLECTION/dhryst.txt
The relevant numbers can be found under "DHRYSTONE 1.1 BENCHMARK SUMMARY".
Aztec C version 1.05 seems to be rated at 37 dhrystones, which means that
code generated for this benchmark by cc65 is twice as fast, even on the
C64, which is about 10% slower than the Apple.
One can of course write a benchmark to prove almost anything, but what
I've seen until now is that Aztec C generates larger and slower code for
every single example not specially choosen.
How about compiling a few test programs to compare the output and runtime?
I'm willing to send you whatever I have so you can compile it using Aztec
C and post the numbers. This is also true the other way round, so if you
have programs that qualify using 1.-3. from
http://www.cc65.org/mailarchive/2009-09/6816.html
you can send them to me. I will compile them and post the numbers.
> However when you mention these things the whole cc65 says their way is the
> right way and that's the end of the discussion. I have found this in both
> the c64 and apple2 cc65 users and always want to make sure that new users
> understand that Aztec C is an alternative.
I would say it's an alternative, provided that most of the following is
given:
* You aren't forced to use the C64 version of Aztec C, which is really,
really old. The version for the Apple (3.2) seems to be better, but I
have no personal experience with it.
* You're using Windows or DOS as a host. Aztec C is a DOS application and
using it in dosbox under Linux is very inconvenient.
* Your program is very uncritical regarding speed or size.
* Your program doesn't rely on standard C functions.
* Your program doesn't use snippets of code from a PC or similar.
* You're not going to support other targets than the Apple (and maybe
the C64 - but see above).
* You're using floats.
The last point may actually be a killer argument for Aztec C. Apart from
that, most arguments favour cc65:
* Standard C syntax, but understands old K&R.
* Available for more than a dozen platforms. Many programs can be
written to be compiled on more than one platform.
* Actively developed. cc65 improves with every version while Aztec C
is in the same state it was about 25 years ago.
* Faster and smaller code in most cases.
* Verbose error messages and warnings for problematic or dubious code.
Here is an example of how cc65 helps you in development:
---------------------------------------------------------------------
#include <stdio.h>
int a;
int noreturn () /* This function does not return a value */
{
char a; /* Unused parameter */
}
int main ()
{
a = noreturn ();
if (a & 0x80 == 0) { /* Missing parens around & */
printf ("Bit 7 of a is set\n");
}
return 0;
}
---------------------------------------------------------------------
This program contains some problems. When compiled with cc65, the
following warnings are output:
test.c(8): Warning: Control reaches end of non-void function
test.c(8): Warning: `a' is defined but never used
test.c(13): Warning: Result of comparison is constant
When compiled with either, Aztec C 1.05, or Aztec C 3.2, you don't get
a single hint that your program won't work as expected!
> Nor amd I wrong for providing "extra" information that I feel is relevant
> despite the fact that an OP did not ask a question.
I don't have a problem with extra information. But I have a problem with
wrong statements as the ones that started your post.
Regards
Uz
--
Ullrich von Bassewitz u...@spamtrap.musoftware.de
13:01:36 up 2 days, 17:20, 14 users, load average: 0.08, 0.20, 0.35
Oliver Schmidt
>I found the example very instructive,
Thanks for the postive feedback :-)
> but I noticed a small anomaly.
>The comments in the file overlaydemo-apple2enh.cfg helpfully mention
>how to transfer the overlays to an Apple disk image, e.g.
>
># java -jar ac.jar -p prodos.dsk overlaydemo.1 bin < overlaydemo.1
Yes, that's the way it's supposed to work.
>Because the overlays don't have a start header, I think the address
>must be specified explicitly, as shown below:
> [...]
> ac -p prodos.po ${OVER}.1 bin 0x803 < ${OVER}.1
I'm not sure where you are heading to with your statement...
1. AppleCommander syntax:
http://applecommander.sourceforge.net/acguide.html says
-p <imagename> <filename> <type> [[$|0x]<addr>]
so it's legal to omit the address. It then defaults to 0x2000.
2. Semantic:
The ProDOS 8 aux type is used by BIN files to carry the default load
address. But this is solely something used by BASIC.SYSTEM's command
BRUN/BLOAD (and here only when omitting the A option).
The overlay files are however loaded by the cc65 program using the
cc65 C library which calls the ProDOS MLI. And with the ProDOS MLI
it's up to the caller if he looks into the aux type for the load
address of if he determines the load address in another way.
The latter is the case here: The cc65 program uses the standard POSIX
calls open(), read(), close() to access the overlay files. And read()
requires the caller to supply the buffer address. And this buffer
address is determined by a symbol generated by the cc65 linker into
the main program. So the main program just "knows by heart" where to
load the overlays and doesn't need the ProDOS aux type hint - so after
all the aux type just doesn't matter.
If you think the default 0x2000 is misleading you may want to specify
0x0000 in your AppleCommander call but for the sake of simplicity I
didn't do so in the cfg file comment.
BTW: If you create a file using cc65 via open() then it's a BIN file
with aux type 0x0000...
>I wonder if it would be helpful to use the make syntax in the comments?
Using make seems a quite advanced approach for most cc65 usecases.
Most projects are so small and cc65 is so fast :-) that some shell
script simply rebuilding from scratch every time is just fine for most
cc65 users. Therefore I intentionally didn't want to mix in make
complexity in this as-simple-as-possible demo - although I personally
of course have 'disk' goals in my makefiles calling AppleCommander ;-)
Best, Oliver
John B. Matthews
wrote:
[...]
> The overlay files are however loaded by the cc65 program using the
> cc65 C library which calls the ProDOS MLI. And with the ProDOS MLI
> it's up to the caller if he looks into the aux type for the load
> address of if he determines the load address in another way.
>
> The latter is the case here: The cc65 program uses the standard POSIX
> calls open(), read(), close() to access the overlay files. And read()
> requires the caller to supply the buffer address. And this buffer
> address is determined by a symbol generated by the cc65 linker into
> the main program. So the main program just "knows by heart" where to
> load the overlays and doesn't need the ProDOS aux type hint - so
> after all the aux type just doesn't matter.
>
> If you think the default 0x2000 is misleading you may want to specify
> 0x0000 in your AppleCommander call but for the sake of simplicity I
> didn't do so in the cfg file comment.
Ah, you're right. I incorrectly attributed a problem I had to faulty
start addresses; it was actually an undefined symbol.
Regarding aux_type, I'm too inured to BASIC.SYSTEM. :-)
> BTW: If you create a file using cc65 via open() then it's a BIN file
> with aux type 0x0000...
This makes perfect sense.
> > I wonder if it would be helpful to use the make syntax in the
> > comments?
>
> Using make seems a quite advanced approach for most cc65 usecases.
> Most projects are so small and cc65 is so fast :-) that some shell
> script simply rebuilding from scratch every time is just fine for
> most cc65 users. Therefore I intentionally didn't want to mix in make
> complexity in this as-simple-as-possible demo - although I personally
> of course have 'disk' goals in my makefiles calling AppleCommander
> ;-)
Your point is well taken. I didn't intend to promote make syntax, per
se; rather, I meant to suggest including the basic cl65 or
cc65/ca65/ld65 command(s) to build the demo. Something like this,
cl65 -t apple2enh -C over-apple2enh.cfg -m overlaydemo.map overlaydemo.c --lib apple2enh.lib
java -jar ac.jar -cc65 prodos.po ${OVER} bin < ${OVER}
java -jar ac.jar -p prodos.po ${OVER}.1 bin < ${OVER}.1
...
or
cc65 -t apple2enh overlaydemo.c
ca65 -t apple2enh overlaydemo.s
ld65 -C over-apple2enh.cfg -m overlaydemo.map overlaydemo.o --lib apple2enh.lib
java -jar ac.jar -cc65 prodos.po ${OVER} bin < ${OVER}
java -jar ac.jar -p prodos.po ${OVER}.1 bin < ${OVER}.1
...
I wouldn't call it essential, but it might save someone a trip through
the sample code's Makefile.
Oliver Schmidt
>Your point is well taken. I didn't intend to promote make syntax, per
>se; rather, I meant to suggest including the basic cl65 or
>cc65/ca65/ld65 command(s) to build the demo. Something like this,
>
>[...]
>
>I wouldn't call it essential, but it might save someone a trip through
>the sample code's Makefile.
Okay, now I got your point - and I totally agree that it would be
preferable to have the build comands together with the disk image
commands.
My original idea was of course to put the necessary AppleCommander
commands into the sample code's Makefile - as there are already some
C64 disk image commands. But then I noticed that the Makefile isn't
that well maintained - i.e. the default goal doesn't work.
And because the overlaydemo was a last-minute-before-release effort
there was just not enough momentum ;-) to fix the Makefile and add the
additional C64 disk image commands for the overlay demo and add the
Apple2 disk image commands in general - so please consider the
comments in the cfg file as a quick hack. There's no hint that they
exist there - where someone less curious than you might not even find
them ;-)
Hopefully the next cc65 release will come with a polished up sample
code Makefile...
Best, Oliver