Installation#

Prerequisites#

You will need CMake v3.14 or later to build the package and, optionally, recent versions of Doxygen, Sphinx and Breathe to compile the documentation. Also, make sure that you have LaTeX with PDF support installed on your system if you want to generate the documentation in PDF format.

The emulator requires some types and macros included in Zeta, a dependency-free, header-only library used to retain compatibility with most C compilers. Install Zeta or extract its source code tarball to the root directory of the Z80 project or its parent directory. Zeta is the sole dependency; the emulator is a freestanding implementation and as such does not depend on the C standard library.

Configure#

Once the prerequisites are met, create a directory and run cmake from there to prepare the build system:

mkdir build
cd build
cmake [options] <Z80-project-directory>

The resulting build files can be configured by passing options to cmake. To show a complete list of those available along with their current settings, type the following:

cmake -LAH

If in doubt, read the CMake documentation for more information on configuration options. The following are some of the most relevant standard options of CMake:

-DBUILD_SHARED_LIBS=(YES|NO)#

Generate shared libraries rather than static libraries.
The default is NO.

-DCMAKE_BUILD_TYPE=(Debug|Release|RelWithDebInfo|MinSizeRel)#

Choose the type of build (configuration) to generate.
The default is Release.

-DCMAKE_INSTALL_PREFIX="<path>"#

Specify the installation prefix.
The default is "/usr/local" (on UNIX and UNIX-like operating systems).

Package-specific options are prefixed with Z80_ and can be divided into two groups. The first one controls aspects not related to the source code of the library:

-DZ80_DEPOT_LOCATION="<location>"#

Specify the directory or URL of the depot containing the test files (i.e., the firmware and software required by the testing tool).
The default is "http://zxe.io/depot".

-DZ80_FETCH_TEST_FILES=(YES|NO)#

Copy or download the test files from the depot to the build directory.
The default is NO.

-DZ80_INSTALL_CMAKEDIR="<path>"#

Specify the directory in which to install the CMake config-file package.
The default is "${CMAKE_INSTALL_LIBDIR}/cmake/Z80".

-DZ80_INSTALL_PKGCONFIGDIR="<path>"#

Specify the directory in which to install the pkg-config file.
The default is "${CMAKE_INSTALL_LIBDIR}/pkgconfig".

-DZ80_NOSTDLIB_FLAGS=(Auto|"[<flag>[;<flag>...]]")#

Specify the linker flags used to avoid linking against system libraries.
The default is Auto (autoconfigure flags). If you get linker errors, set this option to "".

-DZ80_OBJECT_LIBS=(YES|NO)#

Build the emulator as an object library.
This option takes precedence over BUILD_SHARED_LIBS and Z80_SHARED_LIBS. If enabled, the build system will ignore Z80_WITH_CMAKE_SUPPORT and Z80_WITH_PKGCONFIG_SUPPORT, as no libraries or support files will be installed.
The default is NO.

-DZ80_SHARED_LIBS=(YES|NO)#

Build the emulator as a shared library, rather than static.
This option takes precedence over BUILD_SHARED_LIBS.
Not defined by default.

-DZ80_SPHINX_HTML_THEME="[<name>]"#

Specify the Sphinx theme for the documentation in HTML format.
The default is "" (use the default theme).

-DZ80_WITH_CMAKE_SUPPORT=(YES|NO)#

Generate and install the CMake config-file package.
The default is NO.

-DZ80_WITH_HTML_DOCUMENTATION=(YES|NO)#

Build and install the documentation in HTML format.
It requires Doxygen, Sphinx and Breathe.
The default is NO.

-DZ80_WITH_PDF_DOCUMENTATION=(YES|NO)#

Build and install the documentation in PDF format.
It requires Doxygen, Sphinx, Breathe, and LaTeX with PDF support.
The default is NO.

-DZ80_WITH_PKGCONFIG_SUPPORT=(YES|NO)#

Generate and install the pkg-config file.
The default is NO.

-DZ80_WITH_STANDARD_DOCUMENTS=(YES|NO)#

Install the standard text documents distributed with the package: AUTHORS, COPYING, COPYING.LESSER, HISTORY, README and THANKS.
The default is NO.

-DZ80_WITH_TESTS=(YES|NO)#

Build the testing tool.
The default is NO.

The second group of package-specific options configures the source code of the library by predefining macros that enable optional features:

-DZ80_WITH_EXECUTE=(YES|NO)#

Build the implementation of the z80_execute() function.
The default is NO.

-DZ80_WITH_FULL_IM0=(YES|NO)#

Build the full implementation of the interrupt mode 0 rather than the reduced one.
The default is NO.

-DZ80_WITH_IM0_RETX_NOTIFICATIONS=(YES|NO)#

Enable optional notifications for any reti or retn instruction executed during the interrupt mode 0 response.
The default is NO.

-DZ80_WITH_Q=(YES|NO)#

Build the implementation of Q.
The default is NO.

-DZ80_WITH_SPECIAL_RESET=(YES|NO)#

Build the implementation of the special RESET.
The default is NO.

-DZ80_WITH_UNOFFICIAL_RETI=(YES|NO)#

Configure the undocumented instructions ED5Dh, ED6Dh and ED7Dh as reti instead of retn.
The default is NO.

-DZ80_WITH_ZILOG_NMOS_LD_A_IR_BUG=(YES|NO)#

Build the implementation of the bug affecting the Zilog Z80 NMOS, which causes the P/V flag to be reset when a maskable interrupt is accepted during the execution of the ld a,{i|r} instructions.
The default is NO.

Package maintainers are encouraged to use at least the following options for the shared library:

-DZ80_WITH_EXECUTE=YES
-DZ80_WITH_FULL_IM0=YES
-DZ80_WITH_IM0_RETX_NOTIFICATIONS=YES
-DZ80_WITH_Q=YES
-DZ80_WITH_ZILOG_NMOS_LD_A_IR_BUG=YES

Build and install#

Finally, once the build system is configured according to your needs, build and install the package:

cmake --build . [--config (Debug|Release|RelWithDebInfo|MinSizeRel)]
cmake --install . [--config <configuration>] [--strip] [--component <component>]

The --config option is only necessary for those CMake generators that ignore CMAKE_BUILD_TYPE (e.g., Xcode and Visual Studio). Use --strip to remove debugging information and non-public symbols when installing non-debug builds of the shared library. To install only a specific component of the package, use the --component option. The project defines the following components:

Z80_Runtime#

  • Shared library.

  • Symbolic link for the compatibility version of the shared library.

  • Standard text documents.

Z80_Development#

  • Static library.

  • Unversioned symbolic link of the shared library.

  • Public header.

  • CMake config-file package.

  • pkg-config file.

Z80_Documentation#

  • Documentation in HTML format.

  • Documentation in PDF format.