Difference between revisions of "ZX BASIC:Zxb"

From BorielWiki
Jump to: navigation, search
(Command Line Options)
(Command Line Options)
Line 59: Line 59:
 
* '''-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.
 
* '''-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''' currently ignored. The default optimization level is 1, anyway. In the near future, setting this to 0 will be useful for debugging purposes (both for the compiler or the BASIC program). Also, when implemented, setting this to a value greater than 1 will trigger the optimized module (which is not currently implemented).
+
* '''-O''' or '''--optimize''' currently ignored. The default optimization level is 1, anyway. In the near future, setting this to 0 will be useful for debugging purposes (both for the compiler or the BASIC program). Also, when implemented, setting this to a value greater than 1 will trigger the optimized module (which is not currently implemented).
  
*s
+
* '''-o''' or '''--outpuy''' 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 [http://www.worldofspectrum.org/TZXformat.html TZX Format]. This format can be converted to sound (.WAV or .MP3).
 +
 
 +
* '''-t''' or '''--tap''' outputs the binary result in [http://www.worldofspectrum.org/faq/reference/formats.htm TAP Format] (also read [http://www.jupiter-ace.co.uk/faq_ace_tap_format.html here]).

Revision as of 16:07, 8 June 2008

Introduction

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.
  • Is invoked as a translator it will convert a .BAS file into an assembler (.ASM) source. You can edit this assembler file by hand 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.

Using ZXB

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:

zxb.py helloworld.bas

If everything went ok, no message should appear on the screen (Some warnings about compiler internal tokens might be shown, but you can safely ignore them). 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 format is .TZX. This format is supported by many emulators, and can also be converted into sound (WAV, MP3, VOC) to be later loaded on a real ZX Spectrum. The TZX file can also contain a BASIC loader which will load the binary code and execute it. Lets 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 code is 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

The .TAP file format is not currently supported (but it's being worked on. Please be patient). 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 currently ignored. The default optimization level is 1, anyway. In the near future, setting this to 0 will be useful for debugging purposes (both for the compiler or the BASIC program). Also, when implemented, setting this to a value greater than 1 will trigger the optimized module (which is not currently implemented).
  • -o or --outpuy 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 outputs the binary result in TAP Format (also read here).