Zeal Development Environment (ZDE) is the build and tooling environment for working on software for the Zeal 8-bit Computer. It provides a consistent containerized toolchain, project scaffolding, dependency management, image staging utilities, and optional host-mode activation.

Detailed command documentation now lives in docs/README.md.

• What ZDE Provides
• Getting Started
• Linux
• macOS
• Windows (WSL2)
• Quick Command Overview
• Requirements And Dependencies
• Upgrading from a Previous Version

• A container-based development environment for Zeal projects.
• A host wrapper script (./zde) for launching builds, tools, and long-lived services.
• Optional host-mode activation for running against the ZDE-managed toolchain without entering the container.
• Project templates for quickly starting new Zeal applications.
• Dependency management for required and optional tool repositories.

Clone the repository, change into it, and run the initial update:

git clone https://github.com/zoul0813/zeal-dev-environment.git
cd zeal-dev-environment
./zde update

If you want to run zde from anywhere, add the repository root to your PATH:

export ZDE_PATH="/path/to/zeal-dev-environment"
export PATH="$ZDE_PATH:$PATH"

• Install git.
• Install a supported container runtime.
• Ensure your user can run the selected container runtime.
• Clone the repository and run ./zde update.

• Install git.
• Install a container runtime. Docker Desktop and Podman are both supported options.
• Start the container runtime before running ZDE commands.
• Clone the repository and run ./zde update.

Use ZDE from a Linux shell inside WSL2, not from PowerShell.

• Install Git inside WSL.
• Install WSL2.
• Install a container runtime inside WSL2. Docker Desktop with WSL2 integration and Podman are both supported options.
• Clone the repository from the WSL shell.
• Run ./zde update from the WSL shell.

Use zde COMMAND [args].

Host wrapper and service commands:

• zde -v / zde --version: print the current ZDE version and configured ZDE image reference.
• zde update: update the local ZDE checkout, pull the container image, and run ZDE sync tasks.
• zde -i: open an interactive shell inside the ZDE container.
• zde activate: emit shell exports for host mode.
• zde emulator: start, stop, or query the Zeal Web Emulator service.
• zde playground: start, stop, or query the Zeal Playground service.

Core ZDE commands:

• zde deps: manage required and optional dependencies.
• zde create: scaffold a new project from a template.
• zde make: run make in the current project.
• zde cmake: configure and build CMake projects.
• zde image: manage EEPROM, CF, TF, and romdisk staging and image files.
• zde config: inspect and change persistent ZDE config.
• zde kernel: build the Zeal kernel with predefined or user config.
• zde tui: launch the optional terminal UI.
• zde test: run ZDE Python unit tests.

For the full command map, runtime configuration, and per-command reference pages, see docs/README.md.

Base requirements:

• git
• a supported container runtime
• a working container runtime with compose support

ZDE dependency model:

• Required dependencies are installed and synchronized by zde update.
• Optional dependencies are installed on demand with zde deps install <id-or-alias>.
• Installed dependency state is tracked in ~/.zeal8bit/deps-lock.yml.
• Generated dependency environment exports are written to ~/.zeal8bit/deps.env.
• The state directory defaults to ~/.zeal8bit and can be overridden by setting ZDE_USER_PATH in your environment before running zde.

Host mode:

• You can activate ZDE without entering the container by running eval "$(zde activate)" or sourcing bin/activate.
• Host mode assumes you already have the required native tooling available on your machine.

Project-specific prerequisites may still apply depending on which Zeal project, SDK, or optional dependency you are using.

If you are on an older ZDE version, run zde update twice — the first run pulls the latest ZDE code, and the second applies any updated sync tasks against the new version:

./zde update
./zde update

ZDE will automatically migrate required (core) dependencies. Non-core optional dependencies are no longer tracked as submodules — they can be reinstalled after upgrading with zde deps install <id-or-alias>.