# Programmatic Interaction Using the `crosvm_control` Library

## Usage

[`crosvm_control`](https://chromium.googlesource.com/crosvm/crosvm/+/refs/heads/main/crosvm_control/src/lib.rs)
provides a programmatic way to interface with crosvm as a substitute to the CLI.

The library itself is written in Rust, but a C/C++ compatible header (`crosvm_control.h`) is
generated during the crosvm build and emitted to the Rust `OUT_DIR`.
([See the `build.rs`](https://chromium.googlesource.com/crosvm/crosvm/+/refs/heads/main/crosvm_control/build.rs)
script for more information).

The best practice for using `crosvm_control` from your project is to exclusively use the
`crosvm_control.h` generated by the crosvm build. This ensures that there will never be a runtime
version mismatch between your project and crosvm. Additionally, this will allow for build-time
checks against the crosvm API.

During your project's build step, when building the crosvm dependency, the emitted
`crosvm_control.h` should be installed to your project's include dir - overwriting the old version
if present.

## Changes

As `crosvm_control` is a externally facing interface to crosvm, great care must be taken when
updating the API surface. Any breaking change to a `crosvm_control` entrypoint must be handled the
same way as a breaking change to the crosvm CLI.

As a general rule, additive changes (such as adding new fields to the end of a struct, or adding a
new API) are fine and should be integrated correctly with downstream projects so long as those
projects follow the usage best practices. Changes that change the signature of any existing
`crosvm_control` function will cause problems downstream and should be considered a breaking change.

### (ChromeOS Developers Only)

For ChromeOS, it is possible to integrate a breaking change from upstream crosvm, but it should be
avoided if at all possible. [See here](../integration/chromeos.md#cq-depend) for more information.