| # 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](https://fuchsia.dev/fuchsia-src/concepts/packages/package) on |
| Fuchsia software packaging, or the [long term SWD goals](https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0133_swd_goals). |
| |
| ### Software Delivery (SWD) Subsystems |
| |
|  |
| |
| ### Major Binaries |
| |
| All subsystems listed below are written in Rust. |
| |
| Updated: January 2025 |
| |
| | 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](https://fuchsia.dev/fuchsia-src/concepts/packages/ota#update-omaha) | `//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!](https://fuchsia.dev/fuchsia-src/concepts/packages/ota#update-system) | `//src/sys/pkg/bin/system-update-checker` | |
| | system-updater-committer | Component responsible for [committing the update.](https://fuchsia.dev/fuchsia-src/concepts/packages/ota#committing-update) | `//src/sys/pkg/bin/system-update-committer` | |
| | system-updater | Actually [performs system updates.](https://fuchsia.dev/fuchsia-src/concepts/packages/ota#staging-update) | `//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 |
| |
| * [rust-tuf](https://fuchsia.googlesource.com/third_party/rust-mirrors/rust-tuf/) |
| * [go-tuf](https://fuchsia.googlesource.com/third_party/go-tuf/) |
| * [hyper](https://github.com/hyperium/hyper) |
| * [rustls](https://github.com/ctz/rustls). |
| |
| #### Useful Debugging Tools |
| |
| * [`fidlcat`](https://fuchsia.dev/fuchsia-src/development/tools/fidl_inspecting): |
| it’s `strace`, but for every IPC on the system, not just syscalls. |
| * [`zxdb`](https://fuchsia.dev/fuchsia-src/development/debugger): |
| Fuchsia’s debugger. Similar usage to `gdb`, and has Unicode support |
| (emoji!). Doesn’t currently work well with golang, but works fine with Rust. |
| * [Inspect](https://fuchsia.dev/fuchsia-src/development/diagnostics/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](https://fuchsia.dev/fuchsia-src/reference/tools/editors#vs-code), 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](https://fuchsia.dev/fuchsia-src/get-started/learn-fuchsia). |
| |
| 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 |
| |
| ```sh |
| |
| Tab 1 > fx set core.x64 --with //bundles/tests && fx build && fx serve -v |
| |
| Tab 2 > sudo ip tuntap add dev qemu mode tap user $USER && sudo ip link set qemu up |
| |
| Tab 2 > ffx emu start --net tap -H # starts Fuchsia in an emulator running in the background, headless |
| |
| Tab 2 > 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 |
| usually just restart QEMU to get an updated base after a rebuild. Don’t worry, |
| it’s fast. If you are running an emulator that supports OTA workflows (i.e. |
| started with `ffx emu start --uefi ...`), you can use `fx ota` if you prefer. |
| |
| ##### 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](https://fuchsia.dev/fuchsia-src/development/languages/rust/external_crates) |
| 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 |
| [publishing a package with ffx](https://fuchsia.dev/fuchsia-src/development/idk/documentation/packages). |
| |
| ### More information: |
| |
| * [OTA Flow](https://fuchsia.dev/fuchsia-src/concepts/packages/ota) |
| * [Package overview](https://fuchsia.dev/fuchsia-src/concepts/packages/package) |
| * [Package updates](https://fuchsia.dev/fuchsia-src/concepts/packages/update_pkg) |
| * [Package metadata](https://fuchsia.dev/fuchsia-src/concepts/packages/package#meta-far) |
| * [Package URLs](https://fuchsia.dev/fuchsia-src/concepts/packages/package_url) |
| * [Software updates](https://fuchsia.dev/fuchsia-src/concepts/packages/software_update_system) |
