zxuno-git/sdk

Authors

2021 Ivan Tatarinov ivan-tat@ya.ru

Contributors

No one yet.

License

This document is under GNU FDL-1.3 or later license.
SJAsmPlus Z80 Assembler is distributed under zlib license.
z88dk is distributed under Clarified Artistic 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.).
src	The source code of local and downloadable tools. See Makefiles for details.

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

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
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:

# apt install -y mingw-w64

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	Build all tools from sources
make <TARGET>	Build only the TARGET from sources
make BUILD=<BUILD>	Cross-build all tools from sources for Windows platform
make BUILD=<BUILD> <TARGET>	Cross-build only the TARGET from sources for Windows platform

where:

Value of TARGET	Origin	Description
sjasmplus	downloaded	SJAsmPlus Z80 Assembler
z88dk	downloaded	z88dk
zx7b	src/zx7b	zx7b
tools	src/tools	tools

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

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 bin/*.exe

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 clean	clean after compilation from sources
make dist-clean	acts like clean but also removes temporary and downloaded files
make BUILD=<BUILD> clean	clean after compilation from sources for Windows platform
make BUILD=<BUILD> dist-clean	acts like clean for Windows platform but also removes temporary and downloaded files

Value of BUILD is described in 2.2.

Example:

make BUILD=mingw64 clean

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 ZXUNOSDK 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 setvars.sh file in a Bash script like this:

source ../sdk/setvars.sh

or

. ../sdk/setvars.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
z88dk	mingw64-i686-gcc-core mingw64-i686-libxml2 patch
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	Quick setup of all tools
make <TARGET>	Qucik setup of the TARGET only
make FORCEBUILD=1	Build all tools from sources
make FORCEBUILD=1 <TARGET>	Build only the TARGET from sources

where:

Value of TARGET	Origin	Quick setup	Build from sources
sjasmplus	downloaded	available	available
z88dk	downloaded	available	available
zx7b	src/zx7b	N/A	available
tools	src/tools	N/A	available

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

strip bin/*.exe

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 clean	removes downloaded precompiled binaries only
make dist-clean	acts as clean but also removes temporary and downloaded files
make FORCECLEAN=1 clean	clean after compilation from sources
make FORCECLEAN=1 dist-clean	acts as forced clean but also removes temporary and downloaded files

Example:

make FORCECLEAN=1 clean

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 setvars.bat file at the beginning of one like this:

call ..\sdk\setvars.bat

Remember to specify correct relative path to it.

This will set ZXUNOSDK 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
• Z88DK - The Development Kit for Z80 Computers
• 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