xa65/xa

This is the readme for xa, a cross-assembler for the 6502 and 65816 CPUs (and
derivatives). xa is a small, fast, portable two-pass assembler that compiles
under most ANSI C compilers. It is distributed under the GNU Public License
(see COPYING).

The current version is 2.4.1, a bug fix for 2.4.0, the first major release in
years. It builds upon the improvements in 2.3.x and its unified 6502/65816
assembler core by adding listing capability, greater flexibility with
relocatable objects, and better cross-compatibility with other popular
cross-assemblers (notably ca65) because once you use xa, you'll want to keep
on using it. :)

Certain long-deprecated options and non-standard syntaxes have also been
removed in this release, so it is possible some very old code may not
assemble without errors. These changes have been a long time coming and we
gave lots of warnings, so if you require these features and cannot change
your code to work without them, you must use xa 2.3.14. Fortunately, most
code should continue to work just fine and the test suite is even bigger to
catch these sorts of regressions.

To install on a generic Unixy thing, you should be able to just type

	% make # to build the executable, and if it works ...
	% make test # if you have Perl, make and prerequisites, otherwise
	% make install # to install man pages and binaries into the system

This will create xa along with its various support utilities. Try assembling
the cpk depacker in examples/ as a test. xa also comes with uncpk (a program
for generating cpk archives) and printcbm (a program for listing Commodore
BASIC test, now deprecated as of 2.4) and file65, ldo65 and reloc65 for
displaying, linking and relocating o65 files in Andre's relocatable format.

Don't forget the man pages in man/. Install these into your MANPATH at your
leisure, or read them with nroff -man (and/or groff -man).

xa is no longer broadly supported outside of Unix due to my inability to test
it, but has nothing that should impair it from compiling elsewhere. To wit,
DOS compilation is still supported with the GO32 package. You should just be
able to type

	C:\> make dos

In addition, there are compatibility updates to allow it to compile under
Microsoft Visual Studio and mingw. It should compile under VS2005 as written;
look in the vstudio directory for solution and project files provided by
Fabian Nunez. For mingw, use

	make mingw

(but do it from within MSYS2).

Similarly, Amiga and Atari ST compilation should still also function with
their particular compatible packages.

xa has a companion disassembler, the dxa package. dxa is not included in the
standard xa distribution, but can be downloaded from the xa home page at

	http://www.floodgap.com/retrotech/xa/

Please check by periodically for the latest version of both packages.

xa was originally written and maintained by Andre Fachat. The current version
is maintained by Cameron Kaiser.

Please send me your comments at ckaiser@floodgap.com -- Andre's original
readme follows and applies generally to the present version.

-------------------------------------------------------------------------------

XA is a 6502 cross compiler:

 - under GNU public license

 - can produce _relocatable_ binaries

 - The full fileformat description and 6502 file loader included.

 - also included relocation and info utilites, as well as linker

 - for any ANSI-C compliant computer (only utilities need 'stat' call 
   for file size). 

 - fast by hashtables

 - Rockwell CMOS opcodes

 - running under DOS and any ANSI C system (Unix, Amiga, Atari ST)

I developed this cross assembler for the 6502 CPU family quite some time
ago on my Atari ST. The assembler has successfully been ported to Amiga 
and Unix computer (ported? just compiled... :-) 
Lately I came across the problem to need relocatable 6502 binary files, so
I revised the assembler from version 2.0.7 to 2.1.0, adding a (admittedly
proprietary) 6502 relocatable binary format. But there are not many other
formats around and they didn't fit my needs. I have developed this format 
myself and it is under the GNU public license.
With version 2.1.1 the 'official' version of the fileformat is supported.

To compile it, just type "make" (if you have the GNU gcc. If not, edit the 
Makefile for the compiler options). This produces "xa", the cross assembler;
"uncpk", a small packing utility (where the C64 counterpart is in the
examples subdirectory), "printcbm", that lists C64 BASIC files and
'file65' that prints some information about o65 files.  The "loader" in
the loader subdirectory is a basic 6502 implementation of a relocating
binary loader.
"file65" prints file information on 'o65' relocatable files. "reloc65"
can relocate 'o65' files.

If you want to use it under DOS, you have to have the GO32 DOS crosscompiling
tools to compile. Then just type "make dos" and you'll end up with the
appropriate DOS binaries. This has been tested only under i386 Linux, however. 
Another archive with the DOS binaries included is provided.

One problem on the Atari was it's broken "malloc". Therefore I used to
alloc everything in one chunk and divide the memory by hand. So everything
was kind of statically allocated. This is almost gone now. Only the
temporary storage between pass1 and pass2 and the preprocessor are still
allocated in one chunk (size definitions in xah.h). The rest is allocated
as needed.

The docs are in the 'doc' subdir. There also is a description of the
6502 relocatable binary format. If you think some things could be 
expressed in a better way, feel free and mail me to improve my english ;-)
[ The documentation is now maintained in man(1) format in man/ . -- CK ]

Andre