90 lines
4.0 KiB
Markdown
90 lines
4.0 KiB
Markdown
|
Multiple Instantiation
|
||
|
|
======================
|
||
|
|
|
||
|
|
{{#include ../links.md}}
|
||
|
|
|
||
|
|
|
||
|
|
Background
|
||
|
|
----------
|
||
|
|
|
||
|
|
Rhai's [features] are not strictly additive. This is easily deduced from the [`no_std`] feature
|
||
|
|
which prepares the crate for `no-std` builds. Obviously, turning on this feature has a material
|
||
|
|
impact on how Rhai behaves.
|
||
|
|
|
||
|
|
Many crates resolve this by going the opposite direction: build for `no-std` in default,
|
||
|
|
but add a `std` feature, included by default, which builds for the `stdlib`.
|
||
|
|
|
||
|
|
|
||
|
|
Rhai Language Features Are Not Additive
|
||
|
|
--------------------------------------
|
||
|
|
|
||
|
|
Rhai, however, is more complex. Language features cannot be easily made _additive_.
|
||
|
|
|
||
|
|
That is because the _lack_ of a language feature is a feature by itself.
|
||
|
|
|
||
|
|
For example, by including [`no_float`], a project sets the Rhai language to ignore floating-point math.
|
||
|
|
Floating-point numbers do not even parse under this case and will generate syntax errors.
|
||
|
|
Assume that the project expects this behavior (why? perhaps integers are all that make sense
|
||
|
|
within the project domain).
|
||
|
|
|
||
|
|
Now, assume that a dependent crate also depends on Rhai. Under such circumstances,
|
||
|
|
unless _exact_ versioning is used and the dependent crate depends on a _different_ version
|
||
|
|
of Rhai, Cargo automatically _merges_ both dependencies, with the [`no_float`] feature turned on
|
||
|
|
because Cargo features are _additive_.
|
||
|
|
|
||
|
|
This will break the dependent crate, which does not by itself specify [`no_float`]
|
||
|
|
and expects floating-point numbers and math to work normally.
|
||
|
|
|
||
|
|
There is no way out of this dilemma. Reversing the [features] set with a `float` feature
|
||
|
|
causes the project to break because floating-point numbers are not rejected as expected.
|
||
|
|
|
||
|
|
|
||
|
|
Multiple Instantiations of Rhai Within The Same Project
|
||
|
|
------------------------------------------------------
|
||
|
|
|
||
|
|
The trick is to differentiate between multiple identical copies of Rhai, each having
|
||
|
|
a different [features] set, by their _sources_:
|
||
|
|
|
||
|
|
* Different versions from [`crates.io`](https://crates.io/crates/rhai/) - The official crate.
|
||
|
|
|
||
|
|
* Different releases from [`GitHub`](https://github.com/jonathandturner/rhai) - Crate source on GitHub.
|
||
|
|
|
||
|
|
* Forked copy of [https://github.com/jonathandturner/rhai](https://github.com/jonathandturner/rhai) on GitHub.
|
||
|
|
|
||
|
|
* Local copy of [https://github.com/jonathandturner/rhai](https://github.com/jonathandturner/rhai) downloaded form GitHub.
|
||
|
|
|
||
|
|
Use the following configuration in `Cargo.toml` to pull in multiple copies of Rhai within the same project:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[dependencies]
|
||
|
|
rhai = { version = "{{version}}", features = [ "no_float" ] }
|
||
|
|
rhai_github = { git = "https://github.com/jonathandturner/rhai", features = [ "unchecked" ] }
|
||
|
|
rhai_my_github = { git = "https://github.com/my_github/rhai", branch = "variation1", features = [ "serde", "no_closure" ] }
|
||
|
|
rhai_local = { path = "../rhai_copy" }
|
||
|
|
```
|
||
|
|
|
||
|
|
The example above creates four different modules: `rhai`, `rhai_github`, `rhai_my_github` and
|
||
|
|
`rhai_local`, each referring to a different Rhai copy with the appropriate [features] set.
|
||
|
|
|
||
|
|
Only one crate of any particular version can be used from each source, because Cargo merges
|
||
|
|
all candidate cases within the same source, adding all [features] together.
|
||
|
|
|
||
|
|
If more than four different instantiations of Rhai is necessary (why?), create more local repositories
|
||
|
|
or GitHub forks or branches.
|
||
|
|
|
||
|
|
|
||
|
|
Caveat - No Way To Avoid Dependency Conflicts
|
||
|
|
--------------------------------------------
|
||
|
|
|
||
|
|
Unfortunately, pulling in Rhai from different sources do not resolve the problem of
|
||
|
|
[features] conflict between dependencies. Even overriding `crates.io` via the `[patch]` manifest
|
||
|
|
section doesn't work - all dependencies will eventually find the only one copy.
|
||
|
|
|
||
|
|
What is necessary - multiple copies of Rhai, one for each dependent crate that requires it,
|
||
|
|
together with their _unique_ [features] set intact. In other words, turning off Cargo's
|
||
|
|
crate merging feature _just for Rhai_.
|
||
|
|
|
||
|
|
Unfortunately, as of this writing, there is no known method to achieve it.
|
||
|
|
|
||
|
|
Therefore, moral of the story: avoid pulling in multiple crates that depend on Rhai.
|