Documentation: Installation from sources and integration.

redcode · redcode · commit f7fb4821aaf6 · 2025-01-22T02:06:23.000+01:00
diff --git a/README.md b/README.md
@@ -358,9 +358,15 @@ Pre-built binaries for Windows are available on the [download](https://zxe.io/so
 
 ## Installation from sources
 
+### Prerequisites
+
 You will need [CMake](https://cmake.org) v3.14 or later to build the package and, optionally, recent versions of [Doxygen](https://www.doxygen.nl), [Sphinx](https://www.sphinx-doc.org) and [Breathe](https://www.breathe-doc.org) to compile the documentation. Also, make sure that you have [LaTeX](https://www.latex-project.org) 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](https://zeta.st), a dependency-free, [header-only](https://en.wikipedia.org/wiki/Header-only) library used to retain compatibility with most C compilers. Install Zeta or extract its [source code tarball](https://zeta.st/download) 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](https://en.wikipedia.org/wiki/C_standard_library).
+The Z80 library requires some types and macros included in [Zeta](https://zxe.io/software/Zeta), a [header-only](https://en.wikipedia.org/wiki/Header-only), dependency-free library used for portability reasons. Install Zeta or extract its [source code tarball](https://zxe.io/software/Zeta/download) to the root directory of the Z80 project or its parent directory. Zeta is the sole dependency; the emulator does not depend on the [C standard library](https://en.wikipedia.org/wiki/C_standard_library).
+
+Lastly, the package includes two testing tools. The first one runs various Z80-specific tests for [CP/M](https://en.wikipedia.org/wiki/CP/M) and [ZX Spectrum](https://en.wikipedia.org/wiki/ZX_Spectrum) and will use [libzip](https://libzip.org) and [zlib](https://zlib.net) if they are available on your system. The second tool is for [unit tests in JSON format](https://github.com/SingleStepTests/z80) and requires the [cJSON](https://github.com/DaveGamble/cJSON) and [Z80InsnClock](https://zxe.io/software/Z80InsnClock) libraries. Building these tools is optional.
+
+### Configure
 
 Once the prerequisites are met, create a directory and run `cmake` from there to prepare the build system:
 
@@ -452,6 +458,11 @@ If in doubt, read the [CMake documentation](https://cmake.org/documentation/) fo
 	Install the standard text documents distributed with the package: [`AUTHORS`](AUTHORS), [`COPYING`](COPYING), [`COPYING.LESSER`](COPYING.LESSER), [`HISTORY`](HISTORY), [`README`](README) and [`THANKS`](THANKS).  
 	The default is `NO`.
 
+* <span id="cmake_option_z80_with_step_testing_tool">**`-DZ80_WITH_STEP_TESTING_TOOL=(YES|NO)`**</span>  
+	Build `step-test-Z80`, a tool for [unit tests in JSON format](https://github.com/SingleStepTests/z80).  
+	It requires cJSON and Z80InsnClock.  
+	The default is `NO`.
+
 * <span id="cmake_option_z80_with_testing_tool">**`-DZ80_WITH_TESTING_TOOL=(YES|NO)`**</span>  
 	Build `test-Z80`, a tool that runs various Z80-specific tests for [CP/M](https://en.wikipedia.org/wiki/CP/M) and [ZX Spectrum](https://en.wikipedia.org/wiki/ZX_Spectrum).  
 	The default is `NO`.
@@ -504,6 +515,8 @@ Package maintainers are encouraged to use at least the following options for the
 -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:
 
 ```shell
@@ -620,9 +633,9 @@ When not specified as a component, the linking method is selected according to [
 
 ### As a CMake subproject
 
-To embed the Z80 library as a CMake subproject, extract the source code tarballs of [Zeta](https://zeta.st/download) and [Z80](https://zxe.io/software/Z80/download) (or clone their respective repositories) into a subdirectory of another project. Then use [`add_subdirectory`](https://cmake.org/cmake/help/latest/command/add_subdirectory.html) in the parent project to add the Z80 source code tree to the build process (N.B., the Z80 subproject will automatically find Zeta and import it as an [interface library](https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#interface-libraries)).
+To embed the Z80 library as a CMake subproject, extract the source code tarballs of [Zeta](https://zxe.io/software/Zeta/download) and [Z80](https://zxe.io/software/Z80/download) (or clone their respective repositories) into a subdirectory of another project. Then use [`add_subdirectory`](https://cmake.org/cmake/help/latest/command/add_subdirectory.html) in the parent project to add the Z80 source code tree to the build process (N.B., the Z80 subproject will automatically find Zeta and import it as an [interface library](https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#interface-libraries)).
 
-It is advisable to configure the Z80 library in the `CMakeLists.txt` of the parent project. This will prevent the user from having to specify [configuration options for the Z80 subproject](#cmake_package_options) through the command line when building the main project.
+It is advisable to configure the Z80 library in the `CMakeLists.txt` of the parent project. This will eliminate the need for the user to specify [configuration options for the Z80 subproject](#cmake_package_options) through the command line when building the main project.
 
 Example:
 
@@ -643,16 +656,16 @@ The source code of the emulator can be configured at compile time by predefining
 
 * <span id="macro_z80_external_header">**`#define Z80_EXTERNAL_HEADER "header-name.h"`**</span>  
 	Specifies the only external header to `#include`, replacing all others.  
-	Predefine this macro to provide a header file that defines the external types and macros used by the emulator, thus preventing your project from depending on [Zeta](https://zeta.st). You can use this when compiling `Z80.c` as a part of your project or (if your types do not break the binary compatibility) when including `<Z80.h>` and linking against a pre-built Z80 library.
+	Predefine this macro to provide a header file that defines the external types and macros used by the emulator, thus preventing your project from depending on [Zeta](https://zxe.io/software/Zeta). You can use this when compiling `Z80.c` within your project or (if your types do not break the binary compatibility) when including `<Z80.h>` and linking against a pre-built Z80 library.
 
 * <span id="macro_z80_static">**`#define Z80_STATIC`**</span>  
-	Restricts the visibility of public symbols.  
-	This macro is required if you are building `Z80.c` as a static library, compiling it directly as a part of your project, or linking your program against the static version of the Z80 library. In either of these cases, make sure this macro is defined before including `"Z80.h"` or `<Z80.h>`.
+	Indicates that the emulator is a static library.  
+	This macro must be predefined when building `Z80.c` as a static library. Additionally, if you compile `Z80.c` directly within your project or link your program against the static version of the Z80 library, ensure that this macro is defined before including `"Z80.h"` or `<Z80.h>`.
 
 * <span id="macro_z80_with_local_header">**`#define Z80_WITH_LOCAL_HEADER`**</span>  
 	Tells `Z80.c` to <code>#include&nbsp;"Z80.h"</code> instead of `<Z80.h>`.
 
-The optional features of the emulator mentioned in "[Installation from sources](#installation-from-sources)" are disabled by default. If you compile `Z80.c` as a part of your project, enable those features you need by predefining their respective activation macros. They have the same name as their [CMake equivalents](#cmake_package_source_code_options):
+The optional features of the emulator mentioned in the "[Configure](#configure)" section of "[Installation from sources](#installation-from-sources)" are disabled by default. If you compile `Z80.c` within your project, enable those features you need by predefining their respective activation macros. They have the same name as their [CMake equivalents](#cmake_package_source_code_options):
 
 * **<code>#define [Z80_WITH_EXECUTE](#cmake_option_z80_with_execute)</code>**
 * **<code>#define [Z80_WITH_FULL_IM0](#cmake_option_z80_with_full_im0)</code>**
diff --git a/documentation/installation-from-sources.rst b/documentation/installation-from-sources.rst
@@ -14,27 +14,30 @@ Installation from sources
 
       \newline
 
-.. |cmake_option_build_config| replace:: ``--config``
-.. _cmake_option_build_config: https://cmake.org/cmake/help/latest/manual/cmake.1.html#cmdoption-cmake-build-config
-
 .. |cmake_option_install_component| replace:: ``--component``
 .. _cmake_option_install_component: https://cmake.org/cmake/help/latest/manual/cmake.1.html#cmdoption-cmake-install-component
 
+.. |cmake_option_build_config| replace:: ``--config``
+.. _cmake_option_build_config: https://cmake.org/cmake/help/latest/manual/cmake.1.html#cmdoption-cmake-build-config
+
 .. |cmake_option_install_strip| replace:: ``--strip``
 .. _cmake_option_install_strip: https://cmake.org/cmake/help/latest/manual/cmake.1.html#cmdoption-cmake-install-strip
 
 .. _config-file package: https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html#config-file-packages
 .. _CP/M: https://en.wikipedia.org/wiki/CP/M
 .. _file: https://people.freedesktop.org/~dbn/pkg-config-guide.html
 .. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config
+.. _unit tests in JSON format: https://github.com/SingleStepTests/z80
 .. _ZX Spectrum: https://en.wikipedia.org/wiki/ZX_Spectrum
 
 Prerequisites
 =============
 
 You will need `CMake <https://cmake.org>`_ v3.14 or later to build the package and, optionally, recent versions of `Doxygen <https://www.doxygen.nl>`_, `Sphinx <https://www.sphinx-doc.org>`_ and `Breathe <https://www.breathe-doc.org>`_ to compile the documentation. Also, make sure that you have `LaTeX <https://www.latex-project.org>`_ 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 <https://zeta.st>`_, a dependency-free, `header-only <https://en.wikipedia.org/wiki/Header-only>`_ library used to retain compatibility with most C compilers. Install Zeta or extract its `source code tarball <https://zeta.st/download>`_ 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 <https://en.wikipedia.org/wiki/C_standard_library>`_.
+The Z80 library requires some types and macros included in `Zeta <https://zxe.io/software/Zeta>`_, a `header-only <https://en.wikipedia.org/wiki/Header-only>`_, dependency-free library used for portability reasons. Install Zeta or extract its `source code tarball <https://zxe.io/software/Zeta/download>`_ to the root directory of the Z80 project or its parent directory. Zeta is the sole dependency; the emulator does not depend on the `C standard library <https://en.wikipedia.org/wiki/C_standard_library>`_.
+
+Lastly, the package includes two testing tools. The first one runs various Z80-specific tests for `CP/M`_ and `ZX Spectrum`_ and will use `libzip <https://libzip.org>`_ and `zlib <https://zlib.net>`_ if they are available on your system. The second tool is for `unit tests in JSON format`_ and requires the `cJSON <https://github.com/DaveGamble/cJSON>`_ and `Z80InsnClock <https://zxe.io/software/Z80InsnClock>`_ libraries. Building these tools is optional.
 
 Configure
 =========
@@ -148,14 +151,20 @@ Package-specific options are prefixed with ``Z80_`` and can be divided into two
    Install the standard text documents distributed with the package: :file:`AUTHORS`, :file:`COPYING`, :file:`COPYING.LESSER`, :file:`HISTORY`, :file:`README` and :file:`THANKS`. |br| |nl|
    The default is ``NO``.
 
+.. option:: -DZ80_WITH_STEP_TESTING_TOOL=(YES|NO)
+
+   Build :file:`step-test-Z80`, a tool for `unit tests in JSON format`_. |br| |nl|
+   It requires cJSON and Z80InsnClock. |br| |nl|
+   The default is ``NO``.
+
 .. option:: -DZ80_WITH_TESTING_TOOL=(YES|NO)
 
    Build :file:`test-Z80`, a tool that runs various Z80-specific tests for `CP/M`_ and `ZX Spectrum`_. |br| |nl|
    The default is ``NO``.
 
 .. _cmake_package_source_code_options:
 
-The second group of package-specific options configures the source code of the library by predefining macros that enable :ref:`optional features <Introduction:Optional features>`:
+The second group of package-specific options configures the source code of the library by predefining macros that enable :ref:`optional features <introduction:Optional features>`:
 
 .. option:: -DZ80_WITH_EXECUTE=(YES|NO)
 
@@ -222,7 +231,9 @@ Finally, once the build system is configured according to your needs, build and
    cmake --build . [--config (Debug|Release|RelWithDebInfo|MinSizeRel)]
    cmake --install . [--config <configuration>] [--strip] [--component <component>]
 
-The |cmake_option_build_config|_ option is only necessary for those `CMake generators <https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html>`_ that ignore :option:`CMAKE_BUILD_TYPE<-DCMAKE_BUILD_TYPE>` (e.g., Xcode and Visual Studio). Use |cmake_option_install_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 |cmake_option_install_component|_ option. The project defines the following components:
+The |cmake_option_build_config|_ option is only necessary for those `CMake generators <https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html>`_ that ignore :option:`CMAKE_BUILD_TYPE<-DCMAKE_BUILD_TYPE>` (e.g., Xcode and Visual Studio). Use |cmake_option_install_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 |cmake_option_install_component|_ option.
+
+The project defines the following components:
 
 .. option:: Z80_Runtime
 
@@ -242,3 +253,9 @@ The |cmake_option_build_config|_ option is only necessary for those `CMake gener
 
    * Documentation in HTML format.
    * Documentation in PDF format.
+
+.. option:: Z80_Testing
+
+   * Testing tools.
+
+By default, the build system will install ``Z80_Runtime``, ``Z80_Development`` and ``Z80_Documentation``. The ``Z80_Testing`` component can only be installed explicitly.
diff --git a/documentation/integration.rst b/documentation/integration.rst
@@ -28,9 +28,9 @@ When not specified as a component, the linking method is selected according to :
 As a CMake subproject
 =====================
 
-To embed the Z80 library as a CMake subproject, extract the source code tarballs of `Zeta <https://zeta.st/download>`__ and `Z80 <https://zxe.io/software/Z80/download>`_ (or clone their respective repositories) into a subdirectory of another project. Then use |add_subdirectory|_ in the parent project to add the Z80 source code tree to the build process (N.B., the Z80 subproject will automatically find Zeta and import it as an `interface library <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#interface-libraries>`_).
+To embed the Z80 library as a CMake subproject, extract the source code tarballs of `Zeta <https://zxe.io/software/Zeta/download>`__ and `Z80 <https://zxe.io/software/Z80/download>`_ (or clone their respective repositories) into a subdirectory of another project. Then use |add_subdirectory|_ in the parent project to add the Z80 source code tree to the build process (N.B., the Z80 subproject will automatically find Zeta and import it as an `interface library <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#interface-libraries>`_).
 
-It is advisable to configure the Z80 library in the :file:`CMakeLists.txt` of the parent project. This will prevent the user from having to specify :ref:`configuration options for the Z80 subproject <cmake_package_options>` through the command line when building the main project.
+It is advisable to configure the Z80 library in the :file:`CMakeLists.txt` of the parent project. This will eliminate the need for the user to specify :ref:`configuration options for the Z80 subproject <cmake_package_options>` through the command line when building the main project.
 
 Example:
 
@@ -54,25 +54,25 @@ The source code of the emulator can be configured at compile time by predefining
 
    Specifies the only external header to ``#include``, replacing all others.
 
-   Predefine this macro to provide a header file that defines the external types and macros used by the emulator, thus preventing your project from depending on `Zeta <https://zeta.st>`__:
+   Predefine this macro to provide a header file that defines the external types and macros used by the emulator, thus preventing your project from depending on `Zeta <https://zxe.io/software/Zeta>`__:
 
    * Macros: ``Z_ALWAYS_INLINE``, ``Z_API_EXPORT``, ``Z_API_IMPORT``, ``Z_CAST``, ``Z_EMPTY``, ``Z_EXTERN_C_BEGIN``, ``Z_EXTERN_C_END``, ``Z_MEMBER_OFFSET``, ``Z_NULL``, ``Z_UINT8_ROTATE_LEFT``, ``Z_UINT8_ROTATE_RIGHT``, ``Z_UINT16``, ``Z_UINT16_BIG_ENDIAN``, ``Z_UINT32``, ``Z_UINT32_BIG_ENDIAN``, ``Z_UNUSED``, ``Z_USIZE`` and ``Z_USIZE_MAXIMUM``.
 
    * Types: ``zbool``, ``zchar``, ``zsint``, ``zsint8``, ``zuint``, ``zuint8``, ``zuint16``, ``zuint32``, ``zusize``, ``ZInt16`` and ``ZInt32``.
 
-   You can use this macro when compiling :file:`Z80.c` as a part of your project or (if your types do not break the binary compatibility) when including ``<Z80.h>`` and linking against a pre-built Z80 library.
+   You can use this macro when compiling :file:`Z80.c` within your project or (if your types do not break the binary compatibility) when including ``<Z80.h>`` and linking against a pre-built Z80 library.
 
 .. c:macro:: Z80_STATIC
 
-   Restricts the visibility of public symbols.
+   Indicates that the emulator is a static library.
 
-   This macro is required if you are building :file:`Z80.c` as a static library, compiling it directly as a part of your project, or linking your program against the static version of the Z80 library. In either of these cases, make sure this macro is defined before including ``"Z80.h"`` or ``<Z80.h>``.
+   This macro must be predefined when building :file:`Z80.c` as a static library. Additionally, if you compile :file:`Z80.c` directly within your project or link your program against the static version of the Z80 library, ensure that this macro is defined before including ``"Z80.h"`` or ``<Z80.h>``.
 
 .. c:macro:: Z80_WITH_LOCAL_HEADER
 
    Tells :file:`Z80.c` to ``#include "Z80.h"`` instead of ``<Z80.h>``.
 
-The :ref:`optional features <Introduction:Optional features>` of the emulator mentioned in the ":doc:`installation-from-sources`" section are disabled by default. If you compile :file:`Z80.c` as a part of your project, enable those features you need by predefining their respective activation macros. They have the same name as their :ref:`CMake equivalents <cmake_package_source_code_options>`:
+The :ref:`optional features <introduction:Optional features>` of the emulator mentioned in the ":ref:`Configure <installation-from-sources:Configure>`" section of ":doc:`installation-from-sources`" are disabled by default. If you compile :file:`Z80.c` within your project, enable those features you need by predefining their respective activation macros. They have the same name as their :ref:`CMake equivalents <cmake_package_source_code_options>`:
 
 .. c:macro:: Z80_WITH_EXECUTE
 
diff --git a/documentation/version-history.rst b/documentation/version-history.rst
@@ -15,7 +15,7 @@ This is an important update that addresses a number of issues and also includes
 2. Moved the public header from ``<emulation/CPU/Z80.h>`` to ``<Z80.h>``.
 3. Removed the Xcode project.
 4. Switched the build system from Premake to `CMake <https://cmake.org>`_.
-5. Switched to `Zeta <https://zeta.st>`_ v0.1.
+5. Switched to `Zeta <https://zxe.io/software/Zeta>`_ v0.1.
 6. Added `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config>`_ support.
 7. Added the following files to the project: :file:`.vimrc`, :file:`CITATION.cff` and :file:`THANKS`.
 8. Added detailed documentation.
