Lib.rs

xterm-js-sys

Rust bindings for xterm.js.

TODO: add a picture here (sourced from the wiki) that links to a matching demo

Features

Currently this covers most of the xterm.js API.

This crate has two features:

• ext: Adds some nicer, more rust-y functions on top of the core bindings; all the functions are in this module.
• crossterm-support: Provides a wrapper type that let's crossterm use xterm.js as a backend (located here). This enables xterm.js to be used with, for example,the tui crate. Usually you won't have to enable this feature yourself; you should be able to just use crossterm and pass it a Terminal.

This crate also does support the infrastructure xterm.js has for addons. It also lets you define your own addons in Rust, if you'd like. Currently only the xterm-addon-fit package has Rust bindings. If you do end up making bindings for an xterm.js addon (or your own addon in Rust), feel free to send in a PR to update this list!

xterm.js addons

First party addon packages:

• attach: Unimplemented!
• fit: xterm-js-addon-fit-sys
• search: Unimplemented!
• serialize: Unimplemented!
• unicode11: Unimplemented!
• web-links: Unimplemented!
• webgl: Unimplemented!

Usage

Add this to your Cargo.toml:

[dependencies]
xterm-js-sys = "4.6.0-alpha1"

And make sure that your bundler/JS package manager is set to grab the corresponding verison of the xterm.js package. The examples in this repo use parcel for which all that's needed is adding xterm to your package.json:

  "dependencies": {
    "xterm": "^4.6.0"
  }

Make sure you also add the packages for any addons you're using; see our examples' package.json for an example.

The xterm.js documentation is a good reference for actual usage of the API; these bindings are usually one to one. Though, as of this writing, the xterm.js docs still correspond to version 4.4.

Examples

This repo has a few examples that show usage of the bindings, usage with the ext feature, and usage with crossterm and the tui crate.

To build these, enter the folder of the example you wish to run (i.e. examples/basic) and:

• install the packages (npm i or yarn install)
• run the watch script (npm run watch or yarn run watch)

It should (hopefully) just work! 🤞

These examples are also deployed here.

Minimum Supported Rust Version (MSRV)

This crate is currently guaranteed to compile on stable Rust 1.43 and newer. We offer no guarantees that this will remain true in future releases but do promise to always support (at minimum) the latest stable Rust version and to document changes to the MSRV in the changelog.

Contributing

PRs are (very) welcome!

TODO:

• CoC (ccov)
• contributing.md (rustfmt, clippy; commit msg convention)
• figure out how the hell env shows up as an import for core::panicking::panic_bounds_check with lto = true on the with-input demo