oxidecomputer / oxidecomputer/omicron

Would like expanded releng docs for building OS images

Open
#7,479 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
572
Forks
97
Avg merge
2d 12h
Merged PRs (30d)
96

Description

If you're getting started from the perspective of I normally build an OS image, but not in Omicron context, and have an urgent need to turn that into one that does, I think expanding the docs to cover some of the expected pre-reqs and which parts of the other Omicron dev docs are required might be useful. From reading the current docs one might assume that it'd be reasonable to just clone omicron and run cargo xtask releng --helios-local --helios-dir ~/src/path/to/helios. There are a few additional things I've found that need to be set up, which I expect are true regardless of what one is doing:

  • Creating required ZFS datasets
  • Having downloaded dendrite bits (cargo xtask download dendrite-openapi)

From the --help and current docs it's not clear if I should have already built the illumos bits (I did) or not. I'm assuming it wants me to at this point in the process, but I'm also not sure how it would pick debug vs. non-debug.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the current releng documentation and run cargo xtask releng --help to compare the documented flow with the reported prerequisites. Check how required ZFS datasets, cargo xtask download dendrite-openapi, and existing illumos debug or non-debug builds fit into the process. Done means the docs clearly list setup steps and explain which build artifacts each mode expects.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
build-system, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.