Introduction to Z88DK – Part 1: Installation & Compilation

This article was originally published on www.speccy.org/wiki, in Spanish, and is reproduced with permission from Santiago Romero. Translation to English courtesy Google and some re-write from my end. Please do let me know of any errors in the text.

In this series of articles we’ll take a look at Z88DK and learn to make programs with it for our Spectrum.

Basically it is a C cross compiler, which allows us to make our programs in this language on our desktop computer (PC running Windows or Linux, SPARC) and create a file that can be run in an emulator. Using the right tools it can be moved to tape to run on our Spectrum. While these articles will focus on the target machine of this publication (the Sinclair ZX Spectrum), the z88dk allows develop applications for a wide range of platforms including Sam Coupe, MSX1, Jupiter ACE, ZX81, and a large number of computers based on the Z80 processor.

The package includes a set of libraries that allow us to easily add functionality to the programs, including a versatile graphics library, which will enable us to even write a game. The C compiler included with z88dk is only a small compiler accepts many features of ANSI C and perform basic optimizations. Finally, we clarify that the purpose of these articles is not to explain the syntax or the operation of the C language and, the reader is assumed to have a basic knowledge about it.

In this issue we focus on how to install the package for different platforms, as well as learn how to compile and run the examples.

Installation

To download the latest stable version we will go to the download page of z88dk, where we can get the Linux version. Binaries for Windows can be obtained from Dennis Grönign’s page (the link can also be found on the same page z88dk).

Installing on Linux

The first step after downloading the file z88dk-src-xytar.gz (where xy is the version of the package at the time of writing – the latest stable version was 1.5), is unpacking in the directory where you want to have it installed:

tar-xvzf z88dk-src-xytar.gz

Once this is done we must compile the various binaries and libraries that make z88dk:

cd z88dk
. / build.sh

To use z88dk we should declare a number of environment variables. We can do this by creating a file setpath.sh (which we will execute permissions with chmod a + x setpath.sh) with the following contents:

where (z88dk) is the directory where you have unpacked the tar.gz. Every time we use z88dk, must execute this file by using the following command:

setpath.sh source

With this we define the environment variables for the current shell.

One tool that we use in creating our programs is bin2tap. This program transforms the binary produced by the compiler to TAP files that can be run in an emulator. Fortunately, this program comes bundled with z88dk. Unfortunately, this is included without compiling, and also not compiled to run the. / Build.sh previously indicated.

To build it, we move to the $ Z88DK/support/zx /, and execute:

cc-o bin2tap bin2tap.c

That way we will create the executable program. To use it comfortably, we copy the bin directory:

mv $ Z88DK/support/zx/bin2tap $ Z88DK/bin /

Compiling and Running on Linux

Once the package is installed, and prepared our system, we explain how we can compile our programs and run them on any emulator. We shall do this in the examples located in the $ Z88DK/examples/spectrum.

In the above directory are a number of files containing C programs that use z88dk librarie. In the README file have a description for each one of them. Let’s compile and test the gfx.c, which incorporates a series of graphic effects that look spectacular. To do so, according to the README file, we can run:

CCZ + zx-or gfx.bin gfx.c-lndos

Below is a brief description of the syntax:
• Just after the ZCC command specify the target machine, ie the machine which will produce the binary. In our case we want to create a binary for the ZX Spectrum, so we use the modifier + zx (the switches for each of the machines supported can be found at $ Z88DK/doc/compile.txt).

• Finally, we con-lndos to bind to the bookstore NDOS (in next installments we go into detail about the most useful libraries and functionalities offered). The libraries are in $ Z88DK/libsrc /.

As you can see, the syntax is very similar to Linux gcc compiler, so if we are used to programming in C on this platform, we should not have any problem. The resulting file, gfx.bin, is a binary file (which a text editor can’t understand). Keep in mind that CCZ is not the compiler itself, but it is a frontend that is responsible for implementing the compiler and assembler / linker (all these applications can be found in the $ Z88DK/bin /).

This binary may not yet be executed in any emulator, we must first convert it to a suitable format. To do this we can use the application bin2tap, we compiled in the previous paragraph:

bin2tap gfx.bin gfx.tap

And now we can test the program in our favorite emulator!

Installation on Windows (thanks to the collaboration of Miguel)

This installation has been completed and tested on a PC with Windows 98 Second Edition. Attempt on a Windows XP system files and executables in the bin directory gave the error “xxxxxxx.exe is not a valid win32 file” (This may be due more to the PC on which the author has installed the operating system incompatibility problems between himself and z88dk Windows XP).
The first step we must carry out is to download the file z88dk-win32-xyzip (where xy indicates the version of z88dk) we can find on the project website. Once downloaded, unzip the zip file in the directory c: z88dk, which will be the default directory that we use in this article. We can switch to one that suits us more by changing the path in all explanations given below.

The following adds the path of the executables and libraries to the autoexec.bat file. For this we have two options:

• 1. Add the path manually by editing the autoexec.bat file. To do this simply edit the autoexec.bat file located in c: / with the Windows Notepad, or from a MS-DOS “edit autoexec.bat” and add the following lines:

• 2. When you uncompress the zip files containing z88dk, there is a file called SETZ88-W95.inf, we place the mouse pointer over it, right-click and select install, which automatically adds the file path autoexec.bat.
After one of the above, reboot the PC to update the paths. Compile and run on Windows

When writing code with the z88dk, the code is written in C language in plain text files with your preferred editor (can be even Windows Notepad). These files are usually saved with a .c extension.
To show briefly how we create a file to run on a ZX Spectrum emulator, or upload to a real computer, we’ll use one of the examples that come with z88dk.

• The first thing we do is open a MS-DOS command window and move to the folder where the examples are present:
To put ourselves in the root directory of C:

CD c:
CD z88dk examples spectrum

With that we are in the examples folder.
Now we have to compile the program. To do this we will use the executable ZCC.EXE, which is located in the BIN folder, but we do not have to enter it at all, because we added its path earlier. Compile by typing:

CCZ + zx-or gfx.bin gfx.c-lndos

When you run it, it creates a file.bin in which we will have our program. We need to convert it to a format that the emulator can understand, or move to tape and load on a real ZX Spectrum.

• To convert the file from .bin to .tap, we have a program called BIN2TAP.EXE that is included in z88dk and located in the support zx folder.

Usage is very simple: we have to be in the same folder as the. BIN2TAP.exe and provide it the .bin source and specify the target .tap. Execute: