Optional Features
By default, Rhai includes all the standard functionalities in a small, tight package.
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]({{rootUrl}}/patterns/multiple.md) for more details.
Features that Enable Special Functionalities
| Feature | Additive? | Description |
|---|---|---|
sync | no | restricts all values types to those that are Send + Sync; under this feature, all Rhai types, including Engine, Scope and AST, are all Send + Sync |
decimal | no | enables the Decimal number type |
unicode-xid-ident | no | allows Unicode Standard Annex #31 as identifiers |
serde | yes | enables serialization/deserialization via serde (pulls in the serde crate) |
metadata | yes | enables exporting functions metadata; implies serde and additionally pulls in serde_json |
internals | yes | exposes internal data structures (e.g. AST nodes);Safety Warnings
|
debugging | yes | enables the debugging interface; implies internals |
Features that Disable Certain Language Features
| Feature | Additive? | Description |
|---|---|---|
no_float | no | disables floating-point numbers and math |
no_index | no | disables arrays and indexing features |
no_object | no | disables support for custom types and object maps |
no_function | no | disables script-defined functions; implies no_closure |
no_module | no | disables loading external modules |
no_closure | no | disables capturing external variables in anonymous functions to simulate closures |
Features that Disable Certain Engine Features
| Feature | Additive? | Description |
|---|---|---|
unchecked | no | disables 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_optimize | no | disables script optimization |
no_position | no | disables position tracking during parsing |
Features that Configure the Engine
| Feature | Additive? | Description |
|---|---|---|
f32_float | no | sets the system floating-point type (FLOAT) to f32 instead of f64; no effect under no_float |
only_i32 | no | sets the system integer type (INT) to i32 and disable all other integer types |
only_i64 | no | sets 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.
| Feature | Additive? | Description |
|---|---|---|
no_std | no | builds 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.
| Feature | Additive? | Description |
|---|---|---|
wasm-bindgen | no | uses wasm-bindgen to compile for WASM |
stdweb | no | uses 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 = "{{version}}", features = [ "sync", "unchecked", "only_i32", "no_float", "no_module", "no_function" ] }
turns on these six features:
| Feature | Description |
|---|---|
sync | everything is Send + Sync |
unchecked | disable all safety checks (should not be used with untrusted user scripts) |
only_i32 | use only 32-bit signed integers and no others |
no_float | no floating point numbers |
no_module | no loading external modules |
no_function | no 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.