These docs describe the main branch, including unreleased changes. Read the 0.9.4 docs.

Install, link, and ship

A Rust app needs two things: the crates, and OpenTUI’s native library for its platform. The crates link the native library, but they do not build it. You get the library from a GitHub release, or by building it in a checkout of the repository.

The crates are on crates.io. opentui and opentui-sys are published as anomalyco-opentui and anomalyco-opentui-sys for now, because their own names are taken. Their libraries are still named opentui and opentui_sys, so your code writes use opentui::.... They need Rust 1.88 or later. opentui-ssh needs 1.89, and the tree-sitter feature needs 1.90. Each crate has the version of the OpenTUI release it belongs to.

Depend on a release#

  1. Add the crate under the name opentui:

    cargo add anomalyco-opentui --rename opentui

    In Cargo.toml, that is opentui = { package = "anomalyco-opentui", version = "0.9.4" }. To serve apps over SSH, also run cargo add opentui-ssh.

  2. Download the native archive for your platform from the release with the crate’s version on GitHub Releases, for example opentui-native-v0.9.4-linux-x64.zip. The archive has no top-level folder, so extract it into a directory of its own, such as vendor/opentui-native. It holds opentui.h, the shared and static libraries, and the license notices.

  3. Set OPENTUI_LIB_DIR to that directory when you run Cargo. Use an absolute path, because Cargo resolves a relative one from the anomalyco-opentui-sys crate’s directory. In .cargo/config.toml, relative = true resolves the path from your project directory, so Cargo gets an absolute path:

    [env]
    OPENTUI_LIB_DIR = { value = "vendor/opentui-native", relative = true }
    OPENTUI_LIB_HINT = "run scripts/fetch-opentui.sh"

The archive must come from the release with the crates’ version. The build checks that the archive’s opentui.h matches the crates and fails if it does not.

To use the crates of a commit that is not released, depend on them through Git. Build the native library in a checkout of that commit, as Build from a checkout describes, and set OPENTUI_LIB_DIR to its lib/<artifact directory>:

[dependencies]
opentui = { package = "anomalyco-opentui", git = "https://github.com/anomalyco/opentui", rev = "<commit>" }

If a file is missing, the build fails and names the release archive to extract. OPENTUI_LIB_HINT replaces that message with your own, so it can point to your project’s setup step. In the example above, scripts/fetch-opentui.sh stands for such a step.

Build from a checkout#

In a checkout, the crates link the library that the checkout’s native build writes to lib/<artifact directory> in the native workspace. Build the native library first, then run Cargo from the repository root:

bun install
bun run build   # or `bun run build:native` in packages/core
cargo test --manifest-path packages/rust/Cargo.toml

OPENTUI_LIB_DIR takes precedence over the checkout’s build. It can point to an extracted release archive, or to an npm platform package such as node_modules/@opentui/core-linux-x64. An npm platform package ships only the shared library, so you need to turn the default features off. The Windows GNU targets are the exception: they always link the shared library.

On macOS, the native build needs the macOS SDK, which comes with the Xcode Command Line Tools (xcode-select --install). bun run build builds for the Mac’s own architecture. To build the other one, run zig build -Doptimize=ReleaseFast -Dlibrary-target=x86_64-macos.13.0 (or aarch64-macos.13.0) in the native workspace.

The Windows build needs no SDK, so you can build it on any system with Zig: zig build -Doptimize=ReleaseFast -Dlibrary-target=x86_64-windows-gnu.

Platforms#

Platform Rust target Release archive Artifact directory
Linux x86_64 with glibc x86_64-unknown-linux-gnu linux-x64 x86_64-linux
Linux arm64 with glibc aarch64-unknown-linux-gnu linux-arm64 aarch64-linux
Linux x86_64 with musl x86_64-unknown-linux-musl linux-x64-musl x86_64-linux-musl
Linux arm64 with musl aarch64-unknown-linux-musl linux-arm64-musl aarch64-linux-musl
macOS 13 or later, Apple chips aarch64-apple-darwin darwin-arm64 aarch64-macos
macOS 13 or later, Intel chips x86_64-apple-darwin darwin-x64 x86_64-macos
Windows 10 1809 or later x86_64-pc-windows-msvc, x86_64-pc-windows-gnu windows-x64 x86_64-windows
Windows 10 1809 or later, Arm aarch64-pc-windows-msvc, aarch64-pc-windows-gnullvm windows-arm64 aarch64-windows

The release archive is named opentui-native-v<version>-<release archive>.zip. A checkout builds into lib/<artifact directory> in the native workspace, and Cargo picks the directory for the target it builds.

Rust’s musl targets build static executables, which cannot load libopentui.so. On those targets, keep the default static feature. With the shared library and a static executable, the build fails. If you need the shared library there, turn the default features off and build with RUSTFLAGS='-C target-feature=-crt-static'.

Features#

  • static (default): link the static library. See Static and shared linking.
  • tokio: App::spawn runs futures on a Tokio runtime and delivers their results on the UI thread.
  • log: console::init_logger shows records from the log crate in the debug console.
  • tree-sitter: Code, Diff, Textarea, and Markdown code blocks get syntax highlighting. It bundles grammars for JavaScript, TypeScript and TSX, Markdown, Zig, and Rust.

Static and shared linking#

By default the crates link OpenTUI statically: libopentui.a on Linux and macOS, and opentui-static.lib on the Windows MSVC targets. The executable then needs no OpenTUI file at run time.

  • Linux: the static library carries its own private libc++, so the program needs only libc. Other C++ code in the program keeps its own C++ runtime.
  • macOS: the crates also link the system frameworks OpenTUI uses for the clipboard, audio, and video.
  • Windows MSVC: the static library is built with MinGW and carries the parts of MinGW’s runtime it needs, libc++ among them, so other C++ code keeps MSVC’s runtime. Build with RUSTFLAGS='-C target-feature=+crt-static' and the .exe needs no Visual C++ runtime DLL either. It is then the only file you ship.
  • Windows GNU: these targets always link opentui.dll, with or without the static feature, because their MinGW runtime is not the one the library was built with.

To link the shared library (libopentui.so, libopentui.dylib, or opentui.dll), turn the default features off with default-features = false or --no-default-features. Cargo merges features across the whole dependency graph, so every crate in your app that depends on opentui must turn them off.

A shared library must be found at run time:

  • On Windows, the crates link opentui.dll through its import library, opentui.lib, so the library directory needs both. Ship opentui.dll beside the .exe. The build copies it to where cargo run and cargo test find it.
  • On Linux and macOS, give your executable an rpath, or set LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (macOS). The crates’ own tests and examples already have an rpath.

Video and licenses#

The native library includes FFmpeg, which VideoView uses to play video. The release archives include it. In a checkout, bun run build prepares FFmpeg for the host platform. Without it, the native build warns and leaves video out.

FFmpeg is licensed under LGPL-2.1-or-later. The default native library includes it even if your app never uses VideoView. The Rust code is MIT-licensed. anomalyco-opentui-sys ships LICENSE-FFMPEG and FFMPEG-SOURCE.md, and the library carries code under these other notices:

  • Yoga (LICENSE-YOGA)
  • Zig’s runtime (LICENSE-ZIG)
  • on Linux and Windows, LLVM’s libc++, libc++abi, and libunwind (LICENSE-LLVM)
  • on Windows, the MinGW-w64 runtime (LICENSE-MINGW-W64) and its gdtoa code (LICENSE-GDTOA)
  • FFmpeg’s zlib code (LICENSE-ZLIB)

Ship these notices with an app that links OpenTUI statically, or with opentui.dll. Each release archive also includes them, along with the notices for the library’s other bundled code.

To build the native library without FFmpeg, run these in the native workspace of a checkout:

sh scripts/prepare-zig-deps.sh
zig build -Dvideo=false -Doptimize=ReleaseFast

Then set OPENTUI_LIB_DIR to the absolute path of the resulting lib/<artifact directory> when you run Cargo.

Windows consoles#

On Windows, the app turns on the console’s virtual terminal mode, so it reads the same input sequences as on Unix. Some keys and events behave differently:

  • Windows has no job control, so Ctrl+Z reaches your key handlers instead of suspending the app.
  • Ctrl+Break, closing the console, logging off, and shutting down end App::run, as signals do on Unix.

See C for the native artifacts and how other languages link them.

Changes0.9.4
0.9.4
native: The Rust packages opentui and opentui-sys are now named anomalyco-opentui and anomalyco-opentui-sys. Add package = "anomalyco-opentui" to a Git or path dependency, and use the new names with cargo -p and --features. (#2167)