installation
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. .
See Docker Usage for details.
Based on the docker image, there's an example devcontainer project: https://github.com/z88dk/z88dk-devcontainer-example
Note, some virus scanners report the presence of trojans within the z88dk kit. These are false detections. The detections seem to be triggered by the version of Mingw/gcc that is used to build the binaries. All binaries and kits are cross-compiled from Linux and haven't been near a Windows machine. See #2474 for more details.
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:
| Variable | Value |
|---|---|
| ZCCCFG | {z88dk}\lib\config |
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 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:
| Variable | Value |
|---|---|
| ZCCCFG | {z88dk}/lib/config |
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.
A snap file is available for certain Linux distributions. For more details see Snap usage.
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:
| 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 the following 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 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
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:
| Variable | Value |
|---|---|
ZCCCFG |
{z88dk}/lib/config |
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
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"
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.
Should you wish to time travel and use older versions of z88dk downloading either nightly kits or Docker builds are easiest. Should you need to build from source you may need to apply additional compiler options or other bodges to cope with compilers becoming better at identifying bugs and (by default) rejecting older C standards.
With recent GNU compilers, Z88DK v2.2 may fail to compile due to an incorrect initialization in some Next-related Appmake code. If that's the case, please do export CFLAGS=-Wno-int-conversion and then retry the build.