Skip to main content

SDK Setup and Usage

The Spectranext SDK provides everything you need to develop programs for the Spectranext cartridge (and for original Spectranet). It includes the z88dk toolchain, CMake integration, and SPX tools for file transfer.

Installation​

The easiest option is to use Homebrew:

brew tap spectranext/homebrew-spectranext
brew install spectranext-sdk

Load the SDK environment in your shell:

source "/opt/homebrew/opt/spectranext-sdk/libexec/source.sh"

Or add it to your shell profile:

echo 'source "/opt/homebrew/opt/spectranext-sdk/libexec/source.sh"' >> ~/.zshrc

Configure CMake projects with the z88dk toolchain:

cmake -S . -B build \
-DCMAKE_TOOLCHAIN_FILE="/opt/homebrew/opt/spectranext-sdk/libexec/z88dk/support/cmake/Toolchain-zcc.cmake"

(or manually) clone and install the SDK:

git clone https://github.com/spectranext/spectranext-sdk
cd spectranext-sdk
./install.sh

This will:

  • Download and install z88dk toolchain
  • Create a Python virtual environment
  • Install required Python dependencies

Setup​

If you installed with Homebrew, source the SDK environment from the Homebrew prefix:

source "/opt/homebrew/opt/spectranext-sdk/libexec/source.sh"

Or add it to your shell profile:

echo 'source "/opt/homebrew/opt/spectranext-sdk/libexec/source.sh"' >> ~/.zshrc

For CMake toolchain configuration, Homebrew installs the z88dk toolchain file at:

/opt/homebrew/opt/spectranext-sdk/libexec/z88dk/support/cmake/Toolchain-zcc.cmake

If you installed manually, source the SDK environment from your checkout:

source /path/to/spectranext-sdk/source.sh

You can also select source.sh as your environment file in CLion toolchain settings.

Setting Up a CMake Project​

Create a CMakeLists.txt file in your project directory:

cmake_minimum_required(VERSION 3.16)

# Import Spectranext SDK - MUST be before project()
include($ENV{SPECTRANEXT_SDK_PATH}/cmake/spectranext_sdk_import.cmake)
spectranext_sdk_init()

project(idetest C)

add_executable(idetest main.c)

target_compile_options(idetest PUBLIC -debug)

target_link_libraries(idetest PUBLIC -lndos -llibspectranet -llibsocket)

target_link_options(idetest PUBLIC -debug -create-app)

# Set boot basic program (optional)
# This creates a boot.zx file that will be uploaded before your program
spectranext_set_boot("
10 %tapein \"idetest.tap\"
20 LOAD \"\"
")

# Add convenience targets (upload_bin, upload_tap, etc.)
spectranext_add_extra_outputs(idetest)

If source.sh is not sourced then SPECTRANEXT_SDK_PATH must be explicitly provided.

Important Notes​

  • spectranext_sdk_init() must be called before project() - This is required because the SDK sets up the CMake toolchain, which must be configured before the project is defined.

Boot BASIC Program​

The spectranext_set_boot() function allows you to create a boot BASIC program that will be automatically uploaded before your main program. This is useful for creating loader programs or initialization code.

Usage:

spectranext_set_boot("
10 PRINT \"Booting...\"
20 CLEAR 32767
30 %aload \"myprogram.bin\" CODE 32768
40 RANDOMIZE USR 32768
")

The function:

  • Creates boot.bas in the CMake binary directory
  • Compiles it to boot.zx using zmakebas (starting at line 10)
  • Creates an upload_boot target that builds and uploads boot.zx
  • When spectranext_add_extra_outputs() is called, upload_bin and upload_tap targets will automatically depend on upload_boot if it exists

Example boot program:

spectranext_set_boot("
10 REM Boot loader
20 %tapein \"myprogram.tap\"
30 LOAD \"\"
40 REM Program will auto-run after loading
")

The boot program is compiled with zmakebas -o boot.zx -a 10 boot.bas, which means it starts at line 10. Make sure your BASIC code includes line numbers or uses labels if you're using zmakebas label mode.

Available Targets​

If spectranext_set_boot() was called, the following additional target is available:

  • upload_boot - Build and upload boot.zx file for your BASIC loader program.

After calling spectranext_add_extra_outputs(project_name), the following targets are available:

  • project_name_upload_bin - Build and upload .bin file
  • project_name_upload_tap - Build and upload .tap file
  • project_name_bin_autoboot - Build, upload .bin, and configure autoboot
  • project_name_tap_autoboot - Build, upload .tap, and configure autoboot

Building and Uploading​

# Configure CMake (if not already done)
cmake -B build

# Build and upload .bin file
cmake --build build --target idetest_upload_bin

# Build and upload .tap file
cmake --build build --target idetest_upload_tap

# Build, upload, and configure autoboot
cmake --build build --target idetest_bin_autoboot

SDK Components​

  • z88dk - Z80 cross-compiler toolchain
  • CMake Integration - Automatic toolchain setup and convenience targets
  • Headers - Spectranext API headers in include/
  • Libraries - Pre-built libraries in clibs/

Environment Variables​

The SDK sets the following environment variables:

  • SPECTRANEXT_SDK_PATH - Path to the SDK root directory
  • SPECTRANEXT_TOOLCHAIN - Path to the CMake toolchain file
  • SPECTRANEXT_INCLUDE_DIR - Path to SDK include directory
  • ZCCTARGET - z88dk target (default: zx)
  • SPX_SDK_DIR - SDK directory for SPX tools
  • ZCCCFG - z88dk configuration path
  • PATH - Includes z88dk/bin

Development Workflow​

Example Project Structure​

my-project/
├── CMakeLists.txt
├── main.c
└── build/          # CMake build directory

Complete Example​

CMakeLists.txt:

cmake_minimum_required(VERSION 3.16)

include($ENV{SPECTRANEXT_SDK_PATH}/cmake/spectranext_sdk_import.cmake)
spectranext_sdk_init()

project(hello C)

add_executable(hello main.c)

target_compile_options(hello PUBLIC -debug)
target_link_libraries(hello PUBLIC -lndos -llibspectranet)
target_link_options(hello PUBLIC -debug -create-app)

# Optional: Set boot BASIC program
spectranext_set_boot("
10 PRINT \"Loading hello...\"
20 %tapein \"hello.tap\"
30 LOAD \"\"
")

spectranext_add_extra_outputs(hello)

main.c:

#include <stdio.h>
#include <spectranet.h>

int main() {
    printf("Hello from Spectranext!\n");
    return 0;
}

Build and upload:

cmake -B build
cmake --build build --target hello_upload_bin

Next Steps​