Z88DK

https://github.com/z88dk/z88dk
Admin
Z88DK is a collection of software development tools targeting 8080 and Z80 family machines, enabling...
Tokens:478,664
Snippets:5,201
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Compile z88dk examples

Source: https://github.com/z88dk/z88dk/blob/master/doc/Dockerfile.md

Example of running make within the examples directory of the z88dk repository.

```bash
cd ${z88dk}/examples
docker run -v ${PWD}:/src/ --rm -it z88dk make
```

--------------------------------

### Build Output Example

Source: https://github.com/z88dk/z88dk/blob/master/doc/target/zx/05_MultipleFiles.md

Example output showing the commands executed by the makefile.

```sh
>make all
zcc +zx -vn -c -SO3 --max-allocs-per-node200000 -compiler sdcc -clib=sdcc_iy -pragma-include:zpragma.inc -o text_main.o text_main.c
zcc +zx -vn -c -o text_via_makefile.o text_via_makefile.asm
zcc +zx -vn -clib=sdcc_iy -pragma-include:zpragma.inc -startup=4 text_main.o text_via_makefile.o -o text -create-app
```

--------------------------------

### Build all examples

Source: https://github.com/z88dk/z88dk/blob/master/examples/g800/README.md

Compiles all source files into intelhex (ihx) format.

```bash
make
```

--------------------------------

### Compile and run command-line argument example

Source: https://github.com/z88dk/z88dk/blob/master/doc/target/pps/README.md

Compile an example that demonstrates command-line argument parsing and its expected output.

```sh
zcc +pps -clib=default -create-app examples/pps/argv.c -o argv
```

```text
ARGV.EXE one two
```

--------------------------------

### Compile Tritone example

Source: https://github.com/z88dk/z88dk/blob/master/doc/Dockerfile.md

Executing a custom build script inside the Tritone example directory.

```bash
cd ${z88dk}/libsrc/_DEVELOPMENT/EXAMPLES/zx/demo_tritone/
docker run -v ${PWD}:/src/ --rm -it z88dk ./build.sh
```

--------------------------------

### Main Entry Point

Source: https://github.com/z88dk/z88dk/wiki/source

Initializes the environment and starts the Lisp top-level loop.

```c
void
main(void)
{
  init();
#ifdef SCHEME
  printf("\x0cCAMPUS LIsP\nLemon version,\nz88dk SCHEME variant\n");
#else
  printf("\x0cCAMPUS LIsP\nLemon version,\nz88dk variant\n");
#endif
  toplevel();
  quit();

  /*return 0;*/
}
```

--------------------------------

### Instrumental profiling session

Source: https://github.com/z88dk/z88dk/wiki/debugging

Example session showing how to start and stop the profiler within z88dk-ticks to inspect function performance.

```text
    $0038    (ASMDISP_SENDTO_CALLEE+41)> profiler start
Profiler enabled.

    $0038    (ASMDISP_SENDTO_CALLEE+41)> c
^CRequesting a break...
l_debug_push_frame:
                    pop     bc                              ;[cc52] c1

    $cc52    (l_debug_push_frame+0)> profiler stop
Profiling results:
----------------------------------
    Time     Share    Function
----------------------------------
 4134142       27%    update_game_state
 1617394       10%    client_map_render
 1053286        7%    update_object
 1047621        7%    client_map_update
  926913        6%    update_game_input
  855393        5%    update_object_boundaries
  754259        5%    check_is_block_blocking
  707894        4%    update_move_controls
  568581        3%    client_map_get_block
  562230        3%    client_map_redraw_chunks
  539196        3%    client_map_redraw_objects
  408572        2%    client_map_get
  305714        2%    proto_client_process
  241743        1%    recv_process
  229390        1%    process
  177202        1%    find_cached_chunk
  139233        0%    proto_req_object_callback
  128713        0%    client_message_object
  105020        0%    client_map_render_chunk
   89943        0%    client_message_sync
   79010        0%    memory_switch_cached_chunk
   78701        0%    zxgui_scene_iteration
   37521        0%    allocate_cached_chunk
   20181        0%    client_message_unsync
   15171        0%    proto_req_new_request
   13561        0%    proto_req_recv
    8853        0%    my_player_send_updated_coords
    8598        0%    get_uint8_property
    6510        0%    proto_object_read
    6481        0%    find_property
    4987        0%    free_cached_chunk
    4582        0%    client_new_message
    4123        0%    client_message_complete
----------------------------------

    $cc52    (l_debug_push_frame+0)>
```

--------------------------------

### Install MacOS Prerequisites

Source: https://github.com/z88dk/z88dk/wiki/installation

Homebrew command to install necessary build tools on MacOS.

```bash
brew install gmp libxml2 pkg-config
```

--------------------------------

### File Name Syntax Examples

Source: https://github.com/z88dk/z88dk/wiki/Platform-ZX-Basic-Driver

Examples of valid MS-DOS like file path syntax for the ZX BASIC driver.

```text
	"a:filename"	(drive #1)
	"H:filename"	.. i.e. 8th microdrive
	"filename"	(the file will be searched in drive #1)
	"2:filename"	..numbers are allowed, too !
	"P::"		Printer device on stream #3
```

--------------------------------

### Compile Commands for SP1 Example

Source: https://github.com/z88dk/z88dk/wiki/sp1_ex1

Use these zcc commands to compile the example program with different library configurations.

```bash
zcc +zx -vn -clib=new -startup=31 sp1_ex1.c gr_window.asm -o sp1_ex1 -create-app
zcc +zx -vn -SO3 -clib=sdcc_ix -startup=31 --max-allocs-per-node200000 sp1_ex1.c gr_window.asm -o sp1_ex1 -create-app
zcc +zx -vn -SO3 -clib=sdcc_iy -startup=31 --max-allocs-per-node200000 sp1_ex1.c gr_window.asm -o sp1_ex1 -create-app
```

--------------------------------

### Compile Command for Mothership Example

Source: https://github.com/z88dk/z88dk/blob/master/doc/target/zx/SP1_04_BiggerSprites.md

Command line to compile the mothership example using zcc.

```sh
zcc +zx -vn -m -startup=31 -clib=sdcc_iy mothership_landing.c mothership_sprite.asm -o mothership_landing -create-app
```

--------------------------------

### Compile Directory Reading Example

Source: https://github.com/z88dk/z88dk/blob/master/examples/zxn/unsorted/esxdos/readme.md

Compilation commands for the directory reading example using different z88dk compilers.

```bash
zcc +zxn -v -clib=sdcc_iy -SO3 --max-allocs-per-node200000 dir.c -o dir -subtype=nex -Cz"--clean" -create-app
```

```bash
zcc +zxn -v -clib=new dir.c -o dir -subtype=nex -Cz"--clean" -create-app
```

--------------------------------

### Build PPS examples

Source: https://github.com/z88dk/z88dk/blob/master/doc/target/pps/README.md

Commands to build the provided smoke tests for the +pps target.

```sh
cd examples/pps
make
```

--------------------------------

### Start a program on the Einstein

Source: https://github.com/z88dk/z88dk/wiki/Platform---Tatung-Einstein

Command entered at the Einstein boot prompt to execute a file.

```text
1:APP.COM
```

--------------------------------

### Compile with Startup Option

Source: https://github.com/z88dk/z88dk/wiki/Library-in-Depth

Example command line usage for selecting a specific startup configuration.

```bash
zcc +embedded -vn -startup=0 -SO3 -clib=sdcc_iy --max-allocs-per-node200000 test.c -o test
```

--------------------------------

### Verify z80asm installation

Source: https://github.com/z88dk/z88dk/blob/master/doc/target/zx/01_GettingStarted.md

Check that the Z80 assembler is installed and functional.

```sh
>z80asm
 Z80 Module Assembler 2.8.5, (c) InterLogic 1993-2009, Paulo Custodio 2011-2017
```

--------------------------------

### Compile with Startup Specification

Source: https://github.com/z88dk/z88dk/wiki/Library-in-Depth

Example command line for compiling a C program while specifying the startup value and library configuration.

```bash
zcc +z80 -vn -startup=0 -SO3 -clib=sdcc_iy --max-allocs-per-node200000 test.c -o test
```

--------------------------------

### NIRVANA_start()

Source: https://github.com/z88dk/z88dk/blob/master/libsrc/target/zx/nirvanap/readme.txt

Enables the NIRVANA+ engine.

```APIDOC
void NIRVANA_start();
```

--------------------------------

### Floating Point Number Examples

Source: https://github.com/z88dk/z88dk/blob/master/libsrc/math/float/math16/README.md

Examples of various values represented in the 16-bit format.

```text
  sign  exponent     mantissa
    0   01110    (1) 10000....    1.5 * 2 ^ (-1) =  0.75
    0   01111    (1) 10000....    1.5 * 2 ^ ( 0 )=  1.50
    1   10000    (1) 10000....   -1.5 * 2 ^ ( 1 )= -3.00
    0   10110    (1) 0110010010                  =178.3
    x   00000        xxx... zero (sign positive or negative, mantissa not relevant)
    x   11111        000... infinity  (sign positive or negative, mantissa zero)
    x   11111        xxx... not a number (sign positive or negative, mantissa non zero)
```

--------------------------------

### Optimizer rule example

Source: https://github.com/z88dk/z88dk/wiki/Tool---copt

A specific example of a rule transformation for jump and call instructions.

```asm
jr	z,ASMPC+3
	scf
	call	c,%2
=
	call	nz,%2
```

--------------------------------

### Initialize and run a basic BiFrost program

Source: https://github.com/z88dk/z88dk/blob/master/doc/target/zx/07_BiFrost.md

Sets up the BiFrost engine, clears the tile map, and renders a static tile at a specific coordinate.

```c
#pragma output REGISTER_SP  = -1
#pragma output CLIB_MALLOC_HEAP_SIZE = 0

#include <arch/zx.h>
#include <arch/zx/bifrost_l.h>

extern unsigned char ctiles[];

int main ( void ) {

    unsigned char blank_tile_index;
    unsigned char row, col;

    BIFROSTL_resetTileImages( _ctiles );

    for ( blank_tile_index = 0; blank_tile_index < 81; blank_tile_index++ )
        BIFROSTL_tilemap[blank_tile_index] = BIFROSTL_DISABLED;

    zx_cls(PAPER_WHITE);

    for ( row = 1; row <= 17; row++ )
        for ( col = 1; col <= 17; col += 2 )
            BIFROSTL_fillTileAttrL( row, col, INK_WHITE+PAPER_WHITE );

    BIFROSTL_setTile( 0, 0, (unsigned char)( 0 + BIFROSTL_STATIC ) );

    BIFROSTL_start();

    while(1);

}
```

--------------------------------

### Complete Malloc Usage Example

Source: https://github.com/z88dk/z88dk/wiki/Classic-allocation

Demonstrates heap initialization, adding memory blocks, dynamic allocation, and freeing memory.

```c
#include <malloc.h>
	
	...
	
	extern long heap(60000);    // place malloc's heap pointer at address 60000
	
	...
	
	main()
	{
	
	   ...
	
	   // initialize the heap before malloc is used
	
	   mallinit();              // heap cleared to empty
	   sbrk(30000,2000);        // add 2000 bytes from addresses 30000-31999 inclusive to the heap
	   sbrk(65000,536);         // add 536 bytes from addresses 65000-65535 inclusive to the heap
	
	   ...
	
	   a = (int *)(malloc(20*sizeof(int)));    // dynamically allocate an array of 20 integers
	
	   ...
	
	   free(a);                 // return memory to heap for reuse
	
	   ...
	
	}
```

--------------------------------

### Build and install libraries on Unix

Source: https://github.com/z88dk/z88dk/wiki/Classic-Building-the-libraries

Execute the build process and move the resulting library files to the appropriate directory.

```bash
make
cp *.lib ../lib/clibs/
```

--------------------------------

### Compile SNX example

Source: https://github.com/z88dk/z88dk/blob/master/examples/zxn/unsorted/big-sna/readme.md

Commands to compile the SNX example using zsdcc or sccz80 compilers.

```bash
zcc +zxn -vn -startup=0 -clib=sdcc_iy -SO3 --max-allocs-per-node200000 snx.c mem.asm -o snx -subtype=snx -Cz"--fullsize --clean" -create-app
```

```bash
zcc +zxn -vn -startup=0 -clib=new snx.c mem.asm -o snx -subtype=snx -Cz"--fullsize --clean" -create-app
```

--------------------------------

### Compile FZX example

Source: https://github.com/z88dk/z88dk/blob/master/examples/spectrum/unsorted/fzx_modes/README.md

Compilation commands for the ZX Spectrum using minimal CRT startup.

```bash
zcc +zx -vn -startup=31 -O3 -clib=new fzx_modes.c -o fzx_modes -create-app
```

```bash
zcc +zx -vn -startup=31 -SO3 -clib=sdcc_iy --max-allocs-per-node200000 fzx_modes.c -o fzx_modes -create-app
```

--------------------------------

### Verify SDCC Installation

Source: https://github.com/z88dk/z88dk/wiki/NewLib--Platform--Embedded

Check if the patched version of sdcc (zsdcc) is correctly installed and accessible.

```bash
zsdcc -v
```

--------------------------------

### Compile with zsdcc

Source: https://github.com/z88dk/z88dk/blob/master/examples/spectrum/unsorted/two_terminals/README.md

Compile the example using the zsdcc compiler with the specified startup and pragma configuration.

```bash
zcc +zx -vn -startup=31 -clib=sdcc_iy -SO3 --max-allocs-per-node200000 terminals_x2.c -o terminals_x2 -pragma-include:zpragma.inc -create-app
```

--------------------------------

### Floating Point Number Examples

Source: https://github.com/z88dk/z88dk/blob/master/libsrc/math/float/am9511/readme.md

Provides examples of how specific numbers are represented in the floating point format.

```text
  sign  exponent     mantissa
    0   01111110 (1) 10000....    1.5 * 2 ^ (-1) =  0.75
    0   01111111 (1) 10000....    1.5 * 2 ^ ( 0 )=  1.50
    1   10000000 (1) 10000....   -1.5 * 2 ^ ( 1 )= -3.00
    0   10000110 (1) 01100100010..               =178.25
    x   00000000     xxx... zero (sign positive or negative, mantissa not relevant)
    x   11111111     000... infinity  (sign positive or negative, mantissa zero)
    x   11111111     xxx... not a number (sign positive or negative, mantissa non zero)
```

--------------------------------

### Install z88dk Snap

Source: https://github.com/z88dk/z88dk/wiki/Snap-usage

Installs the latest version of z88dk from the Snap store using the edge channel.

```bash
sudo snap install --edge z88dk
```

--------------------------------

### Execute .RUN commands

Source: https://github.com/z88dk/z88dk/blob/master/examples/zxn/unsorted/dot-command/run/readme.md

Various examples of using the .RUN command to list, navigate, and execute files.

```text
.run
```

```text
.run -p
```

```text
.run -? war*
```

```text
.run -c warhawk.nex
```

```text
.run warhawk.nex
```

```text
.run -2 warhawk.nex
```

```text
.run castle*.tap
```

```text
LOAD "t:": LOAD ""
```

```text
.run -r castlevania.tap
```

```text
.run -? *batman*
.run -5 *batman*
```

--------------------------------

### Compile extended SNA example

Source: https://github.com/z88dk/z88dk/blob/master/examples/zxn/unsorted/big-sna/readme.md

Commands to compile the extended SNA example using zsdcc or sccz80 compilers.

```bash
zcc +zxn -vn -startup=0 -clib=sdcc_iy -SO3 --max-allocs-per-node200000 sna.c mem.asm -o sna -subtype=sna -Cz"--ext --fullsize --clean" -create-app
```

```bash
zcc +zxn -vn -startup=0 -clib=new sna.c mem.asm -o sna -subtype=sna -Cz"--ext --fullsize --clean" -create-app
```

--------------------------------

### Manually build PPS examples

Source: https://github.com/z88dk/z88dk/blob/master/examples/pps/README.md

Individual build commands for various PPS target configurations using zcc.

```sh
zcc +pps     -clib=default -create-app hello.c        -o build/hello
zcc +pps     -clib=default -create-app argv.c         -o build/argv
zcc +pps     -clib=default -create-app clear_screen.c -o build/clear
zcc +pps -subtype=low -clib=default -create-app hello.c -o build/hello_low
```

--------------------------------

### Linking with zxbasdrv using zcc

Source: https://github.com/z88dk/z88dk/wiki/Platform-ZX-Basic-Driver

Command line example for linking the library and merging a BASIC loader using appmake.

```bash
zcc +zxansi -lzxbasdrv -create-app  -zorg=27000 -Cz--merge -Czc:\if1.tap program.c
```

--------------------------------

### Display help and configuration

Source: https://github.com/z88dk/z88dk/wiki/Tool---zcc

Commands to view general help or specific port configuration details.

```bash
zcc -h
```

```bash
zcc +port -specs
```

--------------------------------

### Compile FZX Reader Example

Source: https://github.com/z88dk/z88dk/blob/master/examples/spectrum/unsorted/fzx_reader/README.md

Commands to compile the FZX reader example using either the sccz80 or zsdcc compiler.

```bash
zcc +zx -vn -startup=31 -O3 -clib=new fzx_reader.c The_Jungle.c -o fzxr -create-app
```

```bash
zcc +zx -vn -startup=31 -SO3 -clib=sdcc_iy --max-allocs-per-node200000 fzx_reader.c The_Jungle.c -o fzxr -create-app
```

--------------------------------

### AES-256 Test and Demonstration Program

Source: https://github.com/z88dk/z88dk/wiki/aes256

A complete example demonstrating initialization, encryption, decryption, and cleanup of the AES-256 context.

```c
#include <stdlib.h>

#include <stdio.h>
#include "aes256.h"

#define DUMP(s, i, buf, sz)  {printf(s); for (i = 0; i < (sz);i++) printf("%02x ", buf[i]);  printf("\n");}

int main (int argc, char *argv[])
{
    aes256_context ctx; 
    uint8_t key[32];
    uint8_t buf[16], i;

    /* put a test vector */
    for (i = 0; i < sizeof(buf);i++) buf[i] = i * 16 + i;
    for (i = 0; i < sizeof(key);i++) key[i] = i;

    DUMP("txt: ", i, buf, sizeof(buf));
    DUMP("key: ", i, key, sizeof(key));
    printf("---\n");

    aes256_init(&ctx, key);
    aes256_encrypt_ecb(&ctx, buf);

    DUMP("enc: ", i, buf, sizeof(buf));
    printf("tst: 8e a2 b7 ca 51 67 45 bf ea fc 49 90 4b 49 60 89\n");

    aes256_init(&ctx, key);
    aes256_decrypt_ecb(&ctx, buf);
    DUMP("dec: ", i, buf, sizeof(buf));

    aes256_done(&ctx);

    return 0;
} /* main */
```

--------------------------------

### Define a Target Configuration File

Source: https://github.com/z88dk/z88dk/wiki/Library-in-Depth

Create a .cfg file in z88dk/lib/config/ to define the startup code, default compiler options, and library paths for a new target.

```text
#
# Target configuration file for z88dk
#

# Asm file which contains the startup code (without suffix)
CRT0		 DESTDIR/lib/temp_crt0

# Any default options you want - these are options to zcc which are fed
# through to compiler, assembler etc as necessary
OPTIONS		 -v -O2 -SO2 -I. -DZ80 -DTEMP -D__TEMP__ -D__TEMP -M -clib=default

CLIB     default -ltemp_clib -lndos
CLIB     new -D__SCCZ80 -Ca-D__SCCZ80 -Cl-D__SCCZ80 -nostdlib -IDESTDIR/include/_DEVELOPMENT/sccz80 -Ca-IDESTDIR/libsrc/_DEVELOPMENT/target/temp -ltemp -LDESTDIR/libsrc/_DEVELOPMENT/lib/sccz80 -Cl-IDESTDIR/libsrc/_DEVELOPMENT/target/temp -crt0=DESTDIR/libsrc/_DEVELOPMENT/target/temp/temp_crt
CLIB     sdcc_ix -compiler=sdcc -D__SDCC -D__SDCC_IX -Ca-D__SDCC -Ca-D__SDCC_IX -Cl-D__SDCC -Cl-D__SDCC_IX -nostdlib -IDESTDIR/include/_DEVELOPMENT/sdcc -Ca-IDESTDIR/libsrc/_DEVELOPMENT/target/temp -ltemp -LDESTDIR/libsrc/_DEVELOPMENT/lib/sdcc_ix -Cl-IDESTDIR/libsrc/_DEVELOPMENT/target/temp -crt0=DESTDIR/libsrc/_DEVELOPMENT/target/temp/temp_crt
CLIB     sdcc_iy -compiler=sdcc --reserve-regs-iy -D__SDCC -D__SDCC_IY -Ca-D__SDCC -Ca-D__SDCC_IY -Cl-D__SDCC -Cl-D__SDCC_IY -nostdlib -IDESTDIR/include/_DEVELOPMENT/sdcc -Ca-IDESTDIR/libsrc/_DEVELOPMENT/target/temp -ltemp -LDESTDIR/libsrc/_DEVELOPMENT/lib/sdcc_iy -Cl-IDESTDIR/libsrc/_DEVELOPMENT/target/temp -crt0=DESTDIR/libsrc/_DEVELOPMENT/target/temp/temp_crt
```

--------------------------------

### Compilation Command Example

Source: https://github.com/z88dk/z88dk/wiki/Compiling-Larger-Applications

Example of a shell command used to compile a single C file with specific include paths.

```shell
zcc +zx  -Izx -o build/zx/func.o -c func.c
```

--------------------------------

### Initialization Routine

Source: https://github.com/z88dk/z88dk/wiki/source

Sets up the free cell list for memory management.

```c
void
init(void)
{
  int  i;

  /* make a free cell list */
  for (i = 0; i != NCONS-1; ++i)
    t_cons_car[i]  = i+1;
  t_cons_car[NCONS-1] = NCONS-1;    /* self-loop (this is very important) */
```

--------------------------------

### Compiling with WYZPlayer

Source: https://github.com/z88dk/z88dk/wiki/Classic-WYZ-Player

Example command-line instructions for compiling C projects with WYZPlayer assembly files for ZX Spectrum and MSX targets.

```bash
zcc +zx main.c tune.mus.asm -create-app
```

```bash
zcc +msx -subtype=rom main.c tune.mus.asm -create-app
```

--------------------------------

### Install required Perl modules via CPAN

Source: https://github.com/z88dk/z88dk/wiki/installation

Use cpanm to install the necessary Perl dependencies for the build environment.

```bash
cpanm App::Prove File::Path CPU::Z80::Assembler Object::Tiny::RW List::Uniq
```

--------------------------------

### Read user input with gets

Source: https://github.com/z88dk/z88dk/blob/master/doc/target/zx/02_HelloWorld.md

Demonstrates reading a string from standard input. Note that gets is dangerous and prone to buffer overflows.

```c
#include <arch/zx.h>
#include <stdio.h>

int main ( void ) {

    unsigned char name[15];

    zx_cls( PAPER_WHITE );

    printf( "What is your name? " );
    gets( name ); // Dangerous! See below
    printf( "Hello, %s", name );

    return 0;

}
```

--------------------------------

### Check Appmake Options

Source: https://github.com/z88dk/z88dk/wiki/clisp

Display available options for the ZX target in appmake.

```bash
appmake +zx
```

--------------------------------

### SP1 Sprite Example Source Code

Source: https://github.com/z88dk/z88dk/wiki/sp1_ex1

Full source code for the sp1_ex1_bonus.c example, including compilation instructions and library configuration pragmas.

```c
// By szeliga @ worldofspectrum.org forums
	
	// zcc +zx -vn -clib=new -startup=31 sp1_ex1_bonus.c graphics.asm collision.asm -o sp1_ex1_bonus
	// zcc +zx -vn -SO3 -clib=sdcc_ix -startup=31 --max-allocs-per-node200000 sp1_ex1_bonus.c graphics.asm collision.asm -o sp1_ex1_bonus
	// zcc +zx -vn -SO3 -clib=sdcc_iy -startup=31 --max-allocs-per-node200000 sp1_ex1_bonus.c graphics.asm collision.asm -o sp1_ex1_bonus
	
	#include <arch/zx/sp1.h>
	#include <arch/zx.h>
	#include <input.h>
	#include <sound.h>
	#include <stdlib.h>
	
	#pragma output REGISTER_SP           = 53248     // place stack at $d000 at startup
	
	#pragma output CRT_ENABLE_RESTART    = 1         // not returning to basic
	#pragma output CRT_ENABLE_CLOSE      = 0         // do not close files on exit
	
	#pragma output CLIB_EXIT_STACK_SIZE  = 0         // no exit stack
	
	#pragma output CLIB_MALLOC_HEAP_SIZE = 5000      // malloc heap size (not sure what is needed exactly)
	#pragma output CLIB_STDIO_HEAP_SIZE  = 0         // no memory needed to create file descriptors
	
	#pragma output CLIB_FOPEN_MAX        = -1        // no allocated FILE structures, -1 for no file lists too
	#pragma output CLIB_OPEN_MAX         = 0         // no fd table
	
	
	#define MAX_SPRITES  10
	#define DEAD_SPRITE  100
	
	#ifdef __SDCC
	extern int sp1_TestCollision(struct sp1_ss *s1, struct sp1_ss *s2, unsigned int tolerance) __z88dk_callee;
	#endif
	
	#ifdef __SCCZ80
	extern int __CALLEE__ sp1_TestCollision(struct sp1_ss *s1, struct sp1_ss *s2, unsigned int tolerance);
	#endif
	
	// Clipping Rectangle for Sprites
	
	struct sp1_Rect cr = {0, 0, 32, 24};            // rectangle covering the full screen
	
	// Table Holding Movement Data for Each Sprite
	
	struct sprentry
	{
	   struct sp1_ss  	*s;                     // sprite handle returned by sp1_CreateSpr()
	   char           	dx;                     // signed horizontal speed in pixels
	   char           	dy;                     // signed vertical speed in pixels
	   unsigned char        state;                  // frame state (MSS)
	};
	
	struct sprentry sprtbl[] = {
	   {0,1,0,0}, {0,0,1,0}, {0,1,2,0}, {0,2,1,0}, {0,1,3,0},
	   {0,3,1,0}, {0,2,3,0}, {0,3,2,0}, {0,1,1,0}, {0,2,2,0}
	};
	
	// A Hashed UDG for Background
	
	unsigned char hash[] = {127,255,255,255,223,255,251,255};
	
	// Attach C Variable to Sprite Graphics Declared in external ASM File
	
	extern unsigned char sprite01[];      // gr_window will hold the address of the asm label _gr_window
	extern unsigned char sprite02[];      // gr_window will hold the address of the asm label _gr_window
	extern unsigned char sprite03[];      // gr_window will hold the address of the asm label _gr_window
	extern unsigned char sprite04[];      // gr_window will hold the address of the asm label _gr_window
	
	// Callback Function to Colour Sprites Using sp1_IterateSprChar()
	
	unsigned char colour;
	unsigned char cmask;
	
	void colourSpr(unsigned int count, struct sp1_cs *c)
	{
	   c->attr_mask = cmask;
	   c->attr = colour;
	}
	
	main()
	{
	   static unsigned char i, j, deleteSpriteFlag, numLiveSprites;
	   static struct sp1_ss *s;
	   static struct sprentry *se;
	   
	   #asm
	   di
	   #endasm
	
	   // Initialize SP1.LIB
	   
	   zx_border(INK_BLACK);
	   
	   sp1_Initialize(SP1_IFLAG_MAKE_ROTTBL | SP1_IFLAG_OVERWRITE_TILES | SP1_IFLAG_OVERWRITE_DFILE, INK_BLACK | PAPER_WHITE, ' ');
	   sp1_TileEntry(' ', hash);   // redefine graphic associated with space character
	
	   sp1_Invalidate(&cr);        // invalidate entire screen so that it is all initially drawn
	   sp1_UpdateNow();            // draw screen area managed by sp1 now
	   
	   // Create and Colour Sprites
	
	   for (i=0; i!=MAX_SPRITES; ++i)
	   {
	      s = sprtbl[i].s = sp1_CreateSpr(SP1_DRAW_MASK2LB, SP1_TYPE_2BYTE,  3,  0,  i);
	      sp1_AddColSpr(s, SP1_DRAW_MASK2, 0, 48, i);
	      sp1_AddColSpr(s, SP1_DRAW_MASK2RB, 0, 0, i);
	      
	      colour = (i & 0x01) ? (INK_BLACK | PAPER_CYAN) : (INK_BLACK | PAPER_YELLOW);
	      cmask = SP1_AMASK_INK & SP1_AMASK_PAPER;
	      
	      sp1_IterateSprChar(s, colourSpr);
	   }
	   
	   // Main Loop
	   
	   while (1)
	   {
	      // Move Sprites to Initial Location
	      
	      for (i=0; i!=MAX_SPRITES; ++i)
	      {
	         sp1_MoveSprAbs(sprtbl[i].s, &cr, sprite01, (rand() & 0x0f) + 4, (rand() & 0x0f) + 8, 0, 4);
	         sprtbl[i].state = 0;
	      }
	      
	      do
	      {
	         sp1_UpdateNow();
	      
	         numLiveSprites = 0;
	      
	         for (i=0; i!=MAX_SPRITES; ++i)
	         {
	            // move all sprites
	         
	            se = &sprtbl[i];
	            
	            if ((j = se->state) != DEAD_SPRITE)
	            {
	               s = se->s;
	               
```

--------------------------------

### Compile SP1 Example with Memory Analysis

Source: https://github.com/z88dk/z88dk/wiki/sp1_ex1

Compiles the SP1 example using the SDCC IY library and generates separate binaries for each memory section to analyze usage.

```bash
zcc +zx -vn -SO3 -clib=sdcc_iy -startup=31 --max-allocs-per-node200000 sp1_ex1.c gr_window.asm -o sp1_ex1 -Cl--split-bin
```

--------------------------------

### Compile with sccz80

Source: https://github.com/z88dk/z88dk/blob/master/examples/spectrum/unsorted/two_terminals/README.md

Compile the example using the sccz80 compiler with the specified startup and pragma configuration.

```bash
zcc +zx -vn -startup=31 -clib=new -O3 terminals_x2.c -o terminals_x2 -pragma-include:zpragma.inc -create-app
```

--------------------------------

### Define and Install Raw C Interrupt Service Routines

Source: https://github.com/z88dk/z88dk/wiki/interrupts

Use M_BEGIN_ISR/M_END_ISR for standard ISRs or the LIGHT variants for faster execution with fewer saved registers. Install the resulting functions using im2_InstallISR.

```c
M_BEGIN_ISR(myisr)
{
   // insert C code here
}
M_END_ISR

M_BEGIN_ISR_LIGHT(myotherisr)
{
   // insert C code here
}
M_END_ISR_LIGHT

main()
{
   ...
   im2_InstallISR(0, myisr);        // install myisr() on vector 0
   im2_InstallISR(28, myotherisr)   // install myotherisr() on vector 28
   ...
}
```

--------------------------------

### Display .RUN help text

Source: https://github.com/z88dk/z88dk/blob/master/examples/zxn/unsorted/dot-command/run/readme.md

Shows the usage and available options for the .RUN command.

```text
.run [OPTIONS] FILE

supported extensions:  bas
dot nex o p sna snx tap z80

options:

-p = list dirs in PATH
-? = list FILE matches
-c = cd to FILE location
-r = retain cwd on clean exit
-N = select Nth FILE match

run 1.4 zx-next z88dk.org
```

--------------------------------

### ay_wyz_start

Source: https://github.com/z88dk/z88dk/wiki/Classic-WYZ-Player

Starts playback of a specific song index.

```APIDOC
## void ay_wyz_start(int song)

### Description
Prepares and starts the playback of the song at the specified index.

### Parameters
- **song** (int) - Required - The index of the song to play.
```

--------------------------------

### cpc_add_fast_isr()

Source: https://github.com/z88dk/z88dk/wiki/Platform---Amstrad-CPC

Installs an interrupt service routine called at 300Hz.

```APIDOC
## cpc_add_fast_isr()

### Description
Installs an interrupt service routine called at 300Hz.

### Signature
`void cpc_add_fast_isr();`
```

--------------------------------

### Build and install libraries on Windows

Source: https://github.com/z88dk/z88dk/wiki/Classic-Building-the-libraries

A sequence of commands to clone the repository, configure the environment, and build the libraries using git-bash.

```bash
git clone https://www.github.com/z88dk/z88dk
cd /
unzip make-4.1-2-without-guile-w32-bin.zip
cd z88dk/
export PATH=$(pwd)/bin:$PATH
export ZCCCFG=$(pwd)/lib/config
cd libsrc
make
cp *.lib ../lib/clibs/
```

--------------------------------

### Compile the project

Source: https://github.com/z88dk/z88dk/blob/master/examples/zxn/unsorted/sprites/mixed-sw-hw/readme.md

Use this command to compile the main C source and assembly files into a .nex application.

```bash
zcc +zxn -v -startup=1 -clib=sdcc_iy -SO3 --max-allocs-per-node200000 main.c graphics.asm.m4 interrupt.asm -o main -pragma-include:zpragma.inc -subtype=nex -Cz"--clean" -create-app
```

--------------------------------

### cpc_add_vsync_isr()

Source: https://github.com/z88dk/z88dk/wiki/Platform---Amstrad-CPC

Installs an interrupt service routine called at 50Hz.

```APIDOC
## cpc_add_vsync_isr()

### Description
Installs an interrupt service routine called at 50Hz. This is aliased to `add_raster_int()`.

### Signature
`void cpc_add_vsync_isr();`
```

--------------------------------

### Verify z88dk-appmake installation

Source: https://github.com/z88dk/z88dk/blob/master/doc/target/zx/01_GettingStarted.md

Check that the application generator tool is available.

```sh
>z88dk-appmake
 appmake [+target] [options]

 The z88dk application generator
 <pages and pages of help and options snipped>
```

--------------------------------

### NIRVANA_start

Source: https://github.com/z88dk/z88dk/blob/master/libsrc/target/zx/nirvanam/readme.txt

Enables the Nirvana Engine.

```APIDOC
## NIRVANA_start()

### Description
Enables the Nirvana Engine to begin rendering.

### Signature
void NIRVANA_start()
```

--------------------------------

### Verify z88dk-zsdcc installation

Source: https://github.com/z88dk/z88dk/blob/master/doc/target/zx/01_GettingStarted.md

Check the version and availability of the z88dk-zsdcc compiler.

```sh
>z88dk-zsdcc -v
 ZSDCC IS A MODIFICATION OF SDCC FOR Z88DK
 Build: 4.2.0 #13131 (Linux) Jan  5 2023
```

--------------------------------

### Verify zcc installation

Source: https://github.com/z88dk/z88dk/blob/master/doc/target/zx/01_GettingStarted.md

Check that the zcc frontend is accessible in the environment.

```sh
>zcc
 zcc - Frontend for the z88dk Cross-C Compiler
 <pages and pages of help and options snipped>
```

--------------------------------

### Configure Startup Routine

Source: https://github.com/z88dk/z88dk/wiki/Library-in-Depth

The CRT selection logic based on the startup command line option.

```asm
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; SELECT CRT0 FROM -STARTUP=N COMMANDLINE OPTION ;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

INCLUDE "zcc_opt.def"

IFNDEF startup

   ; startup undefined so select a default
   
   defc startup = 0

ENDIF


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; user supplied crt ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

IF startup = -1

   INCLUDE "crt.asm"

ENDIF

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; ram model ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

IF startup = 0

   ; generic temp startup

   IFNDEF __CRTDEF
   
      defc __CRTDEF = 0
   
   ENDIF
   
   IFNDEF __MMAP
   
      defc __MMAP = 0
   
   ENDIF

   INCLUDE "startup/temp_crt_0.asm"

ENDIF
```

--------------------------------

### im2_install_isr

Source: https://github.com/z88dk/z88dk/wiki/z80

Installs an interrupt service routine on a specific IM2 vector.

```APIDOC
void *im2_install_isr(uint16_t vector, void (*isr)(void))
```

--------------------------------

### im2_InstallISR

Source: https://github.com/z88dk/z88dk/wiki/interrupts

Installs an interrupt service routine on a specific interrupt vector.

```APIDOC
## void *im2_InstallISR(unsigned char vector, void *isr)

### Description
Installs an interrupt service routine on a specific interrupt vector. Returns the ISR formerly registered on the vector.

### Parameters
- **vector** (unsigned char) - Required - Peripheral id supplied by the interrupting device (0-255).
- **isr** (void *) - Required - Interrupt service routine to be installed.
```

--------------------------------

### Initialize and Use Bifrost in ZX BASIC

Source: https://github.com/z88dk/z88dk/blob/master/libsrc/target/zx/bifrost_h/readme.txt

Include the library and use the provided sub-routines for tile management in Boriel's ZX BASIC.

```BASIC
#include "bifrost.bas"

BIFROSTstart()
...
BIFROSTsetTile(row, column, index)
```

--------------------------------

### Compile the project

Source: https://github.com/z88dk/z88dk/blob/master/examples/zxn/classic/level2_sprites/readme.md

Use the provided makefile to build the project.

```text
Use the makefile
```

--------------------------------

### Install Perl Modules

Source: https://github.com/z88dk/z88dk/wiki/installation

Required Perl modules for the build process.

```bash
cpanm --local-lib=~/perl5 App::Prove CPU::Z80::Assembler Data::Dump Data::HexDump Test::HexDifferences File::Path List::Uniq Modern::Perl Object::Tiny::RW Regexp::Common Test::Harness Text::Diff Text::Table YAML::Tiny
eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)
```

--------------------------------

### List supported -clib options

Source: https://github.com/z88dk/z88dk/wiki/Platform--LM80C

Command to display available firmware versions and library configurations for the target.

```bash
zcc +lm80c
```

--------------------------------

### Get list count

Source: https://github.com/z88dk/z88dk/wiki/Classic-adt

Returns the number of items currently in the list.

```c
unsigned int adt_ListCount(struct adt_List *list); 
// list = pointer to list handle
```

--------------------------------

### Compile with zcc for Spectrum

Source: https://github.com/z88dk/z88dk/wiki/programs

Example command line to compile the program while linking the custom library.

```shell
zcc +zxansi -lndos -lssmain -lm -lmalloc -create-app baslib.c
```

--------------------------------

### Resume A* Search

Source: https://github.com/z88dk/z88dk/wiki/algorithm

Continues a search previously started by astar_Search or astar_SearchResume.

```c
struct astar_path *astar_SearchResume(struct astar_path *p);
// p = path to begin investigation with; returned by a previous call to astar_Search() or astar_SearchResume()
//     if 0, further paths to investigate are retrieved from the priority queue.
```
Tokens:
Raw