The supported way to run tests is via cargo-nextest.

If you don’t already have nextest installed, get started by downloading a pre-built binary or installing nextest via your package manager. Nextest has pre-built binaries for Linux, macOS and illumos.

Then, run tests with:

Nextest does not support doctests. Run doctests separately with cargo test --doc.

You can format the code using cargo fmt. Make sure to run this before pushing changes. The CI checks that the code is correctly formatted.

You can run the Clippy linter using cargo xtask clippy. CI checks that code is clippy-clean.

• Use cargo check when you just want to know if your code compiles. It’s much faster than cargo build or cargo nextest run.

• When using Cargo’s check/build/test/clippy commands, you can use the -p PACKAGE flag to only operate on a specific package. This often saves a lot of time for incremental builds.

• When using Cargo’s check/build/clippy commands, use --all-targets to make sure you’re checking or building the test code, too.

These are explained a bit more below, along with some common pitfalls.

Here’s an example workflow. Suppose you’re working on some changes to the Nexus database model (nexus-db-model package, located at nexus/db-model from the root). While you’re actively writing and checking code, you might run:

without any -p flag. Running this incrementally is pretty fast even on the whole workspace. This also uncovers places where your changes have broken code that uses this package. (If you’re making big changes, you might not want that right away. In that case, you might choose to use -p nexus-db-model here.)

When you’re ready to test the changes you’ve made, start with building and running tests for the most specific package you’ve changed:

Once that works, check the tests for the next package up:

When you’re happy with things and want to make sure you haven’t missed something, test everything:

Here are some of the big components in the control plane that live in this repo:

For those with access to Oxide RFDs, RFD 61 discusses the organization principles and key components in more detail.

Many of these components themselves are made up of other packages (e.g., nexus-db-model is under omicron-nexus). There are also many more top-level packages than what’s mentioned above. These are used for common code, clients, tools, etc. For more, see the Rustdoc for each module. (Where docs are missing or incomplete, please contribute!)

Use Cargo’s -p PACKAGE to check/build/test only the package you’re working on. Since people are usually only working on one or two components at a time, you can usually iterate faster this way.

People are often surprised to find Cargo rebuilding stuff that it seems like it’s just built, even when the relevant source files haven’t changed.

• Say you’re iterating on code, running cargo build -p nexus-db-model to build just that package. Great, it works. Let’s run tests: cargo nextest run -p nexus-db-model. Now it’s rebuilding some dependency of nexus-db-model again?!

• Say you’ve just run cargo nextest run -p nexus-db-model. Now you go run cargo nextest run -p omicron-nexus, which uses nexus-db-model. You see Cargo building nexus-db-model again?!

This usually has to do with the way Cargo selects package features. These are essentially tags that are used at build time to include specific code or dependencies. For example, the serde crate defines a feature called "derive" that controls whether the Serialize/Deserialize derive macros will be included. Let’s look at how this affects builds.

Feature selection differs when building tests

Feature selection differs when building different packages

Say you’re iterating on code, running cargo build -p nexus-db-model to build just that package. You work through lots of compiler errors until finally it works. Now you run tests: cargo nextest run -p nexus-db-model. Now you see a bunch of compiler errors again! What gives?

By default, Cargo does not operate on the tests. Cargo’s check/build/clippy commands ignore them. This is another reason we suggest using --all-targets most of the time.

Each service is a Dropshot server that presents an HTTP API. The description of that API is serialized as an OpenAPI document which we store in omicron/openapi and check in to this repo. In order to ensure that changes to those APIs are made intentionally, each service contains a test that validates that the current API matches. This allows us 1. to catch accidental changes as test failures and 2. to explicitly observe API changes during code review (and in the git history).

We also use these OpenAPI documents as the source for the clients we generate using Progenitor. Clients are automatically updated when the coresponding OpenAPI document is modified.

Note that Omicron contains a nominally circular dependency:

• Nexus depends on the Sled Agent client

• The Sled Agent client is derived from the OpenAPI document emitted by Sled Agent

• Sled Agent depends on the Nexus client

• The Nexus client is derived from the OpenAPI document emitted by Nexus

We effectively "break" this circular dependency by virtue of the OpenAPI documents being checked in.

In general, changes any service API require the following set of build steps:

1. Make changes to the service API.

2. Update the OpenAPI document by running the relevant test with overwrite set: EXPECTORATE=overwrite cargo nextest run -p <package> — test_nexus_openapi_internal (changing the package name and test name as necessary). It’s important to do this before the next step.

3. This will cause the generated client to be updated which may break the build for dependent consumers.

4. Modify any dependent services to fix calls to the generated client.

Note that if you make changes to both Nexus and Sled Agent simultaneously, you may end up in a spot where neither can build and therefore neither OpenAPI document can be generated. In this case, revert or comment out changes in one so that the OpenAPI document can be generated.

This is a particular problem if you find yourself resolving merge conflicts in the generated files. You have basically two options for this:

• Resolve the merge conflicts by hand. This is usually not too bad in practice.

• Take the upstream copy of the file, back out your client side changes (git stash and its -p option can be helpful for this), follow the steps above to regenerate the file using the automated test, and finally re-apply your changes to the client side. This is essentially getting yourself back to step 1 above and then following the procedure above.

When pulling in new changes from upstream "main", you may find conflicts in Cargo.lock. The easiest way to deal with these is usually to take the upstream changes as-is, then trigger any Cargo operation that updates the lockfile. cargo metadata is a quick one. Here’s an example:

When you do this, Cargo makes only changes to Cargo.lock that are necessary based on the various Cargo.toml files in the workspace and dependencies.

Here are things you don’t want to do to resolve this conflict:

• Run cargo generate-lockfile to generate a new lock file from scratch.

• Remove Cargo.lock and let Cargo regenerate it from scratch.

Both of these will cause Cargo to make many more changes (relative to "main") than necessary because it’s choosing the latest version of all dependencies in the whole tree. You’ll be inadvertently updating all of Omicron’s transitive dependencies. (You might conceivably want that. But usually we update dependencies either as-needed for a particular change or via individual PRs via dependabot, not all at once because someone had to merge Cargo.lock.)

You can also resolve conflicts by hand. It’s tedious and error-prone.

The ClickHouse binary uses several sources for its configuration. The binary expects an XML config file, usually named config.xml to be available, or one may be specified with the -C command-line flag. The binary also includes a minimal configuration embedded within it, which will be used if no configuration file is given or present in the current directory. The server also accepts command-line flags for overriding the values of the configuration parameters.

The packages downloaded by ci_download_clickhouse include a config.xml file with them. You should probably run ClickHouse via the omicron-dev tool, but if you decide to run it manually, you can start the server with:

The configuration file contains a large number of parameters, but most of them are described with comments in the included config.xml, or you may learn more about them here and here. Parameters may be updated in the config.xml, and the server will automatically reload them. You may also specify many of them on the command-line with: