Zumbra 0.14.5 includes the native-backend performance/runtime stabilization previously validated for Z23, while 0.14.3 remains the prior stable baseline. Zumbra 0.14.5 includes a local native-backend patch for synchronous struct method calls used as immediate call targets. This avoids materializing bound method values inside tight native loops while preserving async method semantics through the normal z_call path. See docs/releases/0.14.3-native-method-hotloop-performance.md.
⚙️ ZUMBRA is a simple, fun, and expressive programming language made for learning, experimenting, and enjoying the beauty of code.
🖥️ Official website
This readme will no longer be updated, all updates will be on the website
✨ What is ZUMBRA?
Zumbra is a lightweight, expressive programming language designed and built entirely from scratch. It features a fully custom lexer, parser, compiler, and virtual machine, providing an educational yet powerful platform to explore language design concepts.
Zumbra supports basic types like integers, floats, booleans, and strings, control flow structures like if and for, and logical operators with proper short-circuit evaluation.
Designed for clarity, simplicity, and extensibility, Zumbra is the perfect playground for learning how modern programming languages work internally.
The rebuild now follows a clear direction: systems, emulation, and game development without abandoning Zumbra's simplicity. See the Portuguese design and feature documentation in docs/pt-BR/.
Zumbra 0.14.5 stabilizes native runtime memory, statement-if checking, and release performance flags for long-running desktop/emulator workloads. Zumbra 0.14.3 adds official real-time desktop/media APIs for RGBA framebuffer presentation, PCM audio queues, keyboard/gamepad state, VSync, process arguments and Unix timestamps. Game and emulator projects no longer need project-local C bridges or extern "C" declarations. See docs/releases/0.14.3.md; docs/releases/0.14.3-native-hotloop-performance.md.
Zumbra 0.14.2 adds native C11 support for the panic builtin. Native programs can now keep defensive validation and assertion helpers without being rejected by nativec; a triggered panic writes a diagnostic to stderr and exits with a non-zero status. This patch closes the native-build blocker found by the Z19 NES/Famicom foundation. See docs/releases/0.14.2.md.
Zumbra 0.14.1 fixes boolean negation and equality for fixed-width integer comparisons in the evaluator and VM. This patch was identified while validating the Z19 NES/Famicom foundation. See docs/releases/0.14.1.md.
Zumbra 0.14.0 completes Z18 as one stable tooling release. It adds the canonical formatter, official linter, API documentation generator, project manager, compiler profiler, structured diagnostics, a built-in Language Server Protocol implementation and an official VS Code extension. See docs/pt-BR/tooling-z18.md and docs/releases/0.14.0.md.
Zumbra 0.13.0 completes Z17 systems programming in one stable release. It adds typed explicit memory, pointer indexing, ownership and borrowing, arenas, memory diagnostics, native ABI layout, mapped files, shared memory, volatile/atomic operations, page protection, dynamic libraries and calls, opt-in raw syscalls, profiling, sanitizer builds and conditional C11 runtime emission across the evaluator, VM, Clang and GCC. See docs/pt-BR/programacao-de-sistemas-z17.md.
Zumbra 0.12.12 restores native C11 scrollbar visibility when scrollbarAvoidContent reserves a gutter. The renderer now paints the thumb with the inherited viewport clip instead of clipping it to content_bounds, so reserved right-side space is always visibly occupied by the scrollbar. See docs/releases/0.12.12.md.
Zumbra 0.12.11 fixes a native C11 shutdown double-free caused by releasing temporary fitted text with free() after allocating it through the runtime-owned z_alloc() registry. Temporary paint strings now use a matching system allocation and are covered by an AddressSanitizer regression test. See docs/releases/0.12.11.md.
Zumbra 0.12.10 fixes nested clipping for buttons and editable controls in scrolling layouts. Partially visible button labels remain inside the scroll viewport, and input/select text cannot overlap adjacent controls. See docs/releases/0.12.10.md.
Zumbra 0.12.9 hardens native C11 UI rendering performance with persistent text/image texture caches, cached modal backdrops and redundant mouse-motion repaint suppression. Packaged desktop applications no longer rebuild every text texture, reload every cover image or recompute blur on each interaction. See docs/releases/0.12.9.md.
Current systems features include readable bitwise operators, fixed-width integers (u8 through u64, i8 through i64), mutable indexes, compact byte memory, typed integer arrays, zero-copy mutable slices, binary file I/O, endian-aware integer access, buffer copying/comparison, SHA-256 hashing, immutable constants, type aliases, structs with methods, enums, and match. Z6 adds a canonical typed pipeline with HIR and MIR. Z7 adds a C11 backend that consumes optimized MIR and produces standalone native executables with Clang or GCC. Z8 adds isolated modules with pub exports, module graph inspection, typed C FFI, opaque pointers, synchronous callbacks, native linking, and a conservative C-header binding generator. Z8.1 adds contextual callback inference, so callback parameters and returns become concrete in type analysis, HIR, MIR, and native builds without extra annotations. Z9 adds real tasks, spawn, async/await, inferred typed channels, timeouts, cooperative cancellation, mutexes, wait groups, semaphores, and atomics across the VM and pthread-based native runtime. Z9.1 extends contextual inference to ordinary calls and spawn, so user functions, methods, Channel<T>, Task<T>, atomics, and return values become concrete without annotations. Z10 adds local-first TCP, UDP, IPv4/IPv6 DNS, TLS 1.2+, common byte streams, accept/connect/read timeouts, half-close, keepalive, and conditional native linking through POSIX sockets and OpenSSL. Z11 adds typed HTTP/1.1 applications, routing, middleware, JSON, cookies, stateless JWT sessions, multipart uploads, static files, gzip, streaming/SSE, HTTP clients, graceful shutdown and RFC 6455 WebSockets/WSS across the VM and native runtime. Z12 completes the data layer with advanced SQLite, PostgreSQL, Redis, safe SQL parameters, migrations, streaming rows, persistent sessions, typed configuration, structured logs, metrics, tracing, rate limiting, JSON files, and versioned binary serialization across the VM and native backend. Z13 adds a Linux-first desktop runtime with SDL3 windows, lifecycle and events, multiple windows, High DPI, clipboard, drag and drop, pickers, notifications, tray, shortcuts, system paths, processes, and a deterministic headless backend across the evaluator, VM, Clang, and GCC. Z14 adds a retained-mode GUI toolkit with layouts, controls, tables, lists, trees, tabs, menus, modals, tooltips, progress, images, canvas, themes, reactive state, bidirectional data binding, custom components, keyboard navigation and accessibility across the VM and native backend. Z17 adds managed ptr<T> values, explicit allocation and ownership, arenas, mapped/shared memory, volatile and atomic access, native page controls, dynamic loading/calls, raw Linux syscalls, profiling and sanitizer-enabled native builds. Z18 adds the canonical formatter, linter, API documentation, project workflows, compiler profiling, structured diagnostics, an embedded LSP and official VS Code integration. See docs/pt-BR/modulos-abi-e-ffi.md, docs/pt-BR/inferencia-contextual-de-callbacks.md, docs/pt-BR/concorrencia-e-tarefas.md, docs/pt-BR/inferencia-contextual-de-chamadas.md, and docs/pt-BR/rede-tcp-udp-dns-tls.md, and docs/pt-BR/dados-e-persistencia-z12.md, and docs/pt-BR/runtime-desktop-z13.md, and docs/pt-BR/toolkit-interface-grafica-z14.md, and docs/pt-BR/programacao-de-sistemas-z17.md.
🛠 Code_examples
📥 How to Run
You can execute .zum code using the compiled ZUMBRA binary on different platforms.
🖥️ Windows
-
Download the
zumbra.exefile for Windows from the GitHub Release. -
Open a command prompt or PowerShell window and run the following command:
zumbra.exe myscript.zum
🐧Linux
-
Download the
zumbra-linuxfile for Linux from the GitHub Release. -
Make the file executable by running:
chmod +x zumbra-linux
-
Run the script with the following command in your terminal:
./zumbra-linux myscript.zum
🔎 Validation and IR:
zumbra check app.zum
zumbra modules app.zum
zumbra ir app.zum hir
zumbra ir app.zum optimized🧰 Z18 tooling:
zumbra fmt --check src tests
zumbra lint --deny-warnings src tests
zumbra doc src -o docs/api.md
zumbra project init --kind library "My Library"
zumbra project check
zumbra profile --runs 20 app.zum
zumbra lsp --stdioThe official VS Code extension is in editors/vscode. It uses the LSP embedded in the Zumbra CLI and provides diagnostics, formatting, completion, hover and document symbols.
🚀 Native build:
zumbra build app.zum
zumbra build --release app.zum
zumbra build --emit-c app.zum
./build/appNative builds require Clang or GCC. Use --compiler, CC, and -o to control the toolchain and output. Z8 also supports --link, --include, --library-dir, and -l for native dependencies. Z17 adds --sanitize address,undefined, --sanitize thread, and --sanitize leak for native diagnostics.
🧩 Modules and C bindings:
zumbra modules app.zum
zumbra bind-c --pub --link ../native/library.c -o bindings/library.zum native/library.h
zumbra build --release app.zum🧠 Contextual callbacks:
extern "C" {
fct apply(value: i32, cb: callback(i32) -> i32) -> i32;
}
var double << fct(value) { value * 2i32; };
unsafe { show(apply(21i32, double)); }
The callback is inferred as fct(i32) -> i32 and remains concrete through HIR, MIR, and native code generation.
🧵 Tasks and channels:
fct calculate(value) { value * value; }
var task << spawn calculate(6);
show(await task);
var messages << channel(4);
send(messages, "ready");
show(receive(messages));
closeChannel(messages);
Native builds use pthreads and C11 atomics. Ordinary arrays, dictionaries, structs, and buffers stay lightweight; protect shared mutation with channels, mutexes, or atomics.
🔎 Contextual call inference:
fct square(value) { value * value; }
var task << spawn square(6);
The first concrete call specializes square as fct(int) -> int, so the task becomes Task<int>. The same propagation applies to methods, channels, atomics, and ordinary calls. A function remains monomorphic: reusing it later with an incompatible argument type is rejected.
⚡ Additional Notes:
-
Make sure the ZUMBRA binary file (
zumbra-linux,zumbra.exe) has execution permissions on your system. -
For Windows, just run the command without additional configuration.
-
For Linux, use the
chmodcommand to make the file executable.
📎 VS Code Integration
-
We provide a ZUMBRA VS Code Extension for syntax highlighting and
.zumfile support. -
Includes keyword coloring, strings, and built-in function recognition.
🤝 Contributing
We welcome contributions! Please read our Contributing Guide and Code of Conduct before submitting pull requests.
👨💻 Creator
Joselucasapp
Bringing ZUMBRA to life with love, logic, and a hint of rebellion.
import "std/net.zum" as net;
var listener << net.listen("127.0.0.1", 8080);
var connection << net.accept(listener);
var data << net.read(connection, 4096);
net.writeBytes(connection, data);
net.closeStream(connection);
The repository examples use a relative import (../../std/net.zum) because package-name imports are reserved for the future package manager. TCP, UDP, DNS and TLS are available in the evaluator, VM and native backend. Native builds compile network support only when the MIR references a network builtin, and OpenSSL is linked only for TLS programs.
import "std/http.zum" as http;
var api << http.app();
api.get("/health", fct(request, response) {
request;
response;
http.json(200, {"status": "ok"});
});
var server << api.listen("127.0.0.1", 8080);
Z11 provides typed HTTP applications, requests and responses; routing, middleware, CORS, cookies, stateless JWT sessions, JSON, multipart uploads, static files, gzip, chunked streams, SSE, HTTP clients, graceful shutdown, WebSockets and WSS. It runs in the evaluator, VM and MIR-based native backend. HTTP reuses Z10 streams and TLS, and native dependencies are enabled only when referenced by the program. See docs/pt-BR/http-websockets-e-apis.md.
Z11.1 restores the shared Go/Zumbra value conversion layer used by PostgreSQL, Supabase and platform integrations. Nested JSON values, database driver values, byte buffers and fixed-width integers now convert recursively without depending on private HTTP helpers. See docs/pt-BR/correcao-conversores-plataforma-z11-1.md.
import "std/database.zum" as database;
var db << database.memory();
database.migrate(db, [
{"version": 1, "name": "users", "sql": "CREATE TABLE users(id INTEGER PRIMARY KEY, name TEXT NOT NULL)"}
]);
database.exec(db, "INSERT INTO users(name) VALUES (:name)", {"name": "Lucas"});
show(database.queryOne(db, "SELECT name FROM users", {})["name"]);
database.close(db);
Z12 adds advanced SQLite, PostgreSQL, Redis, persistent sessions, typed configuration, structured observability, rate limiting, atomic JSON files and versioned binary serialization. Native dependencies are enabled and linked only when referenced. See docs/pt-BR/dados-e-persistencia-z12.md.
import "std/desktop.zum" as desktop;
var app << desktop.app({
"name": "Zumbra Desktop",
"identifier": "dev.zumbra.desktop"
});
var window << app.window({
"title": "Hello",
"width": 900,
"height": 600,
"resizable": true,
"highDPI": true
});
app.shortcut("Ctrl+Q", fct(event) { event; app.quit(); });
app.run();
app.close();
Z13 provides a Linux-first SDL3 backend and a deterministic headless backend for CI. It includes lifecycle, multiple windows, event dispatch, High DPI, clipboard, drop events, file/folder pickers, notifications, tray, shortcuts, XDG paths, external opening, and process management. See docs/pt-BR/runtime-desktop-z13.md.
Zumbra 0.7.0 completes Z13 and establishes the baseline for Z14 GUI toolkit development. See docs/releases/0.7.0.md.
import "std/desktop.zum" as desktop;
import "std/ui.zum" as ui;
var app << desktop.app({"name": "Zumbra GUI"});
var window << app.window({"title": "Hello", "width": 900, "height": 650});
var message << ui.state("Ready");
var label << ui.text("");
ui.bind(label, "text", message);
var root << ui.columnWith({"padding": 20, "gap": 12}, [
ui.textWith("Zumbra GUI Toolkit", {"fontSize": 20}),
ui.input({"placeholder": "Project name"}),
ui.button("Save", fct(event) { event; ui.update(message, "Saved"); }),
label
]);
var context << ui.mount(app, window, root, {"theme": ui.theme("light")});
window.show();
app.run();
context.close();
app.close();
Z14 provides a retained component tree, deterministic row/column layout, controls, collections, overlays, canvas drawing, themes, reactive state, bidirectional binding, custom components, focus navigation and accessibility. The headless backend supports deterministic CI tests; the graphical backend renders through dynamically loaded SDL3 on Linux, Windows and macOS. See docs/pt-BR/toolkit-interface-grafica-z14.md, and docs/pt-BR/programacao-de-sistemas-z17.md.
Zumbra 0.8.1 completes Z14 and establishes the baseline for Z15 desktop distribution. See docs/releases/0.8.1.md.
Zumbra 0.5.1 widens the VM builtin index operand from 8 to 16 bits. This prevents overflow now that Z12.1 raises the builtin table above 255 entries and restores binary I/O parity between the evaluator and VM. See docs/pt-BR/correcao-indice-builtins-0.5.1.md.
zumbra app inspect --manifest zumbra.toml
zumbra app doctor --manifest zumbra.toml
zumbra app build --manifest zumbra.toml
zumbra app package --manifest zumbra.tomlZ15 adds one target-aware packaging command for Linux, Windows and macOS. It creates Linux bundles, .deb, AppDir/AppImage, Windows portable ZIP/NSIS installers, and macOS .app/ZIP bundles. Packages include platform metadata, icons, embedded assets, dependency audits, deterministic timestamps, SHA-256 checksums, update descriptors, optional signatures and optional debug symbols. See docs/pt-BR/distribuicao-desktop-z15.md.
Zumbra 0.10.4 completes the Z15 implementation and maintenance pass with Linux, Windows and macOS desktop/GUI runtime paths, valid AppStream metadata, strict external-tool precedence, reproducible packages, and repository cleanup. See docs/releases/0.10.4.md.
AppImage tooling is external and is never stored in the repository. Install it in the Zumbra cache with:
scripts/setup-appimage-tools.shGenerated binaries, native C output, package directories, AppImages, installers, downloaded toolchains, profiles, and coverage files are not source code and must not be committed.
scripts/clean-generated.sh
scripts/clean-generated.sh --local-tools
scripts/check-repository-hygiene.shRelease packages belong in the release service or CI artifacts, not in the Git tree. The source archive should contain only language sources, tests, documentation, examples, and small public assets. See docs/pt-BR/higiene-do-repositorio.md.
The first official product built with Zumbra is maintained in the separate zumbra-game-collection repository. It is a local SQLite desktop application for cataloging, searching, sorting, editing, and deleting games from a physical or digital collection.
Zumbra 0.11.0 adds UI target identity (targetId and targetKind) and native code-generation fixes required by dynamic database-backed component lists. See docs/pt-BR/aplicativo-referencia-z16.md and docs/releases/0.11.0.md.
Zumbra 0.11.1 enables SDL3 text input only while an editable UI control is focused, restoring real keyboard editing for desktop input and textarea components. See docs/releases/0.11.1.md.
Zumbra 0.11.2 corrects retained UI layout alignment, adds clipped vertical scrolling for overflowing rows, columns and containers, and hardens native C11 generation for dynamically typed string literals and discarded control-flow results. See docs/releases/0.11.2.md.
Zumbra 0.11.3 restricts scrollbar rendering to nodes that explicitly enable vertical overflow, eliminating stray scrollbar fragments on labels, cards, buttons and ordinary containers. See docs/pt-BR/correcao-scrollbars-0.11.3.md.
Zumbra 0.12.1 fecha a fundação do primeiro aplicativo desktop oficial. A versão adiciona operações recuperáveis de JSON e CSV, backup/restauração/verificação de integridade SQLite, file picker em modo salvar, notificações não fatais, modais reais com isolamento de foco, acessibilidade e ponteiro, além de paridade nativa para mutação incremental de arrays. Veja docs/releases/0.12.1.md e docs/pt-BR/aplicativo-referencia-z16.md.
Zumbra 0.12.2 corrige alinhamento e overflow de texto em controles, substitui o v textual dos selects por um chevron, adiciona regiões de navegação recolhíveis em qualquer borda e inclui gráficos portáteis de pizza, barras e linhas, além de tabelas estruturadas. Veja docs/releases/0.12.2.md.
Zumbra 0.12.3 finaliza a interação visual do toolkit com cursores de sistema, caret visível, foco interno, ícones vetoriais, scrollbar sobreposta e remoção real de componentes invisíveis do fluxo de layout. Isso corrige o clipping dos botões de fechar, preserva margens simétricas e permite que sidebars ocultas liberem integralmente o espaço para o conteúdo principal. Veja docs/releases/0.12.3.md.
Navegações laterais preservam toda a altura disponível. Gráficos de linha mostram valores e rótulos categóricos nos backends SDL3 Go/cgo e C11. Veja docs/releases/0.12.4.md.
Inputs e textareas agora oferecem edição completa com caret UTF-8, seleção por teclado e mouse, navegação por setas/Home/End, movimentos por palavra, copiar, recortar, colar e seleção total. Scrollbars podem reservar um gutter interno sem atravessar controles, e imagens com fit: "cover" usam recorte proporcional. A auditoria de mensagens padrão também removeu o último diagnóstico hardcoded em português. Veja docs/releases/0.12.5.md.
O renderer SDL3 separa a camada normal da camada modal antes de desenhar scrollbars. Assim, barras da sidebar e de listas permanecem no fundo, são desfocadas com o restante do aplicativo e nunca atravessam diálogos. Veja docs/releases/0.12.6.md.
The C11 SDL3 backend now blocks on SDL_WaitEvent while idle instead of waking every 16 ms. It renders only dirty UI contexts, batches pending events, and uses an internal SDL wake event for events or state updates emitted by background threads. This removes the native packaged-app busy loop while preserving headless determinism. See docs/releases/0.12.7.md.
Buttons now intersect their local clip with the inherited scroll viewport, preventing labels from appearing above partially hidden cards. Inputs, textareas and selects clip placeholder/value rendering to their own bounds in both SDL3 backends, with native C11 ellipsis truncation for text that does not fit. See docs/releases/0.12.10.md.
The native C11 UI renderer now caches text textures, image textures and blurred modal backdrops. Mouse-motion events over the same control no longer force a full repaint. Renderer-bound resources are released before the SDL renderer is destroyed. See docs/releases/0.12.9.md.
The native C11 runtime now treats SDL_EVENT_POLL_SENTINEL as the end of a non-blocking poll cycle instead of dispatching it as an ordinary event. Event draining is bounded and the main loop returns to SDL_WaitEvent after queued events are processed. See docs/releases/0.12.8.md.
Temporary strings used for ellipsis and control text fitting now use malloc/free consistently instead of mixing z_alloc() with manual free(). This removes the double free or corruption (fasttop) abort that occurred when native desktop applications exited after rendering controls. See docs/releases/0.12.11.md.
The native C11 renderer now restores the inherited viewport clip before drawing vertical scrollbars. Scrollbars placed in a reserved scrollbarAvoidContent gutter are visible instead of being clipped by content_bounds, eliminating the unexplained right-side gap in packaged desktop applications. See docs/releases/0.12.12.md.
Z17 is delivered as one complete systems-programming milestone. Zumbra now provides typed explicit memory, pointer ownership and borrowing, arenas, native layout inspection, mapped/shared memory, atomics, memory protection, dynamic libraries, controlled raw syscalls, profiling and sanitizer builds with evaluator/VM/C11 parity. See docs/pt-BR/programacao-de-sistemas-z17.md and docs/releases/0.13.0.md.
The C11 backend now accepts and executes panic(value). The runtime converts the value to text, reports zumbra runtime error: panic: <message> on stderr, and terminates with a non-zero exit status. Panic paths inside imported modules and assertion helpers can therefore remain intact in native builds. See docs/releases/0.14.2.md.
Fixed-width comparisons now behave like ordinary booleans when negated, compared, returned from functions or stored in struct fields. The VM also canonicalizes boolean objects at the stack boundary. See docs/releases/0.14.1.md.
Z18 is delivered as one complete tooling milestone. Zumbra now includes a canonical comment-preserving formatter, an AST and pipeline-aware linter, Markdown/JSON API documentation, reproducible project scaffolding and commands, per-stage compiler profiling, stable structured diagnostics, a JSON-RPC 2.0 language server and an official VS Code extension. See docs/pt-BR/tooling-z18.md and docs/releases/0.14.0.md.
The desktop runtime now exposes desktopWindowPresentRGBA, desktopWindowSetVSync, desktopKeyDown, desktopGamepadButton, desktopAudioQueue, desktopAudioQueued, processArgs, unixTimeSeconds and native createFile. Applications keep the emulator/game logic and desktop integration in Zumbra while SDL3 remains encapsulated inside the official native runtime. See docs/releases/0.14.3.md.