z88dk is constantly evolving and although we do create release snapshots, it's usually preferable to use a nightly build. Documentation within this wiki is based on the state of nightly. .

NOTE: Some users have reported problems with usage because they have other unrelated programs installed named "zcc" or "z80asm" earlier in their paths. If you are having build or compile trouble, try putting z88dk/bin at the front of your path to see if the problems go away.

To build z88dk from sources, the following tools are needed. The indicated version is a minimum requirement, e.g. gcc version 9 can be used instead of version 8:

The build environment and test tools use Perl and the following modules:

To be able to install Perl modules without sudo, the following line has to be added to your .bashrc or similar shell startup script, and must be run before the next step:

eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"

The following additional Perl modules have to be installed via CPAN:

cpanm App::Prove File::Path CPU::Z80::Assembler Object::Tiny::RW List::Uniq

The tools required for the CI environment are listed in https://github.com/z88dk/z88dk/blob/master/.github/workflows/build-on-ubuntu.yml

See Docker Usage for details - due to changes at dockerhub nightly builds are not available.

A snap file is available for certain Linux distributions. For more details see Snap usage.

Download the latest nightly windows build and unzip it into the destination directory (we suggest to avoid spaces in the directory names). This will create a tree rooted in a z88dk subdirectory.

Some environment variables will have to be defined. On Windows 8, this can be done from the Control Panel by selecting "User Accounts". On the left side of the pop-up box you should find a link to "Change my environment variables". Click that and add the following:

Finally, add ";{z88dk}\bin" to Path for 64 bit windows, or ";{z88dk}\bin.x86" for 32 bit windows.

In the above "{z88dk}" is the full path to the z88dk directory created.

To update the install simply delete the old one, download a new nightly build and unzip in the same location.

Any command prompt that is opened will be ready to compile using z88dk.

The Windows Subsystem for Linux (WSL) allows Linux / Unix distributions to use the Windows host computer. This instruction is based on Ubuntu 22.04 LTS, but other distributions will be similar.

There is a longstanding bug in connecting USB to Serial interfaces to the WSL2 system, so it is best to use the WSL1 as a platform for development.

Install WSL1 following the standard Microsoft instructions.

Install Ubuntu 22.04.x LTS from the Microsoft store.

Using the Windows command prompt, confirm that you are using WSL1 and that Ubuntu-22.04 is installed.

> wsl -l -v

Then set the default distribution to Ubuntu-22.04.

> wsl -s Ubuntu-22.04

Open the Ubuntu 22.04 installation, and configure your installation according to your requirements.

Then follow the instructions for Linux / Unix below.

Download the latest nightly checked source package and unzip it:

wget http://nightly.z88dk.org/z88dk-latest.tgz
tar -xzf z88dk-latest.tgz

This will create a populated z88dk directory in the current working directory. Alternatively you could clone the GitHub repository (including submodules) using:

git clone  --recursive  https://github.com/z88dk/z88dk.git

You will need the following libraries/packages installed to successfully build z88dk:

sudo apt install build-essential bison flex libxml2-dev subversion zlib1g-dev m4 ragel re2c dos2unix texinfo texi2html gdb curl perl cpanminus ccache libboost-all-dev libmodern-perl-perl libyaml-perl liblocal-lib-perl libcapture-tiny-perl libpath-tiny-perl libtext-table-perl libdata-hexdump-perl libregexp-common-perl libclone-perl libfile-slurp-perl pkg-config libgmp3-dev

You will also need the following Perl modules:

cpanm --local-lib=~/perl5 App::Prove CPU::Z80::Assembler Data::Dump Data::HexDump File::Path List::Uniq Modern::Perl Object::Tiny::RW Regexp::Common Test::Harness Text::Diff Text::Table YAML::Tiny
eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)

Then enter:

cd z88dk
export BUILD_SDCC=1
export BUILD_SDCC_HTTP=1
chmod 777 build.sh
./build.sh

This will build z88dk include zsdcc. If you don't want to build zsdcc then omit the export BUILD_SDCC=1 line. The source code for sdcc is downloaded from svn which can be slow, if it keeps failing then run the command: export BUILD_SDCC_HTTP=1 before prior to running ./build.sh - this will download a source code tarball from the z88dk nightly website.

You can run z88dk keeping it in the current location, all you need to do is to set the following environment variable:

Where {z88dk} is the path to the z88dk directory.

Supposing you have bash (most likely it is your system default shell) and you want to keep z88dk in your local user environment (AKA 'home directory'), you can configure it permanently in this way: vi ~/.bash_profile

Modify the configuration as follows:

export PATH=${PATH}:${HOME}/z88dk/bin
export ZCCCFG=${HOME}/z88dk/lib/config
eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)

A system install is not fully supported at the moment, however if you wish to install z88dk and merge it with your default system environment, then export PREFIX=/path/ before building. When building is complete type: make install or alternatively on systems where /bin/sh is actually dash (eg Ubuntu) make SHELL=/bin/bash install.

The build detailed above skips running many of the tests, to run them add the -t option to the build.sh invocation. In order to run the z80asm unit tests the following perl packages are required:

App::Prove Modern::Perl Capture::Tiny Path::Tiny File::Path Template Template::Plugin::YAML CPU::Z80::Assembler Data::HexDump Object::Tiny::RW Regexp::Common List::Uniq

More details can found in .travis.yml which defines the required packages for the Travis CI build.

The MacOS build contains prebuilt binaries to simplify installation. Download the latest package and unzip to a directory:

curl -O http://nightly.z88dk.org/z88dk-osx-latest.zip
unzip z88dk-osx-latest.zip

You can run z88dk keeping it in the current position, all you need to do is to set the following environment variable:

Supposing you have bash (most probably it is your system default shell) and you want to keep z88dk in your local user environment (AKA 'home directory'), you can configure it permanently in this way: vi ~/.bash_profile

Modify the configuration as follows:

export PATH=${PATH}:${HOME}/z88dk/bin
export ZCCCFG=${HOME}/z88dk/lib/config

To update the install simply delete the old one, download a new nightly build and unzip in the same location.

It's recommended that Homebrew is used to install pre-requisites:

brew install gmp libxml2 pkg-config

On Apple silicon, the packages installed by Homebrew aren't automatically placed into the compilation path. The easiest solution is to add the following into your .zprofile following the call to brew shellenv.

export CPATH="$HOMEBREW_PREFIX/include:$CPATH"
export LIBRARY_PATH="$HOMEBREW_PREFIX/lib:$LIBRARY_PATH"

To test if the install was successful, create the following program in a text editor and save as "test.c"

#include <stdio.h>

int main()
{
   printf("Hello World !\n");
       return 0;
}

Open a terminal or command prompt, change to the directory where the test program was saved and compile the program with:

zcc +zx -vn test.c -o test.bin -lndos

There should be no errors.

(recent and not quite ready)

LLVM + SDCC Toolchain \ Clang 3.8 Manual \ LLVM 3.8 Documentation

In order to compile using clang, you must also have sdcc installed.

Clang is a C front end that translates C to LLVM intermediate form and LLVM functions as the back end performing various optimizations on the way to generating the output. Clang+LLVM are well known projects in the open source community, probably made most famous by Apple which uses it as its C compiler.

LLVM as-is is not well suited for targeting small microprocessors. It would take a considerable amount of work to persuade it to generate as good code as the currently available non-LLVM z80 compilers. However, there is a fruitful shortcut that can be taken to exploit some of LLVM's strengths and that is using Clang to compile C to LLVM intermediate form and then using LLVM to perform optimizations and output as C. Then that C can be compiled by an existing z80 C compiler to a binary. In this case, sdcc will be used as the z80 C compiler because it best supports the modern C code that LLVM will be producing.

This process is not as wasteful as it sounds -- there is some indication that a Clang/LLVM/SDCC sequence might produce better code. However, the real prize is that the LLVM toolchain can be used to compile other languages to C and this is an avenue z88dk would like to explore in the future.

** 1. Windows **

** 2. Mac OSX **

** 3. Linux / Unix **

(installation instructions coming; linux/unix users can perhaps follow the instructions in the toolchain link above but rename the binaries to zclang and zllvm-cbe; compiles use the new c library with sdcc command line switches and "-clib=clang_iy" or "-clib=clang_ix")

zcc +z80 -vn -SO3 -clib=clang_iy --max-allocs-per-node200000 test.c -o test -create-app