BEFORE USING, YOU MUST READ AND AGREE TO THE DOCUMENT LICENCE.TXT IN ITS ENTIRETY OR REMOVE ALL OF THIS FROM YOUR COMPUTER NOW. IT WOULD ALSO BE A GOOD IDEA FOR YOU TO REVIEW XPNOTES.TXT FOR KNOWN ISSUES WITH WINDOWS XP AND TROUBLESHOOTING THESE ISSUES. ReadMe for C:\Aztec64 March, 2008 Manx Aztec C65 Version 1.06e Target: Commodore 64 6502 Native Code Target OS: Commodore 64 (C64) BASIC 2 operating system Compiler: C II Vers. 1.05h 6502 (C) 1982, 1983 by Manx Software Systems MS-DOS cross-development environment for 8086 and compatible computers Preconfigured for Windows XP With several samples, projects, and a production example With an additional link library for sound and graphics etc. With many original related custom tools for MS-DOS including source code This document is intended for expert developers and novices alike. However if you are unfamiliar with some of my terminology it will not be an easy read. If that is the case, you will likely need to revisit it several times, after doing your own research. Disclaimer and Conditions of Use This compiler is (C) Copyright 1983 Manx Software Systems. I cannot provide you with a legally licenced copy. I herewith grant you a non-exclusive conditional licence to use any and all of my work included with this C64 compiler for whatever use you deem fit, provided you do not take credit for my work, and that you leave my copyright notices intact in all of it. I believe everything I have written to be correct. Regardless, I, Bill Buckels, do not guarantee, or warranty, in whole or in part, any of this, and further do not offer support for any of this. All of this is provided as-is. See licence.txt for further details. BEFORE USING, YOU MUST READ AND AGREE TO THE DOCUMENT LICENCE.TXT IN ITS ENTIRETY OR REMOVE ALL OF THIS FROM YOUR COMPUTER NOW. Bill Buckels bbuckels@mts.net Introduction This is a complete Aztec C build environment for Windows XP (MS-DOS) which will enable you to produce efficient 6502 machine-language programs which will, when properly built, load and run from BASIC on a Commodore 64 or in the Vice C64 emulator, and which will exit cleanly to BASIC when done. The flavour of C that is used is not ANSI compliant, but many of the functions that existed or still exist in ANSI C are available, or have equivalents. I am unable to provide the original documentation for this compiler, but generally speaking, other Aztec C manuals that may be available online for this version (1.0...) might help. Programs are written in C on an IBM-PC compatible computer and can be augmented with inline assembly language or assembly language modules if desired. This compiler's first pass produces 6502 assembly language, which is assembled on the second pass and linked to other assembled code objects and libraries on the final pass to produce finished programs which are then modified using special tools to load and run under C64 BASIC 2. It is quite a complicated environment, but I have highly simplified it for you by pre-configuring it to run under Windows XP, and by using MAKEFILE's, and have provided many original programs and library routines that I wrote in their entirety to get you started. I have organized this environment into topical subdirectories to make it easier for you to review and use my work and to provide you with a sustainable framework for your own C64 research. DO NOT CHANGE ANY OF THIS UNLESS YOU HAVE A COMPLETE UNDERSTANDING OR IT MAY NOT WORK! See above and below. Some of this is as follows: Directory Structure C:\Aztec64\ - startup directory - click-on WindowsXP shortcut to begin. C:\Aztec64\SAMPLES - simple programs and demos - novice level C:\Aztec64\PROJECTS - small applications - intermediate level C:\Aztec64\PRODUCT - complete application with overlays - expert level C:\Aztec64\B64NAT - custom library project - expert level C:\Aztec64\TOOLS - required to build all my programs provided - many extras C:\Aztec64\INCLUDE - Aztec C headers augmented with my own C:\Aztec64\LIB - Link Libraries including my own with list of functions C:\Aztec64\BIN - Original Aztec C Binaries - Compiler, Assembler, Linker, ... C:\Aztec64\OBJ - Overlay Objects Required for Linking Overlays, etc... C:\Aztec64\SRC - Original Aztec C Library Source for All of this C:\Aztec64\DOC - C64 Reference Documents that I thought you might need. Review the contents of each directory and their subdirectories for more information. Always save a copy of your original directory if modifying or building anything. Library Routines Overview I have added a large library of many routines that are needed (in my opinion) to program anything beyond console applications. The Aztec C libraries provided by Manx did not provide routines for doing text, graphics, nor sound routines at what most of us would consider a "finished" level sufficient to exploit the many native mode features of the C64. The Aztec C libraries form the basis for some of my library functions. Most others however are the result of my 30 years or so experience which was and is mainly as a career programmer with a strong bias in developing input, text, graphics, and sound routines from both the bottom-up and the top-down. Between my original programs and what you get from Aztec C, I don't think you are missing much. Tools Overview The tools that I have provided are "feature-rich" in my opinion. They are variations of tools that I developed over many years beginning in the days when all of this was current, and I tailored them for this environment. They include tools for converting text, graphics, and sound routines from IBM-PC format to C64 format. The various C64 examples that I have provided show how these are used. I have provided the complete source code for these so you can change them to suit your own advanced needs or just read the source code for more information. You can also use them as-is which I would suggest as a starting point.You will need Microsoft's 16 bit legacy compilers (now unsupported) to build most of these tools. Some of the core tools that are called from most MAKEFILE's that I have provided allow you to embed fonts and graphics in your programs, or to generate header information directly from IBM-PC text and graphics screens and sound files which can be included or modified for inclusion. You should note that the MKBASIC program provided with Aztec C along with the compiler, and which is in C:\Aztec64\BIN, is always required to produce the finished program (at least it is the way I have set-up all of this to work). B64NAT Library Project Overview and Details Some background is required here. If I miss some detail, you can review the contents of the C:\Aztec64\B64NAT directory for more information. B64NAT Library Project Background To recap, this is an augmented version of the Manx Aztec C65 Version 1.06e MS-DOS cross-development environment for a Commodore 64 (C64) running BASIC 2 as the Operating System. However, since some of my distribution disks had apparently become damaged over time and I am unable to read them, I am assuming it is only partially complete which is part of the reason that I needed to augment it so it could be used properly. At the time of this writing, I have, since resurrecting this compiler (2007) been unable to read two of the 5 disks that this originally came-on as IBM- PC floppies, and I don't presently have a real C64 set-up to try these as C64 floppies, I don't know if I am missing additional files because one or more of the disks are bad, or if this just came as a C64 native mode cross- compiler for MS-DOS. I believe one or more of the disks are bad, but I consider myself fortunate that I was able to resurrect this to a working build environment which with some additions on my part is completely functional as far as I know with the caveats that I am now stating. The other reason for augmenting this environment is my goal; to provide an Aztec C build environment for C64 native mode programs that is reasonably equal to what I can do in Aztec C on the Apple IIe and on the IBM-PC which is basically everything that needs to be done to develop an application of the flavour of the day... in this case circa 1984. It is targeted specifically at writing C64 native mode programs. It does NOT as far as I know, provide support for the Commodore 128 (C128) running BASIC 7 (although I have not taken time to explore this further, nor do I intend to), and it does NOT, as far as I know, provide support for Aztec C Pcode. Other than that, none of the run-time library functions have been removed that were in what I resurrected of the original distribution. Programs are written and compiled on the IBM-PC and then moved to a C64 or to an emulator disk image to be run. I have provided Makedisk.bat for all my projects which calls c1541 from WinVICE to create a runable d64 emulator disk for each C64 sample program or C64 project provided. You must install WinVICE separately and place the c1541 executable in your tools directory to use the makedisk batch files from within this environment. An additional link library (B64NAT.LIB) is provided which supports, among other things, the use of graphics and bit-mapped graphics images, sound routines, and other useful routines for native mode C64 Aztec C programs. The build environment has been configured to run under Windows XP and a pre- configured shortcut has been provided for this purpose as well as a make utility program and some additional programs to be used in conjunction with make. Several sample programs and C64 projects are provided, each with its own MAKEFILE and each can be reviewed for information on how to write your own C64 programs. I long ago gave away the manuals for my Aztec C compilers in a cross-country move so I have created some documentation to the best of my ability, and much of what I have written is assumptions backed-up by testing this environment during the creation of my sample programs which I wrote from scratch mostly in late 2007 and early 2008. What I have written is accurate to the best of my knowledge and ability and experience, and hopefully you can count-on my documents to be 100% accurate or very close to it. Creating Libraries with libutil - quick notes libutil v1.05g fixups (C) Copyright Bill Buckels 2008. All Rights Reserved. usage: libutil [-artx] [-o libraryname.lib] name1.rel name2.rel ... create: libutil [-o libraryname.lib] name1.rel name2.rel ... -a add one or more object (.rel) modules into an existing library... -r replace one or more object (.rel) modules into an existing library. add and replace are effectively and functionally the same command. -t list all object (.rel) modules in a library. -x extract one or more object (.rel) modules from a library. name1.rel name2.rel etc. (names must be as originally entered) note: this utility has not been extended beyond its original capabilities. it is intended for use with Aztec C v1.0x and is not compatible with later versions that used lb.exe and its library format(s). If you are using the x86 EXE, this was compiled under Aztec C86 v4.10d and is for the Aztec C65 v1.06e MS-DOS C64 cross development environment using the C II v1.05h compiler. The libutil source originated in Aztec C for CP/M80. the output has been changed to default to the .rel object extension and minor fixups were required for x86 OS (MS-DOS XP) and compiler compatibility. You can review the projects and samples and various MAKEFILE's in the Aztec64 environment for more information on how to link to libraries. Compiler Limitations Be sure to read C:\Aztec64\XPNotes.txt for some known problems that you may encounter and for their solutions. This compiler is an earlier version than my Aztec C Apple IIe cross-compiler. The compiler can't handle very many defines. It is very old and written to run in a limited memory environment. It does not as far as I know accept paths for include and lib. Instead my MAKEFILEs copy the headers and libs required to the current build directory and remove them when done. The variables as well as the constants (all symbols) are truncated and you can review the assembly pass of your programs to see what they have been truncated to. I am assuming it is written to be run from a single floppy. Because it is so old, rather than moan and groan about how crappy it is, since I lived through that period of history and understand the deliberate compromises that needed to be made, I consider all of this absolutely excellent especially because it can be used effectively 25 years after it was written. I am still quite current in my programming life in today's world, and develop using the latest tools for current markets. I have the historical perspective to understand what is good and what isn't. Trust me on this, and don't get all hung-up on what is missing and what could have been done differently. This is not evil, not bad and most of it is pretty good. It is what it is. Be Happy and Have Fun! 'Nuff said. Getting Started Unzip the ZIP file(s) with directories intact onto the root of your C: Drive. The Windows XP shortcut has been pre-configured to use this directory structure. Open the C:\Aztec64 folder in MyComputer and click-on the shortcut. A cmd window will open, and you will be in the C:\Aztec64 directory which is the parent directory for this environment. The required environment variables to build Aztec C C64 programs are set for you, and you can build these anywhere on your computer from this cmd window. You must be somewhat familiar with DOS commands to use this build environment. You must CD (Chdir) to each programs build directory. You can test the environment by building the programs in the SAMPLES and PROJECTS subdirectories. Each has its own MAKEFILE which will build a c64 program simply by typing "make" and pressing [ENTER] while in each's project directory under SAMPLES, PROJECTS, or PRODUCT. You can even copy the XP shortcut that I have provided to your working directory and set that as your startup directory to avoid much typing. To recap, in any of the program build directories just type "Make" and press enter to make any of the C64 programs provided as samples. Provided you have used the XP shortcut noted above, you should have no problems. Otherwise use a DOS emulator like DOSBox in which case you will need to set-up your own environment by modifying C:\Aztec64\AZTEC.BAT. What You Will Need You can write your own programs in notepad or your favourite programmer's editor. This environment doesn't provide an editor. You should get a copy of the Aztec C Manual which is available online at http://www.clipshop.ca/Aztec/cat1.htm and http://www.clipshop.ca/Aztec/cat2.htm This will provide you with the original text of the printed manual for a newer version of the C65 compiler and considerably more information about some of the Aztec C library functions than the SAMPLES that are included in this environment. However, if you can find a manual for Aztec C version II (1.0X) then that would be better You will also need an c64 emulator like WinVICE that provides a Disk Manager unless you have a real C64. If you wish to create full-screen bitmapped graphics for the C64 you may wish to download the ClipShop program from the following link: http://www.clipshop.ca Other than that, all you need is the ability to write and compile programs in the C programming language. Review the various ReadMe files and source code in this environment for additional notes. Or better yet, just build the sample programs and experiment. Have Fun! Bill Buckels bbuckels@mts.net March 2008 (C) Copyright Bill Buckels 2008 All Rights Reserved. End of Document