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 not on crates.io. They need Rust 1.88 or later. opentui-ssh needs 1.89, and the tree-sitter feature needs 1.90. Each OpenTUI release tags them with the version of @opentui/core.

Depend on a release#

  1. Add the crates as a Cargo git dependency, pinned to a release tag:

    [dependencies.opentui]
    git = "https://github.com/anomalyco/opentui"
    tag = "v0.9.3"

    Releases after v0.9.3 name the package anomalyco-opentui; its library is still opentui, so your code keeps use opentui::.... A dependency on a later tag adds package = "anomalyco-opentui". opentui-ssh keeps its name. To serve apps over SSH, add opentui-ssh the same way.

  2. Download the native archive for your platform from the same release on GitHub Releases, for example opentui-native-v0.9.3-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 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 same release as the tag. The build checks that the archive’s opentui.h matches the crates and fails if it does not. To use any other commit of the crates, build the native library from that 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. 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)