reorganize module

_archive/rhai_engine/rhaibook/patterns/multiple.md

@@ -0,0 +1,95 @@
+Multiple Instantiation
+======================
+
+{{#include ../links.md}}
+
+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, however, is more complex.
+
+
+Rhai Language Features Are Not Additive
+---------------------------------------
+
+Language features cannot be easily made _additive_.
+
+That is because the _lack_ of a language feature is a feature by itself.
+
+```admonish question "A practical illustration"
+
+Assume an _additive_ feature called `floating-point` that adds floating-point support.
+
+Assume also that the application _omits_ the `floating-point` feature (why? perhaps integers are all
+that make sense within the project domain). Floating-point numbers do not even parse under this
+configuration and will generate syntax errors.
+
+Now, assume that a dependent crate _also_ depends on Rhai, but a new version suddenly decides to
+_require_ floating-point support. That dependent crate would, naturally, specify the
+`floating-point` feature.
+
+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 `floating-point`
+feature turned on because features are _additive_.
+
+This will in turn break the application, which by itself specifically omits `floating-point` and
+expects floating-point numbers to be rejected, in unexpected ways. Suddenly and without warning,
+floating-point numbers show up in data which the application is not prepared to handle.
+
+There is no way out of this dilemma, because the _lack_ of a language feature can be depended upon
+as a feature.
+```
+
+
+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/rhaiscript/rhai) – Crate source on GitHub.
+
+* Forked copy of [https://github.com/rhaiscript/rhai](https://github.com/rhaiscript/rhai) on GitHub.
+
+* Local copy of [https://github.com/rhaiscript/rhai](https://github.com/rhaiscript/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/rhaiscript/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.
+
+
+```admonish danger.small "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.
+```