10 KiB
Optional Features
{{#include ../links.md}}
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 |
|---|---|---|
std |
no | standard features |
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][rust_decimal] number type (pulls in the [rust_decimal][rust_decimal] crate) |
unicode-xid-ident |
no | allows Unicode Standard Annex #31 as identifiers (pulls in the unicode-xid crate) |
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][debugger] 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_time |
no | disables [timestamps] |
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 [closures] |
no_custom_syntax |
no | disables [custom syntax] and [custom operators] |
Features that Disable Certain Engine Features
| Feature | Additive? | Description |
|---|---|---|
unchecked |
no | disables [arithmetic checking][checked] (such as over-flows and division by zero), [call stack depth limit][maximum call stack depth], [operations count limit][maximum number of operations], [modules loading limit][maximum number of modules] and [data size limit][maximum length of strings]. 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].
Specify default-features = false when compiling for [no-std], which will remove the default
std feature.
| Feature | Additive? | Description |
|---|---|---|
no_std |
no | builds for [no-std]; notice that additional dependencies will be pulled in to replace missing 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][safety] (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.