v0.5.0

Full Changelog: v0.4.0...v0.5.0

v0.4.0

v4_cli v0.4.0 - Debugging Meta-Commands

This release adds powerful debugging meta-commands to the v4_cli REPL, enabling real-time VM introspection over the V4-link serial protocol.

New Features

Debugging Meta-Commands

• .stack - Display data stack and return stack contents

  • Shows stack depth and all values
  • Displays values in both hex and decimal

• .rstack - Display return stack with call trace

  • Useful for debugging nested word calls
  • Shows execution flow through return addresses

• .dump [addr] [len] - Hexdump memory at specified address

  • Default: 256 bytes from address 0
  • 16-byte rows with hex and ASCII representation
  • Essential for inspecting VM memory state

• .see <word_idx> - Show word bytecode disassembly

  • Displays word name and bytecode length
  • Shows raw bytecode in hexadecimal
  • Helps understand compiled word structure

V4-link Protocol Extensions

Added three new query commands to enable remote debugging:

• QueryStack (0x30) - Query stack state from device
• QueryMemory (0x40) - Query memory dump from device
• QueryWord (0x50) - Query word information from device

All query responses include structured data payloads for parsing on the host.

Internal Improvements

• Enhanced Response struct with data field for query payloads
• Added serial protocol methods: query_stack(), query_memory(), query_word()
• Added V4Error::Cli variant for user input validation
• Updated .help command to document new debugging features

Example Usage

```forth
v4> : SQUARE DUP * ;
ok

v4> 5 SQUARE
ok

v4> .stack
Data Stack (depth: 1 / 256):
[0]: 0x00000019 (25)

Return Stack (depth: 0 / 64):

v4> .dump 0 64
Memory dump at 0x00000000 (64 bytes):

00000000 A5 00 10 20 42 00 00 00 00 00 00 00 00 00 00 00 |... B...........|
00000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
...
```

Breaking Changes

None - this release is fully backward compatible.

Requirements

• V4-link v0.3.0+ with query command support
• V4-runtime v0.3.0+ or compatible firmware

Full Changelog: v0.3.0...v0.4.0

v0.3.0: Forth Source File Execution

What's New in v0.3.0

New Commands

v4 exec - Execute Forth Source Files

Execute Forth source files (.fs) directly on your device:

v4 exec examples/nanoc6/led.fs -p /dev/ttyACM0

• Compiles Forth source using V4-front
• Sends word definitions to device
• Registers words in VM for later use

v4 exec --repl - Execute and Enter REPL

Execute a file and immediately drop into REPL with the compiler context preserved:

v4 exec examples/nanoc6/led.fs -p /dev/ttyACM0 --repl
# Now you can call led-on, led-off, led-blink, etc.

v4 repl --no-reset - Connect Without Reset

Connect to an already-running VM without resetting:

v4 repl -p /dev/ttyACM0 --no-reset

Useful for preserving existing word definitions on the device.

Example Library

Added examples/nanoc6/led.fs - LED control library for NanoC6 (ESP32-C6):

• led-on - Turn LED on
• led-off - Turn LED off
• led-blink - Blink LED (500ms on/off)
• led-blink-fast - Fast blink (100ms on/off)
• led-blink-slow - Slow blink (1000ms on/off)

Installation

# Linux/macOS
curl -LO https://github.com/V4-project/v4_cli/releases/download/v0.3.0/v4-linux-x86_64
chmod +x v4-linux-x86_64
sudo mv v4-linux-x86_64 /usr/local/bin/v4

# Or use cargo
cargo install v4_cli

See CHANGELOG.md for full details.

v0.2.0

What's New in v0.2.0

✨ New Features

• REPL Command: Interactive Forth execution environment for V4 VM
  • Integrated libv4repl with Rust FFI bindings
  • Rustyline-based command-line interface with history support
  • Real-time Forth code execution and evaluation

🏗️ Build System Improvements

• Cross-Platform Support:
  • ✅ Linux x86_64
  • ✅ Linux ARM64 (cross-compilation)
  • ✅ macOS x86_64
  • ✅ macOS ARM64
  • ✅ Windows x86_64
• Integrated V4 and V4-front libraries via CMake
• Vendored V4 libraries for standalone builds
• Comprehensive CI/CD workflows for automated releases

🐛 Bug Fixes

• Fixed variable-length response frame handling in serial communication
• Improved cross-compilation support with proper toolchain configuration
• Fixed Windows CMake build profile selection
• Resolved ARM64 Linux strip issues
• Updated dependency licenses and configurations

📦 Binary Downloads

Pre-built binaries are available for all supported platforms:

• v4-linux-amd64.tar.gz - Linux x86_64
• v4-linux-arm64.tar.gz - Linux ARM64
• v4-macos-amd64.tar.gz - macOS x86_64
• v4-macos-arm64.tar.gz - macOS ARM64
• v4-windows-amd64.exe.zip - Windows x86_64

🔗 Links

Full Changelog: v0.1.0...v0.2.0

---

🤖 Generated with Claude Code

v0.1.0 - Initial Release

🎉 v0.1.0 - Initial Release

First stable release of v4 CLI tool for V4 VM bytecode deployment over V4-link protocol.

✨ Features

• v4 push - Deploy bytecode to devices with progress bar
• v4 ping - Check device connection
• v4 reset - Reset VM state
• Configurable timeout (default: 5 seconds)
• --detach flag for fire-and-forget mode
• 8 LED example files (.v4b) for testing

🔧 Technical Details

• V4-link protocol implementation (CRC-8, frame encoding/decoding)
• Support for ESP32-C6, CH32V203, and other V4-enabled devices
• Binary size: 733KB (stripped)
• Default baud rate: 115200
• Maximum payload: 512 bytes
• 13 unit tests (all passing)

📦 Installation

cargo install --git https://github.com/V4-project/v4_cli.git

Or build from source:

git clone https://github.com/V4-project/v4_cli.git
cd v4_cli
cargo build --release

🚀 Quick Start

# Check device connection
v4 ping --port /dev/ttyACM0

# Deploy bytecode
v4 push examples/led_blink.v4b --port /dev/ttyACM0

# Reset VM
v4 reset --port /dev/ttyACM0

📝 Examples

The repository includes 8 LED examples:

• led_on.v4b / led_off.v4b - Basic control
• led_blink.v4b - Basic blinking
• led_fast/medium/slow.v4b - Speed variations
• led_sos.v4b - Morse code pattern
• led_toggle.v4b - Toggle state

See examples/README.md for details.