Optional Features

By default, Rhai includes all the standard functionalities in a small, tight package.

Features are not additive

Most Rhai features are not strictly additive, i.e. they do not only add optional functionalities.

In fact, most features are subtractive, i.e. they opt-out of unneeded functionalities. Notice that this deviates from Rust norm where features are additive.

Excluding functionalities result in smaller, faster builds as well as more control over what scripts can (or cannot) do.

There is a reason for this design, because the lack of a language feature by itself is a feature (that’s deep…).

See here for more details.

Features that Enable Special Functionalities

FeatureAdditive?Description
syncnorestricts all values types to those that are Send + Sync; under this feature, all Rhai types, including Engine, Scope and AST, are all Send + Sync
decimalnoenables the Decimal number type
unicode-xid-identnoallows Unicode Standard Annex #31 as identifiers
serdeyesenables serialization/deserialization via serde (pulls in the serde crate)
metadatayesenables exporting functions metadata; implies serde and additionally pulls in serde_json
internalsyesexposes internal data structures (e.g. AST nodes);

Safety Warnings
  • allowing access to internal types may enable external attack vectors
  • internal types and functions are volatile and may change from version to version
debuggingyesenables the debugging interface; implies internals

Features that Disable Certain Language Features

FeatureAdditive?Description
no_floatnodisables floating-point numbers and math
no_indexnodisables arrays and indexing features
no_objectnodisables support for custom types and object maps
no_functionnodisables script-defined functions; implies no_closure
no_modulenodisables loading external modules
no_closurenodisables capturing external variables in anonymous functions to simulate closures

Features that Disable Certain Engine Features

FeatureAdditive?Description
uncheckednodisables arithmetic checking (such as over-flows and division by zero), call stack depth limit, operations count limit, modules loading limit and data size limit.
Beware that a bad script may panic the entire system!
no_optimizenodisables script optimization
no_positionnodisables position tracking during parsing

Features that Configure the Engine

FeatureAdditive?Description
f32_floatnosets the system floating-point type (FLOAT) to f32 instead of f64; no effect under no_float
only_i32nosets the system integer type (INT) to i32 and disable all other integer types
only_i64nosets the system integer type (INT) to i64 and disable all other integer types

Features for no-std Builds

The following features are provided exclusively for no-std targets. Do not use them when not compiling for no-std.

FeatureAdditive?Description
no_stdnobuilds for no-std; notice that additional dependencies will be pulled in to replace std features

Features for WebAssembly (WASM) Builds

The following features are provided exclusively for WASM targets. Do not use them for non-WASM targets.

FeatureAdditive?Description
wasm-bindgennouses wasm-bindgen to compile for WASM
stdwebnouses stdweb to compile for WASM

Features for Building Bin Tools

The feature bin-features include all the features necessary for building the bin tools.

By default, it includes: decimal, metadata, serde, debugging and rustyline.

Example

The Cargo.toml configuration below:

[dependencies]
rhai = { version = "1.8.0", features = [ "sync", "unchecked", "only_i32", "no_float", "no_module", "no_function" ] }

turns on these six features:

FeatureDescription
synceverything is Send + Sync
uncheckeddisable all safety checks (should not be used with untrusted user scripts)
only_i32use only 32-bit signed integers and no others
no_floatno floating point numbers
no_moduleno loading external modules
no_functionno defining functions

The resulting scripting engine supports only the i32 integer numeral type (and no others like u32, i16 or i64), no floating-point, is Send + Sync (so it can be safely used across threads), and does not support defining functions nor loading external modules.

This configuration is perfect for an expression parser in a 32-bit embedded system without floating-point hardware.