Installation from sources#
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 -N -B .
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 isNO
.
- -DCMAKE_BUILD_TYPE=(Debug|Release|RelWithDebInfo|MinSizeRel)#
Choose the type of build (configuration) to generate.
The default isRelease
.
- -DCMAKE_INSTALL_NAME_DIR="<path>"#
Specify the directory portion of the dynamic library install name on Apple platforms (for installed shared libraries).
Not defined by default.
- -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 isNO
.
- -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 isAuto
(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 overBUILD_SHARED_LIBS
andZ80_SHARED_LIBS
. If enabled, the build system will ignoreZ80_WITH_CMAKE_SUPPORT
andZ80_WITH_PKGCONFIG_SUPPORT
, as no libraries or support files will be installed.
The default isNO
.
- -DZ80_SHARED_LIBS=(YES|NO)#
Build the emulator as a shared library, rather than static.
This option takes precedence overBUILD_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 isNO
.
- -DZ80_WITH_HTML_DOCUMENTATION=(YES|NO)#
Build and install the documentation in HTML format.
It requires Doxygen, Sphinx and Breathe.
The default isNO
.
- -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 isNO
.
- -DZ80_WITH_PKGCONFIG_SUPPORT=(YES|NO)#
Generate and install the pkg-config file.
The default isNO
.
- -DZ80_WITH_STANDARD_DOCUMENTS=(YES|NO)#
Install the standard text documents distributed with the package:
AUTHORS
,COPYING
,COPYING.LESSER
,HISTORY
,README
andTHANKS
.
The default isNO
.
- -DZ80_WITH_TESTS=(YES|NO)#
Build the testing tool.
The default isNO
.
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 isNO
.
- -DZ80_WITH_FULL_IM0=(YES|NO)#
Build the full implementation of the interrupt mode 0 rather than the reduced one.
The default isNO
.
- -DZ80_WITH_IM0_RETX_NOTIFICATIONS=(YES|NO)#
Enable optional notifications for any
reti
orretn
instruction executed during the interrupt mode 0 response.
The default isNO
.
- -DZ80_WITH_SPECIAL_RESET=(YES|NO)#
Build the implementation of the special RESET.
The default isNO
.
- -DZ80_WITH_UNOFFICIAL_RETI=(YES|NO)#
Configure the undocumented instructions
ED5Dh
,ED6Dh
andED7Dh
asreti
instead ofretn
.
The default isNO
.
- -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 isNO
.
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.