1# Programmatic Interaction Using the `crosvm_control` Library 2 3## Usage 4 5[`crosvm_control`](https://chromium.googlesource.com/crosvm/crosvm/+/refs/heads/main/crosvm_control/src/lib.rs) 6provides a programmatic way to interface with crosvm as a substitute to the CLI. 7 8The library itself is written in Rust, but a C/C++ compatible header (`crosvm_control.h`) is 9generated during the crosvm build and emitted to the Rust `OUT_DIR`. 10([See the `build.rs`](https://chromium.googlesource.com/crosvm/crosvm/+/refs/heads/main/crosvm_control/build.rs) 11script for more information). 12 13The best practice for using `crosvm_control` from your project is to exclusively use the 14`crosvm_control.h` generated by the crosvm build. This ensures that there will never be a runtime 15version mismatch between your project and crosvm. Additionally, this will allow for build-time 16checks against the crosvm API. 17 18During your project's build step, when building the crosvm dependency, the emitted 19`crosvm_control.h` should be installed to your project's include dir - overwriting the old version 20if present. 21 22## Changes 23 24As `crosvm_control` is a externally facing interface to crosvm, great care must be taken when 25updating the API surface. Any breaking change to a `crosvm_control` entrypoint must be handled the 26same way as a breaking change to the crosvm CLI. 27 28As a general rule, additive changes (such as adding new fields to the end of a struct, or adding a 29new API) are fine and should be integrated correctly with downstream projects so long as those 30projects follow the usage best practices. Changes that change the signature of any existing 31`crosvm_control` function will cause problems downstream and should be considered a breaking change. 32 33### (ChromeOS Developers Only) 34 35For ChromeOS, it is possible to integrate a breaking change from upstream crosvm, but it should be 36avoided if at all possible. [See here](../integration/chromeos.md#cq-depend) for more information. 37