Skip to main content

Module build_host

Module build_host 

Source
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.