Expand description
build-host: generates a wrapper project, cargo builds a cdylib out of it, and
copies that into the install dir.
§Why a wrapper is needed
cargo install only knows about bin targets, so a crate-type = ["cdylib"] crate
cannot be installed that way. And cargo build on a plugin crate directly does
not make Cargo produce a cdylib for a dependency either.
So a wrapper project of a few dozen lines is generated. The generator itself lives in
the private wrapper module, because crate::pack — the release-asset path — builds
the exact same wrapper from a local checkout:
<build>/<crate>/
├── Cargo.toml # [lib] crate-type = ["cdylib"], depends on the plugin and the host contract crate
├── src/lib.rs # one line: <contract>::export!(<plugin_crate>::create);
└── target/ # cargo's build cache, kept between installs -- see `reset_wrapper`The benefit is that the plugin’s own crate stays a plain rlib: crates.io consumes
it normally, unit tests can use it directly, and the plugin author does not have
to write a single #[no_mangle].
§Where the manifest comes from
The plugin crate’s source root holds a copy of <manifest_name>. cargo metadata
is used here to locate the crate source dir, and the file is copied verbatim into
the install dir — see the module docs of crate::manifest.
§Layout
install is the whole flow. metadata holds the cargo metadata parsing, and
probe_contract_requirement below is the one step that has to run before the
wrapper exists.
The two generated files are rewritten on every install; the target directory beside
them is not. That asymmetry is deliberate and load-bearing — reset_wrapper says why.
Functions§
- install
- Installs a plugin through build-host.
- install_
from_ path - Installs a plugin from a checkout on this machine.