README
¶
Contributing to the Software Delivery Stack
Overview
Software Delivery (SWD) Subsystems
Major Binaries
Updated: September 2020
| Subsystem | Purpose | Location | Language |
|---|---|---|---|
| amberctl | Deprecated CLI for various components. Scheduled to be replaced by pkgctl. |
//src/sys/pkg/bin/amber/amberctl |
Go |
| pkg-cache | Caches downloaded packages in case they are needed again. | //src/sys/pkg/bin/pkg-cache |
Rust |
| pkg-resolver | Main entry point for software delivery stack. Coordinates retrieval and installation of packages. | //src/sys/pkg/bin/pkg-resolver |
Rust |
| omaha-client | Checks for system updates using the Omaha server infrastructure | //src/sys/pkg/bin/omaha-client |
Rust |
| pkgctl | CLI for pkg-resolver | //src/sys/pkg/bin/pkgctl |
Rust |
| pkgfs | A filesystem for interacting with packages that are stored on a host. | //src/sys/pkg/bin/pkgfs/pkgfs |
Go |
| system-ota-test | An end-to-end test of system over the air updates. | //src/sys/pkg/tests/system-ota-tests |
Go |
| system-update-checker | Does what it says on the tin, checks for system updates! | //src/sys/pkg/bin/system-update-checker |
Rust |
| system-updater | Actually performs system updates. | //src/sys/pkg/bin/system-updater |
Rust |
Key Dependencies
Useful Debugging Tools
fidlcat: it’sstrace, but for every IPC on the system, not just syscalls.zxdb: Fuchsia’s debugger. Similar usage togdb, and has Unicode support (emoji!). Doesn’t currently work well with golang, but works fine with Rust.- Inspect: Opt-in APIs for components to expose aspects of their state. Several portions of the SWD stack implement this, and more to come.
VS Code seems to work pretty well. Follow the instructions here, including any language-specific instructions you find relevant; the Rust instructions are a good place to start.
Style Guide
Use the style guide appropriate for the language you’re in. The SWD stack is
mostly in Rust and Go, which have strong opinions about style. All commits in
those languages should be formatted with rustfmt and gofmt respectively, and
most editors/IDEs have a mode in which you can run those commands when you save
a file. Do so!
Setup
Fuchsia Setup
Read the Fuchsia Getting Started guide first
Most of the SWD stack is in the base image of fuchsia, so to get a swd stack
working with tests, your build configuration is quite simple:
First tests
Tab 1 > fx set core.x64 --with //bundles:tests && fx build && fx serve
Tab 2 > fx qemu -kN
Tab 3 > fx run-test pkg-resolver-integration-tests # example of running the pkg-resolver integration tests
For further info on fx workflows: https://fuchsia.dev/fuchsia-src/development/workflows/fx
More general tests
If you’ve successfully run the above, you have a working Fuchsia system with the software delivery stack working.
You can discover more tests with by running fx list-packages on the host.
Common Workflows
To update the base of your fuchsia image, you can use fx ota if you’re
running on hardware which supports OTA. If you’re running under QEMU, you’ll
need to just restart QEMU to get an updated base after a rebuild. Don’t worry,
it’s fast.
You’ll need to update that dependency’s vendored repository in //third_party. See the Rust documentation for examples.
The package resolver is configured by default to resolve fuchsia.com to the
local development host. To run a component in a package you’ve built locally,
you can run something like fx shell run fuchsia-pkg://fuchsia.com/<package_name>#meta/<component_name>.cmx
TODO(wittrock): is there a global package repository we can use as a repo for this example?
FAQs
How do I run a hosted package server?
See the instructions on running a package repository with pm
More information:
Directories
¶
| Path | Synopsis |
|---|---|
|
bin
|
|
|
pkgfs/blobfs
Package blobfs provides some wrappers around interactions with the blobfs.
|
Package blobfs provides some wrappers around interactions with the blobfs. |
|
pkgfs/index
Package index implements a basic index of packages and their relative installation states, as well as thier various top level metadata properties.
|
Package index implements a basic index of packages and their relative installation states, as well as thier various top level metadata properties. |
|
pkgfs/pkgfs
Package pkgfs hosts a filesystem for interacting with packages that are stored on a host.
|
Package pkgfs hosts a filesystem for interacting with packages that are stored on a host. |
|
pm/build
Package build contains configuration structures and functions for building Fuchsia packages.
|
Package build contains configuration structures and functions for building Fuchsia packages. |
|
pm/cmd/pm/archive
Package archive implements the `pm archive` command
|
Package archive implements the `pm archive` command |
|
pm/cmd/pm/build
Package build contains the `pm build` command
|
Package build contains the `pm build` command |
|
pm/cmd/pm/delta
Package delta contains the `pm delta` command
|
Package delta contains the `pm delta` command |
|
pm/cmd/pm/expand
Package expand implements the `pm expand` command
|
Package expand implements the `pm expand` command |
|
pm/cmd/pm/genkey
Package genkey is deprecated
|
Package genkey is deprecated |
|
pm/cmd/pm/init
Package init contains the `pm init` command
|
Package init contains the `pm init` command |
|
pm/cmd/pm/newrepo
Package newrepo contains the `pm newrepo` command
|
Package newrepo contains the `pm newrepo` command |
|
pm/cmd/pm/seal
Package seal implements the `pm seal` command
|
Package seal implements the `pm seal` command |
|
pm/cmd/pm/snapshot
Package snapshot contains the `pm snapshot` command
|
Package snapshot contains the `pm snapshot` command |
|
pm/cmd/pm/update
Package update contains the `pm update` command
|
Package update contains the `pm update` command |
|
pm/cmd/pm/verify
Package verify implements the `pm verify` command
|
Package verify implements the `pm verify` command |
|
pm/ignores
Package ignores implements a basic set of patterns to ignore when constructing packages.
|
Package ignores implements a basic set of patterns to ignore when constructing packages. |
|
pm/pkg
Package pkg contains the in memory representations of a Package in the pm system and associated utilities.
|
Package pkg contains the in memory representations of a Package in the pm system and associated utilities. |
|
lib
|
|
|
far/go
Package far implements Fuchsia archive operations.
|
Package far implements Fuchsia archive operations. |
|
sse
Package sse provides support for Server-Sent Events, as a handler for net/http, and a client that can read SSE events from net/http responses.
|
Package sse provides support for Server-Sent Events, as a handler for net/http, and a client that can read SSE events from net/http responses. |
|
tests
|
|