ZXB is the main SDK executable. It can act both as a compiler or as a translator:
- When used as a compiler (this is the default behavior) it will convert a .BAS ASCII file to a binary .BIN or .TZX file you can later run on your Spectrum or in a ZX Spectrum emulator.
- If invoked as a translator it will convert a .BAS file to assembler (.ASM source file). You can alter edit this assembler ASCII file (for example to perform some low-level modifications or just to see how the compiler does it work!).
Note: This section does not explain the BASIC syntax language.
For documentation on the language, go to the ZX BASIC reference page.
ZXB is invoked from the command line as zxb.py if you used the Multiplatform (.zip) distribution or zxb if you installed the .MSI package.
Using ZXB is quite straightforward. You will need to type in a BASIC source in a text file. If you don't have any, create a file named helloworld.bas using your favorite text editor, and type in the following:
10 PRINT "HELLO WORLD"
Save this text file as helloworld.bas. Now let's compile it:
If everything went ok, no message should appear on the screen. Now, if you examine your directory, you will see a helloworld.bin binary file. This file contains the bytes of your program.
Another supported output formats are .TAP and .TZX. These formats are supported by many emulators, and can also be converted into sound (WAV, MP3, VOC) to be later loaded on a real ZX Spectrum. TZX and TAP files can also contain a BASIC loader which will load the binary code and execute it. Let's use all of this together:
zxb.py helloworld.bas --tzx --BASIC --autorun
This will create a .tzx file. Open it with your preferred emulator, and type LOAD "". You will see a BASIC loader program executing and loading your code. The machine code is finally executed using RANDOMIZE USR 32768.
Note: 32768 (8000h) is the default ORG for your program.
You can change the default origin using the -S command line parameter.
Command Line Options
ZXB provides several (and useful) command line options. To see them, just type zxb.py -h, which outputs:
Usage: zxb.py <input file> [options] Options: --version show program's version number and exit -h, --help show this help message and exit -d, --debug Enable verbosity/debugging output -O OPTIMIZATION_LEVEL, --optimize=OPTIMIZATION_LEVEL Sets optimization level. 0 = None -o OUTPUT_FILE, --output=OUTPUT_FILE Sets output file. Default is input filename with .bin extension -T, --tzx Sets output format to tzx (default is .bin) -t, --tap Sets output format to tap (default is .bin) -B, --BASIC Creates a BASIC loader which load the rest of the CODE. Requires -T ot -t -a, --autorun Sets the program to be run once loaded -A, --asm Sets output format to asm -S ORG, --org=ORG Start of machine code. By default 32768 -e ERROR_FILE, --stderr=ERROR_FILE Sets error messages output file. Default is standard error output (stderr) --array-base=ARRAY_BASE Default lower index for arrays (0 by default) -Z, --sinclair Enable by default some more original ZX Spectrum Sinclair BASIC features: ATTR, SCREEN$, POINT
Some options (-h, --version) are quite obvious. Let's focus on the rest:
- -d or -debug
- This will show lots of (useless) debug information for the compiler developer (e.g. to me). Usually, you won't need this at all.
- -O or --optimize
- The default optimization level is 1, anyway. Setting this to a value greater than 1 will trigger the optimized module (which is not currently implemented). In the near future, setting this to 0 will be useful for debugging purposes (both for the compiler or the BASIC program).
- -o or --output
- Sets the output file name. By default it will be the same as the input file, but with the extension changed as appropiated (.BIN, .TAP, .ASM, .TZX).
- -T or --tzx
- Outputs the binary result in TZX Format. This format can be converted to sound (.WAV or .MP3).
- -t or --tap
- -B or --BASIC
- This is a very useful option. It will prepend a ZX spectrum BASIC loader that will load the rest of your binary compiled program. This option requires the --tap or --tzx to be specified. This way you can type LOAD "" to load your program.
- -a or --autorun
- Makes your program to run automatically. If specified with the -B or --basic option, your program will autorun if loaded with LOAD "". If --basic is no used this option is ignored.
- -A or --asm
- This will create the .asm (assembler) file. Useful to see / edit the assembler code. You could later assemble it using ZXbasm included assembler.
- -S or --org
- This will change the default machine code ORiGin. By default your code will start at memory position 32768 (8000h). But you can change this with this parameter.
- -e or --stderr
- This specifies an output file name for error msgs. This is useful if you want to capture compilation error messages (for example, to call ZX BASIC compiler from within an IDE).
This is all you know to use the compiler. Proceed to the ZX BASIC page for a language reference.