Getting started

This section takes a new contributor from a fresh checkout to a running development system.

This guide assumes GNU/Linux on either an x86_64 or an ARM64 (aarch64) machine. The automatic system dependency installer supports Debian and Arch Linux. Other distributions may work, but their system dependencies must be installed manually.

Read the chapters in order on a first setup:

Basic setup

Clone the repository, enter its root, and initialize the development environment:

source ./init_environment.sh

The initialization script adds scripts/bin to PATH, checks the native Rust build dependencies, and installs the pinned frontend and RedisJSON artifacts. Review each installation prompt before accepting it.

Building the system

After sourcing init_environment.sh, build the runtime modules from the repository root:

build_all_debug.sh  # builds all runtime modules
build_core.sh       # builds the gui, control, and peripheral-manager modules
build_gui_debug.sh  # builds just the gui, this includes building the gui's frontend assets
build_peripheral_debug.sh # builds just peripheral-manager, including dummy peripherals
build_control_debug.sh    # builds just the control module

Release and packaging builds are covered in Deployment.

Running the system

The complete debug system can be built and started from the repository root. To avoid a rebuild, supply any of these commands with --no-build:

run_system_debug.sh # builds all modules, then runs the system module
run_core.sh         # builds and runs the control, peripheral-manager, and GUI modules
run_gui_debug.sh
run_peripheral_debug.sh
run_control_debug.sh

Each run script starts Valkey with the Bio-C and RedisJSON modules and waits for initialization. run_system_debug.sh then launches the runtime modules selected in the System configuration. The other scripts launch the module or fixed group named by the script.

Development workflow

Use the watch scripts for short edit-build-run cycles. These scripts require watchexec, which is not installed by init_environment.sh. They use it to watch for source file changes in the bio-c directory:

watch_system.sh
watch_core.sh
watch_gui.sh
watch_control.sh
watch_peripheral.sh

Run the workspace checks before submitting a change:

run_merge_check.sh

The merge check runs the workspace tests, all Clippy lints, and cargo fmt --check. It uses an existing development Valkey instance when one is available. Otherwise, it starts one for the tests and stops it when the checks finish.