Files
kryon/docs/PROJECTS.md
waozi 2da7a627f6 Export the gallery examples as ZX again
Kryon's sources load through `--module-path kryon=DIR`, so the exporter
binds the frame entry and names the bundle entry by their package-scoped
module names. An export that names another file than its same-named module,
as `modal` names modal_frame.zi, is imported by its target's own name, and
other facades import from the deepest module root, because a slash in an
import names another package. All 101 examples export and render again. The
docs no longer say the website publishes these bundles; the Components page
runs every example live.
2026-11-18 03:36:11 -03:00

28 KiB
Raw Permalink Blame History

Ziran projects with Kryon

Kryon is a Ziran package. Application source imports its public modules, and the selected Kryon host links the application's Frame function. No UI syntax or widget handling is built into the Ziran compiler.

Start a project

Install ziran (make install-user in the Ziran repository) and the kryon command (make install-user here), then:

kryon new hello              # a desktop app; kryon new hello --template tui
cd hello
kryon run                    # the default profile; kryon run tui picks another
Template What it starts Profiles
app (default) counter with buttons, a step slider, and progress desktop, tui, web (canvas)
tui keyboard-driven task list tui, desktop
pages Home, Library, and Settings behind a tab row, sharing state desktop, tui, web (canvas)
web page: headings, paragraphs, links, a button web (Canvas2D), desktop

Each template's src/layout.zi stacks rows in pixels in a window or browser and in character cells on the terminal host, so one Frame serves every profile. kryon init --template tui adds a template to an existing package: Ziran merges it into ziran.toml, keeps the package's own values, and never overwrites a file, so a command-line program keeps its main and gains a window.

kryon is a front door to ziran: kryon new and kryon init are ziran new and ziran init with Kryon's templates (--template NAME for Kryon's, or any SOURCE[:NAME]), kryon run|build|check|profiles is ziran tool kryon …, and kryon install is ziran install. Each project therefore runs the Kryon its ziran.lock pins, whatever version of the kryon command is installed. KRYON_TEMPLATES=DIR takes the templates from a local Kryon checkout.

Package manifest

A Kryon application is a Ziran package whose ziran.toml hands its program to Kryon:

[package]
name = "Example"
entry = "src/app.zi"
module_roots = ["src"]
tool = "kryon"

[toolchain]
git = "https://github.com/ziranlang/ziran.git"
ref = "master"

[dependencies.kryon]
git = "https://github.com/kryonlabs/kryon.git"
ref = "master"

[tool.kryon]
default_profile = "desktop"

[tool.kryon.profiles.desktop]
backend = "desktop"

tool = "kryon" makes ziran run, ziran build, ziran check, and ziran install the same as the kryon commands. The build binds the host's frame capability to the selected source's exported Frame function. The source can have any module filename, such as button.zi; no app.zi alias or reverse module bridge is needed. [tool.kryon] entry selects the source with Frame when it differs from the package entry, as in a command-line package that also has a window. The app imports the small kryon/app runner and only the named widget packages it uses:

App  :: #import "kryon/app";
Text :: #import "kryon/text";

main :: () -> s32 {
    return App.Run(App.Window.{.title="Hello", .width=320, .height=160}, Draw)
}

Draw :: (frame: App.Frame) {
    Text.Draw(frame, Text.Props.{.text="Hello, world!", .size=32})
}

Style sheets, charts, tables, trees, and source coloring are separate Git packages: add https://github.com/kryonlabs/css.git, https://github.com/kryonlabs/plot.git, https://github.com/kryonlabs/data-views.git, or https://github.com/ziranlang/syntax.git with ziran add and import css/Css, plot/Plot, data_views/TableView, data_views/TreeView, or syntax/Syntax. Kryon exports geometry, drawing_props, and the other building blocks listed in ziran.toml for code that needs those primitives without importing the widget catalog. Native and browser profiles resolve imports the same way, so an app's Git dependencies and package-qualified named imports such as kryon/text work in Canvas builds too.

From the app directory, run:

kryon check
kryon build
kryon run desktop            # or: kryon run --profile desktop, ziran run desktop
kryon profiles               # the profiles, their hosts, and the default

Commit ziran.lock to pin exact package and toolchain revisions. ziran fetch fills the shared cache. For local development, ziran.local.toml can override the Kryon and Ziran roots; it is not the published dependency manifest. See the Ziran package guide for lock, cache, and override details.

Profiles and hosts

Foreign renderer artifacts

Builders can request Kryon's foreign libraries and standard resources through the generic Ziran artifact API:

ziran pkg artifact kryon:renderer-desktop --platform linux-x86_64-gnu --locked
ziran pkg artifact kryon:renderer-web --platform emscripten-wasm32-emscripten --locked

Omit --locked when using ziran.local.toml overrides. Success stdout is one absolute artifact.tsv path. Verify its declared SHA-256 output rows and resolve their paths beside that descriptor. renderer.json has schema 1, the artifact and platform, ordered archives and link_flags, compile_flags, Ziran defines, include_directories, and resources. Paths in those fields are relative to the descriptor directory; system flags are argv tokens. Pass archive paths after application objects, followed by link_flags. Pass compile flags and resolved include directories when compiling native code; pass defines to Ziran's ordinary compiler invocation. No generated Ziran source tree or object list is part of this contract.

Every recipe includes resources/kryon-font.ttf and its Liberation license. Linux desktop builds use SDL2, Cairo, FreeType, Pango, Fontconfig and GIO.

renderer-web supplies web/ziran_web.js from the selected Ziran toolchain, js_libraries, browser link flags and preload_files entries (path, mount) for the standard font at /kryon-font.ttf. Feed these to Emscripten's --js-library and --preload-file arguments. Game resources remain separate.

Widget and renderer Ziran code remains ordinary kryon/... imports. These artifacts do not provide a separately compiled Ziran component ABI: the current generic artifact API stages provider files but does not define such a language component interface. Builders must not rewrite generated C/H or reconstruct a private module/object list to manufacture one.

Define each profile under [tool.kryon.profiles.NAME]. It requires backend; codegen defaults to c99. Supported backends are terminal, desktop, canvas, pixmap, and android. Set default_profile under [tool.kryon] when there are several profiles. --profile NAME selects another. run asks for a profile when there are several, none is specified, and it runs in a terminal; otherwise it uses the default.

Backend Host Requirements
terminal 80 × 24 terminal cells TTY for interactive input; redirected output renders once
desktop SDL2 window with Cairo raster SDL2, Cairo, and FreeType development libraries
canvas Canvas2D browser page Emscripten with Asyncify; see Canvas host
pixmap headless 960 × 600 frame printed as a PPM image nothing; kryon run shot > frame.ppm
android installable APK through a generated droid/ Gradle project and direct NativeActivity host a JDK, the Android SDK with NDK 28.2.13676358 and CMake 3.22.1, the locked codec source packages, and [tool.kryon.android] package; see Android host

The SDL desktop host presents its already rasterized pixels through the software renderer and an unaccelerated window surface by default. Custom SDL pixel hosts can import kryon/pixmap_sdl and call CreatePixmapRenderer(window) on the window's owner thread before creating their texture. The host retains ownership of its window, renderer, texture and input loop; its raster workers are independent of this presentation choice. Explicit SDL_RENDER_DRIVER and SDL_FRAMEBUFFER_ACCELERATION environment preferences, or normal/override priority SDL hints, take precedence. The helper leaves other hosts and their graphics APIs untouched.

Such a host can also paint on the GPU by importing kryon/pixmap_sdl_gpu. PixmapGpuOpen(renderer) records the same paint commands as textured triangles, including text and terminal cells through a glyph atlas, and returns false on a software renderer or software GL driver, where the host keeps uploading pixels. While it is on, create the presented texture with PixmapGpuCreateTarget(width, height) and call PixmapGpuDraw() instead of uploading damage, then copy and present as usual. KRYON_PIXMAP_GPU=0 keeps CPU painting; =1 also uses a software GL driver.

For a custom SDL3 host, the experimental exports are kryon/pixmap_sdl3 and kryon/pixmap_sdl3_gpu; they require an SDL3 window and explicit gpu renderer. There is no backend = "sdl3" profile. From an application's package graph, request the pinned SDK with:

ziran pkg artifact kryon:native-sdl3 --platform linux-x86_64-gnu --locked

Use --locked when there is no ziran.local.toml. With local overrides, run ziran lock after the overridden package advances before requesting artifacts. The native artifact is currently Linux x86_64 GNU only. Verify the returned descriptor with Ziran's Artifact API; Artifact.link_flags() supplies the ordered static linker arguments. Verify and extract Artifact.output("resources/SDL3-headers.tar") into the consumer's build area for the complete include directory. The loose SDK headers are not all declared outputs, so use the verified archive for compilation. This SDK is native support for custom hosts, not a replacement renderer selection for an existing desktop profile. See experimental SDL3 usage and tests.

These settings live only in ziran.toml. Kryon declares them under [options] in its own ziran.toml. Ziran checks the application's [tool.kryon] tables against that declaration, merges ziran.local.toml over them, and hands the kryon tool the result, so a typo is reported with its file and line. To try another default profile on one machine, set it in the ignored ziran.local.toml:

Native C profiles also link every system library declared in the root [package].links list, in manifest order. Use system basenames such as links = ["gtk-3", "gdk-3", "gio-2.0", "gdk_pixbuf-2.0"]; the build uses the system linker's normal search paths. Portable and browser profiles do not consume this list.

static_archive links one project-relative .a file directly. The project's own build prepares the archive, and Kryon adds that exact path as both a build dependency and linker input. This is for reproducible source-package artifacts; it performs no -l lookup and never selects an operating-system package. The path cannot be absolute or lexically escape the project directory. Kryon also resolves the archive and rejects a symlink that leaves the project or a non-regular file. Browser profiles reject the setting instead of silently omitting it. library remains the existing system-library escape hatch and should be avoided by reproducible applications.

Native c99 profiles can instead request dependency-owned foreign support with native_artifacts and an explicit native_platform:

[tool.kryon.profiles.desktop]
backend = "desktop"
native_artifacts = "kryon:renderer-desktop"
native_platform = "linux-x86_64-gnu"

This adds the desktop codec support and resources to the SDL/Cairo profile. Use space-separated package:artifact selections for several providers. Selections come from the application's resolved package graph; no cache paths or prebuilt archive copies belong in its manifest. The toolchain must provide Ziran's shared artifact consumer.

Each build requests and verifies the artifacts before linking, so changed provider inputs or local overrides cannot leave an old executable in place. Kryon's renderer metadata or a provider's ordered link.txt supplies its archives and prerequisite/system link arguments. These appear after the application objects and before the profile's existing system libraries. Provider failures, malformed metadata and digest mismatches fail the build; the existing executable is replaced only after the complete link succeeds. These options require a native c99 profile; browser, Android and portable profiles use their existing target-specific packaging paths. Compile options and application asset packaging remain the selected profile's responsibility.

[tool.kryon]
default_profile = "tui"

Zx applications

Desktop, Canvas and Android profiles can package an ordinary Frame application as the same portable program with its resources:

[tool.kryon.profiles.portable]
backend = "desktop"
codegen = "zx"
assets = "assets"

Use backend = "canvas" with codegen = "zx" for the same portable app and a browser player. The build writes both .zx and .html files; serve the HTML with its generated JavaScript and WebAssembly files. The browser shell interprets the bundle and uses Canvas2D for rendering. It includes a file picker for opening another downloaded ZX without recompiling its UI. Unsupported required services are reported before replacing the running app.

An Android profile with codegen = "zx" builds its portable guest first, then packages app.zx, the VM and the NativeActivity host into the APK. Its Frame is not compiled into native application code. The canonical scaffold handles display density, safe-area insets, touch, hardware/soft-keyboard input and graphics restoration without resetting bundle state. It also registers a ZX file opener: Android document URIs are copied into private cache and validated before replacing the running app. Invalid files retain the current instance. make zx-android-test builds ARM64, ARMv7 and x86-64 shells. Runtime testing uses python3 tests/zx_android_test.py --serial emulator-NNNN and accepts only an explicitly selected disposable emulator.

make zx-canvas builds a generic browser player with no embedded app. ZX_CANVAS_BUNDLE=/absolute/path/app.zx optionally embeds a default app. A same-origin relative ?bundle=path/app.zx opens a hosted download. The browser player supports ordinary Frame bundles and standalone AppContext apps, drawing, input, fonts, embedded images and the browser clipboard. Native, Android and browser players provide packed audio, asynchronous HTTP audio/text and a monotonic clock. Requests accept only HTTP/HTTPS; guest paths cannot read host files. Android ZX scaffolds include a network manifest overlay; ordinary native builds do not use that overlay.

Standalone AppContext apps use the existing lifecycle and hosted widget contracts. They receive a private document directory per declared app ID, wall time, local time offset, locale, embedded assets and clipboard services. Native apps save on close; browser apps save periodically to IndexedDB and restore on reload. Native documents live under $XDG_DATA_HOME/kryon/apps (or $HOME/.local/share/kryon/apps), %LOCALAPPDATA%/kryon/apps on Windows, and Android's private application storage. KRYON_APP_DATA can select a different native parent directory. Account/device services that the host does not provide return the existing explicit unavailable response.

make gallery-zx exports every enabled gallery example with its full source behavior and embedded assets under build/gallery-zx/; index.json maps example IDs to their bundle paths. The entire gallery also has a portable profile. Each bundle embeds the gallery's assets, so the website runs the examples live on its Components page rather than publishing these files. The exporter and player use the gallery's configured Ziran toolchain, including its lock or local override. A ZX's embedded IR format must match its player; the installed compiler on PATH can use a different format. make gallery-zx-test validates and renders all exported examples on a private X server. make zx-canvas-test checks that the desktop and browser bundles are identical and exercises browser startup, images, clicks, Unicode, resizing, file replacement and rejection of invalid files. make zx-services-test exercises real media and HTTP on native and browser players. make zx-hosted-test checks hosted widgets, packed images and document persistence. make zx-headless-test runs VM drawing, packed PNG, retained input and Unicode without a display. The Android service and hosted tests require --android-serial emulator-NNNN and --serial emulator-NNNN respectively and verify the disposable KryonZx AVD before installing.

Custom native hosts can load kryon/bundle_player, prepare embedded assets, attach kryon/bundle_raster callbacks and then start the instance. This lets initializers use the selected renderer and assets. PlayerFrameNative runs inside the caller's ordinary frame. PlayerFrame retains the CPU-surface route for hosts that supply pixel buffers.

kryon build portable writes build/<package-name>-portable.zx. All four project templates include this profile. kryon run portable builds it and launches the reusable desktop player. After downloading that file, ziran run app.zx works without the app's source, manifest, lock, or compiler-generated native code. Install the player with make install-user in Kryon; this also registers the provider with Ziran. The player needs SDL2, Cairo and FreeType. kryon run app.zx forwards to the same Ziran runner. For a custom install prefix, add its share/ziran/hosts directory to ZIRAN_HOST_PATH or its share directory to XDG_DATA_DIRS.

assets is an optional project-relative directory or file, embedded under that same path. Images retain their ordinary Image.Props.asset_path values. The player extracts validated resources into a private temporary directory and removes it when the app exits. Exports rebuild resource content on every build, including file removals. A pixmap profile also accepts codegen = "zx" and runs through the display-free Ziran interpreter.

The desktop player supplies shapes, text, path-backed PNG images, window visibility/close handling, clipboard, pointer buttons, wheel, modifiers, keyboard and Unicode input. App globals and retained sessions persist between frames. Unsupported capabilities fail before a window opens. Native library and static archive settings cannot be linked into a portable program. Applications with custom native storage, audio, pointer casts or C callbacks must first give those effects portable host interfaces. The desktop player does not yet replace these application-specific hosts.

make zx-test exports a package-qualified app, copies only its Zx file to a download folder, and checks embedded images, installation, native pixel parity, persistent click state, keyboard/Unicode input, malformed files and missing capabilities on private displays. All four starter apps also have their Zx pixels compared with native output.

kryon install also installs a Zx profile: its portable program goes to share/kryon/<bin>/app.zx, and a reusable native player at bin/<bin> launches it. The usual desktop menu and autostart settings apply. Embedded files need no source checkout after installation.

Apps shared between harnesses

An app can import kryon/app_context and kryon/app_protocol instead of a product's host API. On APP_IDENTIFY it calls AppIdentity(id, minimum_api) and AppDescribe(name, icon), then returns APP_PROTOCOL. It draws hosted Kryon widgets on APP_FRAME, handles its own state, and saves pending changes on APP_SAVE. A supervising harness supplies AppContext, its service allowlist and callbacks from kryon/app_context_host. Identification cannot read or write user data. A bundle requiring a newer interface is rejected before its first frame.

AppSupports(name) queries optional services; AppService(name, request) returns {"status":"unavailable"} when the harness does not grant one. AppSupports("kryon.input.desktop") is true when the device's main input is a keyboard and mouse: native desktop hosts answer yes, Android and the web no, and a harness that runs inside another host passes the question on. An app that imports kryon/app_theme follows the host's theme: AppThemeColor(token, fallback) returns the host stylesheet's colour for canvas, surface, border, text, accent or link, and fallback for a token the host lacks. An app with a look of its own, such as a game, imports kryon/widget_palette instead: WidgetPaletteUse(session, palette) asks the host to draw the widgets that follow in that palette's colours (as SystemPalette), until the host's frame for the app ends. A host that is itself a bundle passes the palette on to the host that draws, so it needs a host with the call. Imports alone do not grant storage, network, clipboard or secret access. Hosts keep those permissions and account boundaries. DocumentRead, DocumentStatus and DocumentWrite distinguish missing files from read errors; an app must preserve a document it cannot read.

The desktop player runs this contract directly. Its local provider uses private documents under $XDG_DATA_HOME/kryon/apps/<id> (or ~/.local/share/kryon/apps/<id>), exclusive app-directory locking, atomic writes, the clipboard, embedded locales and a desktop image picker. Set KRYON_APP_DATA to choose another private app directory. Harnesses can provide their own account-scoped storage and sync through the same calls. Local documents do not automatically sync between different harnesses.

For example, Inner Breeze's diary.zx runs in its original harness, Werkzeug's werk --bundle diary.zx, or ziran run diary.zx; it does not load inbe.zx. Werkzeug's Calculator uses the same interface. Apps that need device secrets or timed clipboard ownership still require a harness that supplies those capabilities. The common player currently has a Linux desktop provider; hosted app release watching is not supported yet.

Installing

kryon install (or ziran install) builds one profile and installs it for the current user:

[package]
tool = "kryon"

[install]
bin = "example"

[tool.kryon.install]
profile = "desktop"            # default: default_profile
name = "Example"               # menu and window name; default: package name
comment = "What it does"
icon = "assets/icon.png"
categories = "Utility;"
working_directory = "."        # start in the project directory
autostart = true               # also start at login
autostart_env = "EXAMPLE_HIDDEN=1"

Every window and browser page is named after the app: this name, or else the package name. A build keeps it beside the program as build/NAME-PROFILE.title, an install as share/kryon/example/app.title, and a page in its HTML <title>. A ZX player names a bundle by the .title beside it or by its file name, and a program without a title by its own file name.

The program is copied to ~/.local/bin/example (or --prefix DIR). The copy replaces the old file in one step, so a running copy is never touched and later builds in build/ do not change the installed program. The icon goes to share/pixmaps/. To use the desktop's icon theme instead, set icon_name = "system-file-manager" and omit icon; the launcher stores that theme name and copies no asset. The two options are mutually exclusive. The menu entry goes to share/applications/example.desktop, and with autostart the login entry to ~/.config/autostart/example.desktop. Setting autostart = false removes an autostart entry that ziran install wrote earlier. Browser profiles cannot be installed.

The project binary is build/<package-name>-<profile>. Checked Ziran modules are saved in build/generated/<profile>/ir/ as .zir; generated C is in build/generated/<profile>/c/. ziran inspect FILE.zir displays a saved module.

Canvas projects resolve package-qualified hosts and bind the selected source through the shared frame capability. Their generator also roots canvas_raster.zi and lowers every saved module, preserving raster adapters and browser callbacks. Native profiles select the package-qualified host entry as well. The saved IR carries the frame binding into native and portable builds.

Every host draws text in Kryon's font, Liberation Sans (assets/fonts/LiberationSans-Regular.ttf): a font-pixel line box from the top of the ascent to the bottom of the descent, glyphs at their unhinted widths. The desktop host loads it from KRYON_FONT_PATH, which kryon run sets, else from the system's copy. The pixmap host rasterizes the font's outlines with integer arithmetic, so every Ziran target prints the same bytes for the same frame, and its text matches the desktop window's. It renders two frames and prints the second, for screenshots in documentation and CI without a display. make pixmap-parity-test builds every template and example for C, Go, and the portable runner and checks that all three images match; build/pixmap-parity/grid.png shows them side by side. tools/image_tools.zi, compiled to C, compares two PPM images, converts them to PNG, and lays out such grids.

Kryon's make desktop-project-test exercises the graphical host on private Xvfb displays, including keyboard and Unicode text input. make canvas-project-test builds a real Canvas2D project and loads it in private headless Chromium. Do not run graphical tests on the developer's live display.

Application-owned hosts

A profile can name an application's own Ziran host when it supplies additional platform capabilities, such as private storage or clipboard handling:

[tool.kryon.profiles.desktop]
backend = "desktop"
host = "src/desktop.zi"

The host exports main and imports the application's widgets and platform modules. Kryon builds and runs that program with the profile's backend libraries. The host must be a .zi file inside the project, including when reached through a symlink. Profiles without host use Kryon's standard host.

Native asset directories

A native profile's assets = "assets" ships that directory's contents beside its built executable as PROGRAM.assets/. ziran install copies the contents to PREFIX/share/kryon/BIN/assets/. The install keeps no dependency on the source checkout or its working directory. Undeclaring assets removes only the product's managed snapshot on the next build/install.

Packaged asset directories use mode 755 and data files (including the prefix marker) use 644, even with a private source mode or caller umask. The install creates missing product directories with mode 755 and executable files with 755; desktop entries, icons and title metadata use 644. Existing directories are never made more permissive: callers wanting a shared installation must supply a prefix whose existing ancestors allow users to traverse it. An existing private prefix remains private. Custom installers can use scripts/make-install-dirs.sh DIR... and scripts/copy-native-assets.sh SOURCE DESTINATION ORIGINAL_PREFIX for the same directory-boundary and asset snapshot behavior.

Native Image and ReadAppAsset lookup first preserves an accessible literal relative file and every absolute path. Packaged lookup then accepts paths relative to the declared directory (icons/ui.webp) and its original project prefix (assets/icons/ui.webp). Missing files keep their original path/error behavior. Paths containing parent traversal or drive names are never redirected. Web preloads, ZX bundled assets and Android APK lookup retain their existing routes.

Custom native hosts can import kryon/app_asset_path and call ResolveAppAsset(path: string, output: []u8) -> string. Use a separate 4096-byte buffer: a resolved path borrows it; an unchanged path borrows the original text. ResolveAppAssetForExecutable(path, executable, output) supplies an explicit executable for hosts/tests. Neither changes the process working directory. The standard native image loaders use this resolver automatically; a custom asset-reader callback still has exclusive ownership of its resources.

A host embedding another UI packages that UI's referenced files under its own declared asset directory, retaining their logical names. For example, an embedded Shelf's ImageForIcon needs icons/ui.webp under the Rill host's declared assets; Rill's executable and install prefix determine the runtime location.