installation

Installation

After install, go to Getting started.

z88dk changes often. Prefer a nightly build or a git build when you need current tools. Prefer those over an old release snapshot.

1. Required environment

You must set both variables. Without them, zcc cannot find targets.

Variable	Value
PATH	Include z88dk/bin (or z88dk/bin.x86 on 32-bit Windows)
ZCCCFG	z88dk/lib/config

Check the install

1. Open a new shell (so it loads the updated environment).
2. Run:

zcc

3. You must see the zcc banner and a note that a target is required.
4. If the command is not found, fix PATH.
5. If the tool runs but cannot open a target config, fix ZCCCFG.

2. Choose an install method

Host	Method	Section
Windows	Nightly zip binary	Binary on Windows
macOS	Nightly zip binary	Binary on macOS
Linux / Unix	Build from source (or nightly tarball)	Build from source
Linux (Snap)	Snap package	Snap · Snap-usage
Any	Docker	Snap · Docker-Usage
VS Code / Codespaces style	Dev container example	Dev container
Releases	GitHub release archives	GitHub releases

Nightly site: http://nightly.z88dk.org/

Git build summary: git clone --recursive https://github.com/z88dk/z88dk.git then ./build.sh (see build.sh -h). Set BUILD_SDCC=1 when you need zsdcc.

---

3. Binary installation on Windows

Steps

1. Download the latest nightly Windows build from http://nightly.z88dk.org/
2. Unzip into a destination directory. Avoid spaces in the path when you can.
3. Note the tree root. This document calls that folder {z88dk}.
4. Set environment variables (Windows 8 example):
   • Open Control Panel → User Accounts.
   • Open Change my environment variables.
   • Add:

Variable	Value
ZCCCFG	{z88dk}\lib\config

5. Add to Path:
   • 64-bit Windows: ;{z88dk}\bin
   • 32-bit Windows: ;{z88dk}\bin.x86
6. Open a new command prompt.
7. Run zcc as in section 1.

Update

1. Delete the old install tree.
2. Download a new nightly build.
3. Unzip into the same location.
4. Keep the same PATH and ZCCCFG values.

Note: virus scanners

Some virus scanners report trojans in the z88dk kit. These are false detections. They seem to trigger on the MinGW/gcc used to build the binaries. All binaries and kits are cross-compiled from Linux and have not run on a Windows machine used for packaging. See issue #2474.

---

4. Binary installation on macOS

Steps

1. Download and unzip the latest package:

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

2. Set ZCCCFG to {z88dk}/lib/config (replace {z88dk} with the full path to the unzipped tree).
3. Add {z88dk}/bin to PATH.
4. You can keep the tree where you unzipped it. You do not need a system-wide install.

Permanent shell config (bash profile)

The default shell for macOS is often zsh. You may use bash and store z88dk under your home directory. Example permanent config:

vi ~/.bash_profile

Example contents:

# Suppress message about using zsh
export BASH_SILENCE_DEPRECATION_WARNING=1

# Export z88dk path and environment
export PATH=${PATH}:${HOME}/z88dk/bin
export ZCCCFG=${HOME}/z88dk/lib/config

Adjust ${HOME}/z88dk if your tree is elsewhere.

Update

1. Delete the old tree.
2. Download a new nightly build.
3. Unzip in the same location.

---

5. Snap and Docker

Snap

A snap package is available for some Linux distributions. Details: Snap usage.

Docker

Details: Docker Usage.

Dev container

Based on the docker image, an example devcontainer project is:

https://github.com/z88dk/z88dk-devcontainer-example

---

6. Building from sources

6.1 Dependencies (package lists)

Build needs the tools below. The listed version is a minimum. Example: gcc 9 is fine when the table says gcc 8.

Ubuntu package	Min version	Description
gcc-8	8	GNU C compiler version 8, supporting C++17 and std::filesystem
libboost-all-dev	1.71	Boost C++ Libraries development files
perl	5.30	Larry Wall's Practical Extraction and Report Language
ragel	6.10	State Machine Compiler, compiles finite state machines into code in various languages
re2c	1.3	tool for generating fast C-based recognizers
ccache	3.7	Compiler cache for fast recompilation of C/C++ code
dos2unix	7.4	convert text file line endings between CRLF and LF
texinfo	6.7	Documentation system for on-line information and printed output
texi2html	1.82	Convert Texinfo files to HTML
curl	7.68	command line tool for transferring data with URL syntax
cpanminus	1.7044	script to get, unpack, build and install modules from CPAN
pkg-config		manage compile and link flags for libraries
libxml2-dev		Development files for the GNOME XML library
libgmp3-dev		Arbitrary precision library

The build environment and test tools use Perl and these modules:

Ubuntu package	CPAN package	Min version	Description
liblocal-lib-perl	local::lib	2.000024	module to use a local path for Perl modules
libyaml-perl	YAML	1.30	YAML Ain't Markup Language
libmodern-perl-perl	Modern::Perl	1.20200211	module for enabling all of the features of Modern Perl
libtemplate-perl	Template	2.27	"Template Toolkit" template processing system in Perl
libtemplate-plugin-yaml-perl	Template::Plugin::YAML	1.23	simple Template Toolkit Plugin Interface to the YAML module
libcapture-tiny-perl	Capture::Tiny	0.48	module to capture STDOUT and STDERR
libpath-tiny-perl	Path::Tiny	0.108	file path utility
libtext-table-perl	Text::Table	1.132	Create tables that adapt to alignment requirements
libdata-hexdump-perl	Data::HexDump	0.02	hexadecimal dumper
libregexp-common-perl	Regexp::Common	2017060201	module with common regular expressions
libclone-perl	Clone	0.43	module for recursively copying Perl datatypes

To install Perl modules without sudo, add this line to .bashrc (or a similar shell startup script). Run it before the next CPAN step:

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

Install these additional Perl modules via CPAN:

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

CI package truth: https://github.com/z88dk/z88dk/blob/master/.github/workflows/build-on-ubuntu.yml

6.2 Linux / Unix build steps

1. Get sources. Either nightly tarball:

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

Or clone GitHub with submodules:

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

2. Install host packages (Ubuntu/Debian style example):

sudo apt install build-essential bison flex libxml2-dev 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

3. Install Perl modules used by the build and tests:

cpanm --local-lib=~/perl5 App::Prove CPU::Z80::Assembler Data::Dump Data::HexDump Test::HexDifferences 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)

4. Build (includes zsdcc when BUILD_SDCC=1):

cd z88dk
export BUILD_SDCC=1
export BUILD_SDCC_HTTP=1
chmod 777 build.sh
export PATH=${PATH}:`pwd`/bin
export ZCCCFG=`pwd`/lib/config
./build.sh

5. To skip zsdcc, omit export BUILD_SDCC=1.
6. SDCC sources may come from svn (can be slow). If that fails, set export BUILD_SDCC_HTTP=1 before ./build.sh so the build downloads a tarball from the nightly site.
7. Keep the tree in place. Set ZCCCFG to {z88dk}/lib/config and put {z88dk}/bin on PATH as in section 1.

Permanent bash config (Linux example)

If you use bash and keep z88dk under your home directory:

vi ~/.bash_profile

Example lines:

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

System-style install (optional)

A full system install is not fully supported. If you still want to merge into a prefix:

1. export PREFIX=/path/ before the build.
2. After the build finishes, run make install.
3. On systems where /bin/sh is dash (for example Ubuntu), use: make SHELL=/bin/bash install.

Tests during build

The default build skips many tests. To run them, add -t to build.sh. For z80asm unit tests, these 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

6.3 Building on macOS (from source)

1. Install prerequisites with Homebrew:

brew install gmp libxml2 pkg-config

2. On Apple silicon, Homebrew packages are not always on the default compile path. After brew shellenv, add to .zprofile:

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

3. Then follow the same clone/build.sh flow as Linux (with PATH and ZCCCFG set to the tree).

6.4 Building with Windows Subsystem for Linux (WSL) — Ubuntu

WSL runs a Linux distribution on the Windows host. These steps use Ubuntu 22.04 LTS. Other distributions are similar.

There is a longstanding bug for USB-to-serial on WSL2. Prefer WSL1 for development that needs serial hardware.

1. Install WSL1 using Microsoft instructions.

2. Install Ubuntu 22.04.x LTS from the Microsoft Store.

3. From a Windows command prompt, confirm WSL1 and Ubuntu-22.04:

wsl -l -v

4. Set the default distribution:

wsl -s Ubuntu-22.04

5. Open Ubuntu 22.04 and finish first-boot setup as you need.

6. Follow Linux / Unix build steps.

---

7. Build errata

To use older z88dk versions, nightly kits or Docker builds are the easiest path. If you build old sources, you may need extra compiler flags. Newer host compilers find more issues and may reject older C by default.

Version 2.2

With recent GNU compilers, z88dk v2.2 may fail to compile because of an incorrect initialization in some Next-related Appmake code. If that happens:

1. Run export CFLAGS=-Wno-int-conversion
2. Retry the build

---

Next

Getting started — first zcc command after install.