Skip to content

AGENTS.md

Latest commit

 

History

History
181 lines (139 loc) · 7.71 KB

AGENTS.md

File metadata and controls

181 lines (139 loc) · 7.71 KB
Raw

AGENTS.md

This file provides guidance to AI coding assistants when working with code in this repository.

Project Overview

Slint is a declarative GUI toolkit for building native user interfaces across embedded systems, desktops, mobile, and web platforms. UIs are written in .slint markup files and connected to business logic in Rust, C++, JavaScript, or Python.

Build Commands

Rust (Primary)

cargo build                                    # Build the workspace
cargo build --release                          # Release build (use this flag whenever testing performance)
cargo test                                     # Run tests (requires cargo build first!)
cargo build --workspace --exclude uefi-demo    # Build all examples

Running Examples

cargo run -p gallery                 # Run the gallery example
cargo run --bin slint-viewer -- path/to/file.slint  # View a .slint file

C++ Build

cargo build --lib -p slint-cpp                 # Build C++ library
mkdir cppbuild && cd cppbuild
cmake -GNinja ..
cmake --build .

Node.js Build

cd api/node && pnpm install

Testing

Important: Run cargo build before cargo test - the dynamic library must exist first.

Test Drivers

cargo test -p test-driver-interpreter         # Fast interpreter tests
cargo test -p test-driver-rust                # Rust API tests
cargo test -p test-driver-cpp                 # C++ tests (build slint-cpp first)
cargo test -p test-driver-nodejs              # Node.js tests
cargo test -p doctests                        # Documentation snippet tests

Filtered Testing

tests/run_tests.sh rust layout     # Filter by name

Syntax Tests (Compiler Errors)

cargo test -p i-slint-compiler --features display-diagnostics --test syntax_tests
SLINT_SYNTAX_TEST_UPDATE=1 cargo test -p i-slint-compiler --test syntax_tests  # Update expected errors

Screenshot Tests

cargo test -p test-driver-screenshots                    # Compare against references
SLINT_CREATE_SCREENSHOTS=1 cargo test -p test-driver-screenshots  # Generate references

Architecture

Core Components

  • internal/compiler/ - Slint language compiler (lexer, parser, code generators)

    • parser/ - .slint syntax parsing using Rowan
    • passes/ - Optimization passes
    • generator/ - Code generators for C++, Rust, Python, JS
    • tests/syntax/ - Syntax error test cases

  • internal/core/ - Runtime library (properties, layout, animations, accessibility)

  • internal/core-macros/ - Procedural macros for i-slint-core

  • internal/common/ - Shared code and data structures between compiler and runtime

  • internal/interpreter/ - Dynamic compilation for scripting languages

  • internal/backends/ - Platform windowing/input:

    • winit/ - Cross-platform (primary)
    • qt/ - Qt integration
    • android-activity/ - Android platform support
    • linuxkms/ - Linux KMS/DRM direct rendering
    • selector/ - Runtime backend selection
    • testing/ - Testing backend for automated tests

  • internal/renderers/ - Rendering engines:

    • femtovg/ - OpenGL ES 2.0
    • skia/ - Skia graphics
    • software/ - CPU-only fallback

Language APIs (api/)

  • rs/slint/ - Rust public crate
  • rs/macros/ - slint! procedural macro
  • rs/build/ - Build script support
  • cpp/ - C++ API with CMake integration
  • node/ - Node.js bindings (Neon)
  • python/ - Python bindings (PyO3)
  • wasm-interpreter/ - WebAssembly bindings for browser use

Tools

  • tools/lsp/ - Language Server Protocol for editor integration
  • tools/compiler/ - CLI compiler
  • tools/viewer/ - .slint file viewer with hot reload
  • tools/slintpad/ - Web-based Slint editor/playground
  • tools/figma_import/ - Import designs from Figma
  • tools/tr-extractor/ - Translation string extractor for i18n
  • tools/updater/ - Migration tool for Slint version updates

Editor Support (editors/)

  • vscode/ - Visual Studio Code extension
  • zed/ - Zed editor integration
  • kate/ - Kate editor syntax highlighting
  • sublime/ - Sublime Text support
  • tree-sitter-slint/ - Tree-sitter grammar for syntax highlighting

Key Patterns

  • Internal crates (internal/) are not semver-stable - they use exact version pinning
  • FFI modules are gated with #[cfg(feature = "ffi")]
  • C++ headers generated via cargo xtask cbindgen
  • Extensive Cargo features control renderers (renderer-femtovg, renderer-skia, renderer-software) and backends (backend-winit, backend-qt)

Version Control (Git)

  • The default git branch is master

Code Style

  • Rust: rustfmt enforced in CI
  • C++: clang-format enforced in CI
  • Linear git history preferred (rebase/squash merges)

Platform Prerequisites

Linux

# Debian/Ubuntu
sudo apt install libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev \
  libfontconfig-dev libssl-dev clang libavcodec-dev libavformat-dev \
  libavutil-dev libavfilter-dev libavdevice-dev libasound2-dev pkg-config

macOS

xcode-select --install
brew install pkg-config ffmpeg

Windows

  • Enable symlinks: git clone -c core.symlinks=true https://github.com/slint-ui/slint
  • Install MSVC Build Tools
  • FFMPEG via vcpkg or manual installation

Deep Dive Documentation

For tasks requiring deeper architectural understanding, see:

  • docs/development/compiler-internals.md - Compiler pipeline, passes, LLR, code generation. Load when working on internal/compiler/.
  • docs/development/type-system.md - Type definitions, unit types, type conversions, name resolution, type register. Load when working on langtype.rs, lookup.rs, or type checking.
  • docs/development/property-binding-deep-dive.md - Reactive property system, dependency tracking, two-way bindings, PropertyTracker, ChangeTracker. Load when working on internal/core/properties.rs or debugging binding issues.
  • docs/development/custom-renderer.md - Renderer traits, drawing API, backend integration, testing. Load when working on internal/renderers/ or fixing drawing bugs.
  • docs/development/animation-internals.md - Animation timing, easing curves, performance, debugging. Load when working on internal/core/animations.rs or animation-related issues.
  • docs/development/layout-system.md - Layout solving, constraints, GridLayout/BoxLayout, compile-time lowering. Load when working on internal/core/layout.rs or sizing/positioning bugs.
  • docs/development/item-tree.md - Item tree structure, component instantiation, traversal, focus. Load when working on internal/core/item_tree.rs, event handling, or runtime component model.
  • docs/development/model-repeater-system.md - Model trait, VecModel, adapters (map/filter/sort), Repeater, ListView virtualization. Load when working on internal/core/model.rs or data binding in for loops.
  • docs/development/input-event-system.md - Mouse/touch/keyboard events, event routing, focus management, drag-drop, shortcuts. Load when working on internal/core/input.rs or event handling.
  • docs/development/text-layout.md - Text shaping, line breaking, paragraph layout, styled text parsing. Load when working on internal/core/textlayout/ or text rendering.
  • docs/development/window-backend-integration.md - WindowAdapter trait, Platform trait, WindowEvent, popup management, backend implementations. Load when working on internal/core/window.rs or internal/backends/.
  • docs/development/lsp-architecture.md - LSP server, code completion, hover, semantic tokens, live preview. Load when working on tools/lsp/ or IDE tooling.
  • docs/development/ffi-language-bindings.md - C++/Node.js/Python bindings, cbindgen, FFI patterns, adding new cross-language APIs. Load when working on api/ or internal FFI modules.