[1][Hosted by Floodgap Systems]

                                        xa (xa65)

   xa is Andre Fachat's open-source 6502 cross assembler. I, Cameron Kaiser
   ([2]ckaiser@floodgap.com), am the current maintainer, and bug reports and
   questions should now go to me.

   xa is Copyright © 1989-2024, André Fachat, Jolse Maginnis, David Weinehall and
   Cameron Kaiser. All rights reserved. Additional contributors: Fabien Nuñez,
   Mikkel Holm Olsen, Adam Sampson, Alessandro Gatti, Simon Rowe, Dan Horák,
   Frederic Cambus, Sam Falvo, Stephen Kitt, Bas Wassink, Sergei Trofimovich, Tom
   Hargreaves. xa is distributed under the [3]GNU Public License v2. The current
   maintainer is Cameron Kaiser.
     ____________________________________________________________________________

     For a complete list of available files and distributions, check the [4]dists/
                                      directory.

     For other Floodgap-maintained packages, see the [5]Floodgap Software listing.
     ____________________________________________________________________________

What is xa?

   xa is a high-speed, two-pass portable cross-assembler. It understands mnemonics
   and generates code for NMOS 6502s (such as 6502A, 6504, 6507, 6510, 7501, 8500,
   8501, 8502 ...), CMOS 6502s (65C02 and Rockwell R65C02) and the 65816.

   Key amongst its features:

     * C-like preprocessor (and understands cpp for additional feature support)
     * rich expression syntax and pseudo-op vocabulary
     * multiple character sets
     * binary linking
     * supports o65 relocatable objects with a full linker and relocation suite, as
       well as "bare" plain binary object files
     * block structure for label scoping

   xa's eventual companion disassembler is [6]dxa, a moderately hacked-up version of
   Marko Mäkelä's d65 disassembler. This is still alpha and is available as a
   separate distribution until it is stabilized enough to be part of the xa suite.

Version 2.4.1 (5 March 2024)

   2.4.1 is a bug fix and small feature update for 2.4.0. 2.4.0 is a significant
   update of the code base with many new features. However, because this is more
   than just a point release, there are potentially incompatibilities with edge
   cases in 2.3 and earlier versions, and features that were declared deprecated in
   2.3 have been removed.

     * [7]xa-2.4.1.tar.gz

   xa should compile out of the box on just about any Unix or Unixy thing, and will
   probably compile on other systems that support ANSI C as well. Please see the
   README.1st file for more detailed instructions. It is tested and validated on AIX
   (gcc), Linux/ppc64le (gcc and clang), Mac OS X (gcc on PowerPC, and clang on
   Intel x86_64 and Apple silicon) and NetBSD/macppc and NetBSD/mac68k (gcc).

  What's new in 2.4.1

     * Allow colon-based unnamed labels to be used separately of CA65 mode (such as
       with 65816) with -a. Implies -XMASM.
     * Restore ^ syntax for generating control sequences (e.g., "^m^j" evaluates as
       0d 0a) with -k.
     * Fix a bug using cheap local labels in expressions.
     * Properly tag and match CPU types in o65 objects during relocation and
       linking.
     * Fix a bug with .align when aligning segments.
     * Better validation of arguments to indexed opcodes.
     * Testsuite expanded.

  What's new in 2.4.0

   In case you missed it. Too much to completely enumerate, but here's the hits.
     * Listing feature (-P, -F) in plain text or HTML, along with .listbytes to
       control how hex bytes get listed in the output.
     * Add -E commandline option to not stop after 20 errors, but show all of them.
     * Introduce -X compatibility set command line option to distinguish between
       MASM and CA65 compatibility options; also adds C option for 0x and 0 to
       specify hex or octal. As a result, -M is now deprecated, and colons in
       comments may become the default in a future version.
     * Implement CA65 "cheap local labels", ":=" label definitions, and various
       pseudo-opcodes (.include, .import, .importzp, .zeropage, .proc (anonymous
       only), .endproc, .code, .org, .reloc).
     * -U option to allow all undefined labels in relocating mode; this allows
       exporting them to an .o65 file and link at a later time (or specify one at a
       time with -L).
     * Globals may also be specified manually with -g.
     * #error allows preprocessor-level assertions.
     * .assert allows assembler-level assertions.
     * Better fix for segfault with smaller arity macro issue.
     * Main Makefile fixes.
     * Fixed parallel make in tests, incorporating a patch from Sergei Trofimovich.
     * Added a test case that failed in 2.3.14 from Tom Hargreaves.
     * Some 2.3.x features still allowed with -XXA23, which is obviously deprecated.
     * The quote escape character is now the \ (backslash), except if -XXA23.
     * Recursive /* */ comments are no longer allowed, except if -XXA23.
     * XA_MAJOR and XA_MINOR predefined macros, except if -XXA23.
     * Testsuite greatly expanded.
     * The old loader/ testsuite and doc/ archive are now in attic/, which is the
       repository for old unsupported components. It may be purged in a future
       version.
     * -M is now deprecated (use -XMASM), just in case you forgot.
     * printcbm(1) is now deprecated (use VICE petcat, it does a lot more).
     * Previously deprecated options (16-bit mvn/mvp argument, -S, -x) finally
       removed. If you need this support, you must use 2.3.x.

  Documentation

   Documentation is now in man format since 2.3.0. You can read them here, converted
   with man2html:

     * [8]xa(1)
     * [9]file65(1)
     * [10]ldo65(1)
     * [11]printcbm(1)
     * [12]reloc65(1)
     * [13]uncpk(1)

   For those using older distributions, refer to the previous [14]xa HTML
   documentation.

  History

   I'll just let Andre tell it:

     "I developed the first version of xa on my old Atari ST to build programms for
     my selfbuilt computer CS/A65. After my Atari broke I ported it to Linux
     (ported? It compiled right out of the box!) and when I had to develop a
     programm for a friend of mine, I compiled it on an Amiga without errors. Until
     the beginning of 1992 I made more improvements, until it came to version
     2.0.7. Since then I only very occasionally worked on it, up to version 2.0.7d.
     When I decided to push my selfbuilt OS to a new level in 1996, I needed more
     important improvements, like o65 object format and a linker and all that".
     ____________________________________________________________________________

dxa

   Starting with 2.3.0, xa is now officially accompanied by dxa, its companion
   disassembler. dxa is a rudely hacked version of Marko Mäkelä's d65 package, with
   some extra features and altered output to allow "perfect" disassembly (which is
   to say, you can take an arbitrary object, run it through dxa, take what it spits
   out, run it back through xa, and get the binary you started with). It also has
   features for intelligently labeling code and data sections and multiple output
   formats, and can understand undocumented and CMOS opcodes (65816 not yet).

   Because dxa is new and not well tested, I have not included it as part of the
   standard xa distribution and it is offered here separately. Please consider it to
   be alpha software only and expect bugs. Refer to the readme for instructions on
   installation. dxa, like d65, is distributed under GPL v2.

  Version 0.1.5 (25 March 2022)

   New in this version is a formal, if small, test suite for the very first time
   (make test). This disassembles a set of binary test vectors, reassembles them
   (with xa, natch), and checks that the output matches the original binaries. You
   need xa installed. If make test fails, make sure your xa is current before
   reporting a bug. dxa is now validated on all the platforms xa is.

   There are also many fixes in this version, including properly getting the very
   last byte for files that load all the way to $ffff and correctly (IMNSHO)
   truncating files that load beyond (thanks Malte), fixes for bugs with clang-built
   dxa generating incorrect code, fixes for an issue with the C preprocessor, and
   more flexible BASIC header detection. Note that clang-built dxa does behave
   differently than gcc-built dxa and more research is needed (currently the only
   guarantee is that both will generate an assembly file which will assemble to
   identical binaries). dxa is based on d65 0.2.1.

     * [15]dxa-0.1.5.tar.gz

   Documentation is offered in man format; here is the man2html version.

     * [16]dxa(1)
     ____________________________________________________________________________

   [17][Top of page] Send all bugs in xa or dxa to [18]ckaiser@floodgap.com.
     ____________________________________________________________________________


    Cameron Kaiser

References

   1. http://www.floodgap.com/
   2. mailto:ckaiser@floodgap.com
   3. http://www.floodgap.com/retrotech/xa/COPYING.txt
   4. http://www.floodgap.com/retrotech/xa/dists/
   5. http://www.floodgap.com/software/
   6. http://www.floodgap.com/retrotech/xa/#dxa
   7. http://www.floodgap.com/retrotech/xa/dists/xa-2.4.1.tar.gz
   8. http://www.floodgap.com/retrotech/xa/xa.1.html
   9. http://www.floodgap.com/retrotech/xa/file65.1.html
  10. http://www.floodgap.com/retrotech/xa/ldo65.1.html
  11. http://www.floodgap.com/retrotech/xa/printcbm.1.html
  12. http://www.floodgap.com/retrotech/xa/reloc65.1.html
  13. http://www.floodgap.com/retrotech/xa/uncpk.1.html
  14. http://www.floodgap.com/retrotech/xa/xa-old.html
  15. http://www.floodgap.com/retrotech/xa/dists/dxa-0.1.5.tar.gz
  16. http://www.floodgap.com/retrotech/xa/dxa.1.html
  17. http://www.floodgap.com/retrotech/xa/#top
  18. mailto:ckaiser@floodgap.com