Contribute to Cubic

Contributions are very welcome. Thank you for taking the time to contribute to Cubic!

How to contribute?

There are many ways to contribute, no matter your background:

• Report bugs — open an issue on GitHub if something does not work as expected.
• Request features — open an issue on GitHub to suggest improvements.
• Improve documentation — fix typos, clarify explanations, or add missing guides in the docs/ directory.
• Submit code changes — open a pull request with your fix or feature.
• Join the discussion — share feedback and ideas on existing issues and pull requests.

How to set up a development environment?

Before building Cubic, ensure you have the necessary tools installed:

• Git
• GCC
• Rustup

For Debian, Ubuntu, and derivatives:

sudo apt update && sudo apt install -y git gcc rustup

For Fedora and derivatives:

sudo dnf install -y git gcc rustup && sudo rustup-init -y

For OpenSUSE and derivatives:

sudo zypper install -y git gcc rustup

Then clone the repository:

git clone https://github.com/cubic-vm/cubic.git
cd cubic/
rustup toolchain add 1.92.0

How to build?

Debug build (fast compile, no optimisations):

cargo build

Release build (optimised, matches the distributed binary):

cargo build --locked --release

The release binary is written to target/release/cubic.

Note: --locked ensures the build uses the exact dependency versions intended by the developers.

How to run the binary?

cargo run -- [COMMAND] [OPTIONS]

For example:

cargo run -- images
cargo run -- --help

Runtime dependencies

To actually run virtual machines, Cubic requires QEMU to be installed on the host:

• qemu-system-x86_64
• qemu-system-aarch64
• qemu-img

How to test?

cargo test

To run a single test by name:

cargo test <test_name>

How to generate the documentation?

The documentation is built with Sphinx. The source files live in the docs/ directory and are written in reStructuredText.

First, generate the CLI reference pages from the binary's help output:

./scripts/generate-docs.sh dev

Then build the HTML site:

sphinx-build docs target/doc

The output is written to target/doc/.

How to fix code formatting?

cargo fmt

To only check without modifying files:

cargo fmt --check

How to lint?

cargo clippy -- -D warnings

To automatically apply safe fixes:

cargo clippy --fix --allow-dirty

How to run a security audit?

cargo audit

How to create a good pull request?

High quality pull requests are easier to review and thus take less of your and our time.

General guideline:

• Each pull request must have exactly one intent (fix a bug, update doc, etc.).
• Each pull request should have one Git commit (not mandatory, but recommended).
• Each Git commit must have a descriptive message that explains the changes.
• Each Git commit must have a sign-off (git commit --signoff), which indicates that you agree with the Developer Certificate of Origin.
• Each Git commit message must start with either:
  • feat: ... for features
  • fix: ... for bug and security fixes
  • refactor: ... for code refactorings
  • docs: ... for documentation changes
  • chore: ... for changes not related to source code
  • revert: ... for reverting a previous commit

Before opening a pull request, please verify that your changes pass all checks:

cargo fmt --check && cargo clippy -- -D warnings && cargo test && cargo audit

What license does Cubic use?

Cubic is dual-licensed under the MIT and Apache 2.0 licenses. By submitting a pull request, you agree that your contribution is licensed under these licenses.