Skip to content

Latest commit

 

History

History
205 lines (156 loc) · 6.88 KB

DEVELOPMENT.md

File metadata and controls

205 lines (156 loc) · 6.88 KB
Raw

Developing homestar

Outline

Building and Running the Project

  • Building homestar:

    For the fastest compile-times and prettiest logs while developing homestar, build with:

    cargo build --no-default-features --features dev

    This removes underlying wasmtime zstd compression while also turning on ANSI color-coded logs. If you build with default features, zstd compression and other wasmtime defaults will be included in the build.

  • Running the homestar server/runtime:

    cargo run --no-default-features --features dev -- start

  • Running with tokio-console for diagnosis and debugging:

    RUSTFLAGS="--cfg tokio_unstable" cargo run --no-default-features --features dev,console -- start

    Then, in another window:

    tokio-console --retain-for 60sec

Testing the Project

  • Running the tests:

    We recommend using cargo nextest, which is installed by default in our Nix flake or can be installed separately.

    cargo nextest run --all-features --no-capture

    This command translates to the default cargo test command:

    cargo test --all-features -- --nocapture

Running the Runtime on Docker

We recommend setting your Docker Engine configuration with experimental and buildkit set to true, for example:

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": true,
  "features": {
    "buildkit": true
  }
}

  • Build a multi-plaform Docker image via buildx:

    docker buildx build --build-arg git_sha=$(git rev-parse HEAD) \
--build-arg git_timestamp=$(git log -1 --pretty=format:'%cI') \
--file docker/Dockerfile --platform=linux/amd64,linux/arm64 -t homestar --progress=plain .

  • Run a Docker image (depending on your platform):

    docker run -it --rm --platform=linux/arm64 -p 3030:3030 -p 1337:1337 -t homestar

Nix

This repository contains a Nix flake that initiates both the Rust toolchain set in rust-toolchain.toml and a pre-commit hook. It also installs external dependencies, as well as helpful cargo binaries for development. Please install nix and direnv to get started.

Run nix develop or direnv allow to load the devShell flake output, according to your preference.

Formatting

For formatting Rust in particular, we automatically format on nightly, as it uses specific nightly features we recommend by default.

Pre-commit Hook

This project recommends using pre-commit for running pre-commit hooks. Please run this before every commit and/or push.

  • If you are doing interim commits locally, and you want to skip the pre-commit checks you can run git commit -a -m "Your message here" --no-verify.

Recommended Development Flow

  • We recommend leveraging cargo-watch, cargo-expand and irust for Rust development.
  • We also recommend using cargo-udeps for removing unused dependencies before commits and pull-requests.
  • If using our Nix flake, there are a number of handy command shortcuts available for working with cargo-watch, diesel, and other items, including:
    • ci, which runs a sequence of commands to check formatting, lints, release builds, and tests
    • db and db-reset for running diesel setup and migrations
    • doc for generating cargo docs with private-items documented
    • docker-<amd64,arm64> for running docker builds
    • nx-test, which translates to cargo nextest run --workspace && cargo test --workspace --doc
    • x-test for testing continuously as files change, translating to cargo watch -c -s "cargo nextest run --workspace --no-capture && cargo test --doc"
    • x-<build,check,run,clippy> for running a variety of cargo watch execution stages
    • nx-test-<all,0>, which is just like nx-test, but adds all or 0 for running tests either with the all-features flag or no-default-features flag, respectively
    • x-<build,check,run,clippy,test>-<core,wasm,runtime> for package-specific builds, tests, etc.

Conventional Commits

This project lightly follows the Conventional Commits convention to help explain commit history and tie in with our release process. The full specification can be found here. We recommend prefixing your commits with a type of fix, feat, docs, ci, refactor, etc..., structured like so:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Non-Rust Dependencies

wit-deps

We are using wit-deps to track WIT dependencies/interfaces, which is installed by default in our Nix flake or can be installed separately with cargo install wit-deps-cli.

To see an example of wit-deps in action, view our host helpers, where we import the wasi-logging interface. We track this dependency in our deps.toml file:

logging = "https://github.com/WebAssembly/wasi-logging/archive/main.tar.gz"

To update packages, we can run wit-deps within the homestar-wasm directory.