Software Delivery README
Overview
The Software Delivery (SWD) stack is responsible for all updates of runnable software on a Fuchsia device, including system updates and individual package updates.
This document serves as a jumping-off point for the SWD codebase, and a contribution guide.
Before starting, you may wish to read some documentation on Fuchsia software packaging, or the long term SWD goals.
Software Delivery (SWD) Subsystems
Major Binaries
All subsystems listed below are written in Rust.
Updated: February 2023
| Subsystem | Purpose | Location |
|---|---|---|
| pkg-cache | Caches downloaded packages in case they are needed again, interacting as necessary with blobfs. | //src/sys/pkg/bin/pkg-cache |
| pkg-resolver | Main entry point for software delivery stack. Coordinates retrieval and installation of packages. | //src/sys/pkg/bin/pkg-resolver |
| omaha-client | Checks for system updates using the Omaha server infrastructure | //src/sys/pkg/bin/omaha-client |
| pkgctl | CLI for pkg-resolver | //src/sys/pkg/bin/pkgctl |
| system-update-checker | Does what it says on the tin, checks for system updates! | //src/sys/pkg/bin/system-update-checker |
| system-updater-committer | Component responsible for committing the update. | //src/sys/pkg/bin/system-update-committer |
| system-updater | Actually performs system updates. | //src/sys/pkg/bin/system-updater |
| update | Developer CLI for interacting and configuring system updates. | //src/sys/pkg/bin/update |
| far | Creates Fuchsia archive files. | //src/sys/pkg/bin/far |
Testing
Integration tests for all binaries listed above can be found in their respective paths within //src/sys/pkg/tests/{BINARY_NAME}. Related helper libraries used in these integration tests can be found at //src/sys/pkg/testing.
For wider system tests, including end-to-end tests of system OTA updates, see //src/sys/pkg/tests/system-tests.
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.
IDEs
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 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
Updating a base image to get a new version of pkg-resolver or pkgctl
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.
Pulling down a new version of an external dependency
You’ll need to update that dependency’s vendored repository in //third_party. See the Rust documentation for examples.
Resolve a package and run a contained component
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 ffx component run /core/ffx-laborary:test fuchsia-pkg://fuchsia.com/<package_name>#meta/<component_name>.cm
FAQs
How do I run a hosted package server?
See the instructions on running a package repository with pm.