zxuno-git/sdk

Authors

This document:

• 2021 Ivan Tatarinov ivan-tat@ya.ru

Contributors

This document: No one yet.

Licenses

This document is under GNU FDL-1.3 or later license.
SJAsmPlus Z80 Assembler is distributed under zlib license.
SJAsmPlus Z80 Assembler by aprisobal (z00m128) is distributed under BSD 3-Clause "New" or "Revised" license.
Small Device C Compiler (SDCC) is distributed under GPL licenses.
z88dk is distributed under Clarified Artistic license.
LodePNG C/C++ library is distributed under zlib license.

1. General information

The structure of sdk folder:

Directory	Description
bin	Compiled binaries of tools.
include	Header files (.def, .h etc.) to be included in other sources (assembler, C, etc.).
lib	Libraries, needed for executables (mostly in bin directory) to function properly.
opt	Optionally installed bundles (like SDK).
src	The source code of local and downloadable tools. See Makefiles for details.
windows-x86	Compiled binaries of tools and libraries for Windows x86 (32 bit) platform.
macos-arm64	Compiled binaries of tools and libraries for macOS Ventura (ARM) platform.

1.1. Copyright and licensing information for files

We try to follow REUSE recommendations on how to easely specify copyright and licensing information to our files. So we added this information to each source file we used according to SPDX specification. Check it out by using this reuse-tool.

2. Using SDK in GNU environment on Linux, FreeBSD etc.

2.1. Prepare a build environment

2.1.1. On a Debian-based system (Ubuntu etc.)

Open terminal and type:

# apt install -y build-essential git

to install build-essential and git packages.

NOTE: here the first symbol "#" means that the following command must be run as root or using sudo utility.

Additional packages for targets:

Target	Packages
sjasmplus	cmake libboost-all-dev libxml2-dev
sdcc	-
z88dk	dos2unix libboost-all-dev texinfo texi2html libxml2-dev subversion bison flex zlib1g-dev m4

To use cross-compilation for Windows platform install mingw-w64 package.

2.1.2. Clone repository

Choose a directory for project and type:

git clone git://github.com/zxdos/zxuno.git zxuno

Now zxuno sub-directory is the ZX-Uno project's root directory and all actions we'll make inside it.

2.2. Build tools

Go to the project's root directory, enter sdk sub-directory and type one of the following commands:

Command	Description
make configure	Configure build with default values (on first call)
make configure <CFG_PARAMS>	Configure build with explicit values
make	Build and install all tools from sources
make <TARGET>	Build and install only the TARGET from sources
make BUILD=<BUILD>	Cross-build and install all tools from sources for Windows platform
make BUILD=<BUILD> <TARGET>	Cross-build and install only the TARGET from sources for Windows platform

where:

<CFG_PARAMS> is a series of parameters of type <CFG_VAR>=<VALUE>.

Value of <CFG_VAR>	Possible values	Description
USE_SJASMPLUS_VERSION	sjasmplus, z00m128	Version of SJAsmPlus Z80 Compiler to use. Default is z00m128 (aprisobal).

Value of TARGET	Origin	Description
sjasmplus	downloaded	SJAsmPlus Z80 Assembler
sdcc	downloaded	Small Device C Compiler
z88dk	downloaded	z88dk
lodepng	src/lodepng	LodePNG library
zx7b	src/zx7b	zx7b
tools	src/tools	tools

Value of BUILD	Target directory	Target system
mingw32	windows-x86	Windows with i686 architecture (32-bits)
mingw64	windows-x86_64	Windows with AMD64 architecture (64-bits)

Compiled binaries are installed into bin sub-directory of target directory. Compiled libraries are installed into lib sub-directory of target directory. Complex bundles are installed into opt sub-directory of target directory.

Example:

make BUILD=mingw64 tools

Then you may use strip tool to strip debug information from file and thus shrink file's size. Example:

strip windows-x86/bin/*.exe

For more options see Makefile.

2.3. Clean tools

Go to the project's root directory, enter sdk sub-directory and type one of the following commands:

Command	Description
make uninstall	remove installed binaries
make clean	clean after compilation from sources
make distclean	acts like clean but also remove temporary and downloaded files
make BUILD=<BUILD> uninstall	remove installed binaries for Windows platform
make BUILD=<BUILD> clean	clean after compilation from sources for Windows platform
make BUILD=<BUILD> distclean	acts like clean for Windows platform but also remove temporary and downloaded files

Value of BUILD is described in 2.2.

For more options see Makefile.

2.4. Tools usage

These tools are supposed to be used mainly in Makefiles and Bash scripts invoked from Makefiles.

2.4.1. In Makefiles

To use these tools in a Makefile just include common.mk file at the beginning of one like this:

include ../sdk/common.mk

Remember to specify correct relative path to it.

This will set ZXSDK environment variable (on first inclusion only) and update your PATH environment variable to point to SDK's tools. These changes are actual for current invocation of make utility and all child processes.

2.4.2. In Bash scripts

Bash scripts are supposed to be invoked from Makefiles where the correct environment is already prepared by make utility so nothing must be done for such scripts.

In other cases you must source setenv.sh file in a Bash script like this:

source ../sdk/setenv.sh

or

. ../sdk/setenv.sh

Remember to specify correct relative path to it.

This has the same behavior as the inclusion of common.mk file in a Makefile.

3. Using SDK in GNU environment on Windows

3.1. Prepare a build environment

3.1.1. Setup Cygwin

Download and run Cygwin GUI installer for Windows, either 32 bit or 64 bit version. See Chapter 2. Setting Up Cygwin for more information.

Install the following packages in Cygwin:

Target	Dependencies
all targets	bash git make wget unzip p7zip
sjasmplus	gcc-g++ cmake libboost-devel
sdcc	-
z88dk	mingw64-i686-gcc-core mingw64-i686-libxml2 patch
lodepng	gcc-core
zx7b	gcc-core
tools	gcc-core

HINT: you can install Midnight Commander (mc package). It will help you to navigate through filesystem.

To open Cygwin terminal just click on it's icon on desktop. This will open a Bash shell in a GNU environment.

3.1.2. Clone repository

The cloning is described in 2.1.2.

3.2. Build tools

Go to the project's root directory, enter sdk sub-directory and type one of the following commands:

Command	Description
make configure	Configure build with default values (on first call)
make configure <CFG_PARAMS>	Configure build with explicit values
make	Quick setup of all tools (download precompiled binaries and install them)
make <TARGET>	Qucik setup of the TARGET only
make FORCEBUILD=1	Build and install all tools from sources
make FORCEBUILD=1 <TARGET>	Build and install only the TARGET from sources

where:

<CFG_PARAMS> is a series of parameters as described in 2.2.

Value of TARGET	Sources origin	Binaries origin (Quick setup)	Build from sources
sjasmplus	downloaded	downloaded (yes)	available
sdcc	downloaded	downloaded (yes)	available
z88dk	downloaded	downloaded (yes)	available
lodepng	local	precompiled locally (no)	available
zx7b	local	precompiled locally (no)	available
tools	local	precompiled locally (no)	available

Then you may use strip tool to strip debug information from file and thus shrink file's size. Example:

strip windows-x86/bin/*.exe

For more options see Makefile.

3.3. Clean tools

Go to the project's root directory, enter sdk sub-directory and type one of the following commands:

Command	Description
make FORCECLEAN=1 uninstall	remove installed binaries from SDK after quick setup
make FORCECLEAN=1 clean	clean sources from downloaded binaries after quick setup
make FORCECLEAN=1 distclean	acts as forced clean but also removes temporary and downloaded files
make FORCEBUILD=1 FORCECLEAN=1 uninstall	remove all installed binaries from SDK
make FORCEBUILD=1 FORCECLEAN=1 clean	clean SDK after compilation from sources
make FORCEBUILD=1 FORCECLEAN=1 distclean	acts as forced clean after compilation from sources but also removes temporary and downloaded files

For more options see Makefile.

3.4. Tools usage

3.4.1. In Makefiles

The usage is similar to one for GNU on Linux, FreeBSD etc. See 2.4.1.

3.4.2. In Bash scripts

The usage is similar to one for GNU on Linux, FreeBSD etc. See 2.4.2.

4. Using SDK on Windows without GNU environment

4.1. Prepare a build environment

You should manually download precompiled binaries of SJAsmPlus and Z88DK from Internet and put them in their sub-directories as described in src/Makefile.

4.2. In batch scripts

To use these tools in a batch script just call setenv.bat file at the beginning of one like this:

call ..\sdk\setenv.bat

Remember to specify correct relative path to it.

This will set ZXSDK environment variable (on first call only) and update your PATH environment variable to point to SDK's tools. These changes are actual for current invocation of command shell and all child processes.

References

• REUSE SOFTWARE - a set of recommendations to make licensing your Free Software projects easier
• The Software Package Data Exchange (SPDX) - An open standard for communicating software bill of material information, including components, licenses, copyrights, and security references
• GNU Operating System
• GNU Standards - GNU coding and package maintenance standards (package)
• GNU Core Utilities (package)
• GNU Bash - GNU Bourne Again SHell (package)
• GNU Compiler Collection (package)
• GNU Make - utility for directing compilation (package)
• Cygwin - a large collection of GNU and Open Source tools which provide functionality similar to a Linux distribution on Windows
• MSYS2 - a collection of tools and libraries providing you with an easy-to-use environment for building, installing and running native Windows software
• MinGW - Minimalist GNU for Windows
• MinGW-w64 - an advancement of the original mingw.org project, created to support the GCC compiler on Windows systems
• cmd - command interpreter in Windows
• Windows commands
• SJAsmPlus - Z80 Assembler
• SJAsmPlus by aprisobal - Z80 Assembler
• SDCC - Small Device C Compiler
• Z88DK - The Development Kit for Z80 Computers
• LodePNG - PNG encoder and decoder in C and C++
• Open Source FPGA Foundation Formed to Accelerate Widespread Adoption of Programmable Logic - news article (April 8, 2021)
• Open-Source FPGA Foundation - main site
• Related Projects of Open Source FPGA Foundation - page on GitHub