docs/development/build/package_update.md - fuchsia - Git at Google

 # Developing with Fuchsia packages

 This document explains the basics of Fuchsia product development using
 [Fuchsia packages][packages].

 ## Overview

 A [Fuchsia package][fuchsia-packages] is a hierarchical collection of files and
 resourcesthat provides one or more programs, components or services to a Fuchsia
 system. Whether it is immediately apparent or not, almost everything you see on
 Fuchsia lives in a Fuchsia package.

 During Fuchsia product development, if you want to make new software available
 to your target Fuchsia device, you can build a Fuchsia package to include changes
 and publish it to a local package server running on your development host machine.
 Then the Fuchsia device will download the package and update the software.

 In this setup, your development host machine runs a simple static file HTTP
 server that makes Fuchsia packages available to the target device. This HTTP
 server (which is referred to as the
 [Fuchsia package server][fuchsia-package-server]) is part of the Fuchsia source
 code and is built automatically when the `fx build` command is run.

 Fuchsia target devices are usually configured to look for changes on the
 Fuchsia package server. When the update system on a target device sees
 changes, it fetches the new package from the package server. Once the package
 is downloaded, the new software in the package becomes available on the target
 device.

 ## Prerequisites

 Your development host machine and Fuchsia target device must be able to
 communicate over TPC/IP. In particular, it must be possible to establish
 an SSH connection from the development host machine to the target device.
 This SSH connection is used to issue commands to the target device.

 ## Building packages

 For building a package containing your code in the Fuchsia source checkout,
 you need to specify a package build rule. For more details on adding build
 rules for a package, see [Fuchsia build system][pkg-doc].

 Once an appropriate build rule is added, run the following command to
 generate your package:

 ```posix-terminal
 fx build
 ```

 ## Inspecting packages

 Fuchsia comes with the `ffx` tool to work with package archives. After the
 completion of a [Fuchsia build][fuchsia-build] (`fx build`), you can use the
 [`ffx package archive`][ffx-package-archive] command to create, list, dump or
 extract package archives, for example:

 ```posix-terminal
 ffx package archive list
 ```

 The `ffx package archive list` command example below lists the contents
 of a package named `meta.far` in the
 `~/fuchsia/out/default/obj/third_party/sbase/sed_pkg/` directory:

 ```none {:.devsite-disable-click-to-copy}
 $ ffx package archive list ~/fuchsia/out/default/obj/third_party/sbase/sed_pkg/meta.far
 +-------------------------------+
 | NAME                          |
 +===============================+
 | meta/contents                 |
 +-------------------------------+
 | meta/fuchsia.abi/abi-revision |
 +-------------------------------+
 | meta/package                  |
 +-------------------------------+
 ```

 Notice that this `meta.far` package contains a file named `meta/contents`.
 The `meta/contents` file maps the package's user-facing filenames to
 the merkle root of those files, for example:

 ```none {:.devsite-disable-click-to-copy}
 $ ffx package archive cat ~/fuchsia/out/default/obj/third_party/sbase/sed_pkg/meta.far meta/contents
 bin/sed=361c6e3a027cf38af0d53e1009ef3b3448f4aeb60270910a116396f5ec8eccba
 lib/ld.so.1=c8ec55a14590e7e6f06f311d632744012f85084968d98a335c778f29207caa14
 lib/libc++.so.2=d8a45259c74cf65c1f8470ac043c6459403fdd0bbf676092ba82f36451e4e571
 lib/libc++abi.so.1=f12b37c2b9bfb43fbe33d446794a6ffeee1452b16b7c8d08b3438f3045d1f19a
 lib/libfdio.so=9834d890adedc8e532899a673092271e394458e98e6cee049cb78f5a95372b11
 lib/libunwind.so.1=89e5dee07ff8d2a03c58d524d8d832e79c70dcb81508f8a83c6fbf07e1539e83
 ```

 For more details on Fuchsia packages and their contents,
 see [Structure of a package][pkg-struct].

 ## Managing package servers

 Virtually all software running on a Fuchsia system is collected into Fuchsia
 packages. Beyond the base packages that comprise the foundation of the Fuchsia
 platform, additional packages can be downloaded from the
 [Fuchsia package server][fuchsia-package-server]. The Fuchsia package server is
 an HTTP(S) server managing Fuchsia packages using TUF (The Update Framework).
 This framework uses cryptographically signed BLOBs to securely distribute
 updated packages to devices running Fuchsia.

 For more information on how to start, stop, and list Fuchsia package servers
 running on your development host machine, see the following guides:

 * [Start package servers][start-package-servers]
 * [List running package servers][list-package-servers]
 * [Stop running package servers][stop-package-servers]

 ## Connecting host and target

 The [Fuchsia source checkout][fuchsia-source] (`fuchsia.git`) contains the Fuchsia
 package server, a simple HTTP server that serves static files. And a Fuchsia build
 generates and serves a [TUF][TUF-home] file tree to the server.

 The update agent on a target Fuchsia device does not initially know where to
 look for updates. To connect the update agent on the target to the package server
 running on the development host machine, the target must be told the IP address
 of the development host machine.

 By default, the Fuchsia package server automatically registers itself with the
 default target. This behavior can be disabled by using the `--no-device` option
 when starting the server.

 The following commands are used for managing package repositories on target
 devices:

 * [`ffx target repository list`][ffx-target-repo-list]: Inspect registered
   package repositories on a target device.
 * [`ffx target repository register`][ffx-target-repo-register]: Register a new
   package repository or update an existing entry.
 * [`ffx target repository deregister`][ffx-target-repo-deregister]: Remove a
   package repository registration from a target device.

 To start the Fuchsia package server and configure the update agent on target
 devices, you can run the following command (or simply `fx serve`):

 ```posix-terminal
 fx serve -v
 ```

 The `fx serve` command runs the package server and is often what developers use.
 However, the `-v` option is recommended because it allows the command to print
 more output, which can help you with debugging. If the packager server connects
 successfully to the target devices, the command prints the
 `Ready to push packages!` message in the shell on the development host machine.

 The update agent on a target device remains configured until it is re-flashed.
 The Fuchsia package server attempts to reconfigure the update agent when the
 target device is rebooted.

 ## Triggering package updates

 In Fuchsia, packages are not "installed" but they are cached on an as-needed
 basis.

 There are two collections of packages in a Fuchsia ecosystem:

 * **Base**: The `base` package set is a group of software critical to proper
   system function that must remain congruent. The Fuchsia build system
   assigns packages to `base` when they are provided to the `fx set` command
   using the `--with-base` flag.

   This type of software can only be updated by performing a whole system update,
   typically referred to as an OTA (Over The Air) update, which is performed
   using the `fx ota` command.

 * **Ephemeral software**: Packages included in the `cache` or `universe` package
   set are ephemeral software. These updates are delivered on demand. The Fuchsia
   build system assigns packages to `universe` when they are provided to the
   `fx set` command using the `--with` flag.

   Ephemeral software is updated to the latest available versions when new
   packages are fetched to the target.

 The following commands are used for publishing Fuchsia packages and updating
 target devices:

 * [`fx serve`][fx-serve]: Run the Fuchsia package server locally for both
   build-push and OTA to target devices.
 * [`fx ota`][fx-ota]: Trigger a full system update and reboot on target
   devices.
 * [`fx test`][fx-test]: Build and run tests for testing target devices.

 ## Triggering an OTA

 Sometimes there may be many packages changed. For instance, the kernel may
 change or there may be changes in the system package. To introduce kernel
 changes or changes in the system package to target devices, an OTA or flashing
 is required since `base` packages are immutable for the runtime of a system.
 (An OTA update will usually be faster than flashing the device.)

 To trigger an OTA update to your target devices, run the following command:

 ```posix-terminal
 fx ota
 ```

 The `fx ota` command asks the target device to perform an update from any of
 the update sources available to it. To OTA update a build on the development
 host machine to a target device on the same LAN, you first need to build the
 system (`fx build`). Once the build is finished, if the `fx serve [-v]`
 command isn't already running on your development host machine, run the
 command so the target device can use the Fuchsia package server as an update
 source. The `-v` option prints more information about the files that the
 target device is requesting from the package server. With the `-v` option,
 there will be a flurry of output as the target device retrieves all the new
 files.

 After completing the OTA, the target device will reboot.

 ## Issues and considerations

 Consider the following issues that can occur while working with Fuchsia
 packages.

 ### You can fill up your disk

 Every update pushed is stored in the content-addressed file system, `blobfs`.
 Following a reboot, the updated packages may not be available because the
 index that locates them in `blobfs` is only held in RAM. The system currently
 does not [garbage collect][gc] inaccessible or no-longer-used packages (having
 garbage to collect is a recent innovation!), but will eventually.

 The `fx gc` command will reboot the target device and then evict all old
 ephemeral software from the device, freeing up space.

 ### Restarting without rebooting

 If the package being updated hosts a service managed by Fuchsia, that service
 may need to be restarted. Rebooting is undesirable because both it is slow and
 the package will revert to the version flashed on the device. Typically
 a developer can terminate one or more running components on the system, either
 by asking the component to terminate gracefully, or by forcefully stopping the
 component using the [`ffx component stop`][ffx-component-stop] command. Upon
 reconnection to the component services, or by invocation via
 `ffx component start` or `fx test`, new versions available in the package server
 will be cached before launch.

 ### Packaging code outside the Fuchsia tree

 Packaging and pushing code that lives outside the Fuchsia tree is possible, but
 will require more work. The Fuchsia package format is quite simple. It consists
 of a metadata file describing the package contents, which is described in more
 detail in the [Fuchsia package][pkg-struct] documentation. The metadata file is
 added to a TUF file tree and each of the contents are named after their merkle
 root hash and put in a directory at the root of the TUF file tree called `blobs`.

 <!-- Reference links -->

 [packages]: /docs/concepts/packages/README.md
 [fuchsia-packages]: /docs/concepts/packages/package.md
 [pkg-struct]: /docs/concepts/packages/package.md#structure-of-a-package
 [TUF-home]: https://theupdateframework.github.io "TUF Homepage"
 [pkg-doc]: /docs/development/build/build_system/fuchsia_build_system_overview.md
 [fuchsia-build]: /docs/get-started/learn/build/build-system.md
 [ffx-target-repo-list]: https://fuchsia.dev/reference/tools/sdk/ffx#ffx_target_repository_list
 [ffx-target-repo-register]: https://fuchsia.dev/reference/tools/sdk/ffx#ffx_target_repository_register
 [ffx-target-repo-deregister]: https://fuchsia.dev/reference/tools/sdk/ffx#ffx_target_repository_deregister
 [fuchsia-package-server]: /docs/concepts/packages/fuchsia_package_server.md
 [ffx-package-archive]: https://fuchsia.dev/reference/tools/sdk/ffx#ffx_package_archive
 [fx-serve]: https://fuchsia.dev/reference/tools/fx/cmd/serve
 [fx-ota]: https://fuchsia.dev/reference/tools/fx/cmd/ota
 [fx-test]: https://fuchsia.dev/reference/tools/fx/cmd/test
 [start-package-servers]: /docs/development/tools/ffx/workflows/start-package-servers.md
 [list-package-servers]: /docs/development/tools/ffx/workflows/list-package-servers.md
 [stop-package-servers]: /docs/development/tools/ffx/workflows/stop-package-servers.md
 [fuchsia-source]: /docs/get-started/get_fuchsia_source.md
 [gc]: /docs/concepts/packages/garbage_collection.md
 [ffx-component-stop]: /docs/development/tools/ffx/workflows/start-a-component-during-development.md#stop-a-component
	# Developing with Fuchsia packages

	This document explains the basics of Fuchsia product development using
	[Fuchsia packages][packages].

	## Overview

	A [Fuchsia package][fuchsia-packages] is a hierarchical collection of files and
	resourcesthat provides one or more programs, components or services to a Fuchsia
	system. Whether it is immediately apparent or not, almost everything you see on
	Fuchsia lives in a Fuchsia package.

	During Fuchsia product development, if you want to make new software available
	to your target Fuchsia device, you can build a Fuchsia package to include changes
	and publish it to a local package server running on your development host machine.
	Then the Fuchsia device will download the package and update the software.

	In this setup, your development host machine runs a simple static file HTTP
	server that makes Fuchsia packages available to the target device. This HTTP
	server (which is referred to as the
	[Fuchsia package server][fuchsia-package-server]) is part of the Fuchsia source
	code and is built automatically when the `fx build` command is run.

	Fuchsia target devices are usually configured to look for changes on the
	Fuchsia package server. When the update system on a target device sees
	changes, it fetches the new package from the package server. Once the package
	is downloaded, the new software in the package becomes available on the target
	device.

	## Prerequisites

	Your development host machine and Fuchsia target device must be able to
	communicate over TPC/IP. In particular, it must be possible to establish
	an SSH connection from the development host machine to the target device.
	This SSH connection is used to issue commands to the target device.

	## Building packages

	For building a package containing your code in the Fuchsia source checkout,
	you need to specify a package build rule. For more details on adding build
	rules for a package, see [Fuchsia build system][pkg-doc].

	Once an appropriate build rule is added, run the following command to
	generate your package:

	```posix-terminal
	fx build
	```

	## Inspecting packages

	Fuchsia comes with the `ffx` tool to work with package archives. After the
	completion of a [Fuchsia build][fuchsia-build] (`fx build`), you can use the
	[`ffx package archive`][ffx-package-archive] command to create, list, dump or
	extract package archives, for example:

	```posix-terminal
	ffx package archive list
	```

	The `ffx package archive list` command example below lists the contents
	of a package named `meta.far` in the
	`~/fuchsia/out/default/obj/third_party/sbase/sed_pkg/` directory:

	```none {:.devsite-disable-click-to-copy}
	$ ffx package archive list ~/fuchsia/out/default/obj/third_party/sbase/sed_pkg/meta.far
	+-------------------------------+
	\| NAME \|
	+===============================+
	\| meta/contents \|
	+-------------------------------+
	\| meta/fuchsia.abi/abi-revision \|
	+-------------------------------+
	\| meta/package \|
	+-------------------------------+
	```

	Notice that this `meta.far` package contains a file named `meta/contents`.
	The `meta/contents` file maps the package's user-facing filenames to
	the merkle root of those files, for example:

	```none {:.devsite-disable-click-to-copy}
	$ ffx package archive cat ~/fuchsia/out/default/obj/third_party/sbase/sed_pkg/meta.far meta/contents
	bin/sed=361c6e3a027cf38af0d53e1009ef3b3448f4aeb60270910a116396f5ec8eccba
	lib/ld.so.1=c8ec55a14590e7e6f06f311d632744012f85084968d98a335c778f29207caa14
	lib/libc++.so.2=d8a45259c74cf65c1f8470ac043c6459403fdd0bbf676092ba82f36451e4e571
	lib/libc++abi.so.1=f12b37c2b9bfb43fbe33d446794a6ffeee1452b16b7c8d08b3438f3045d1f19a
	lib/libfdio.so=9834d890adedc8e532899a673092271e394458e98e6cee049cb78f5a95372b11
	lib/libunwind.so.1=89e5dee07ff8d2a03c58d524d8d832e79c70dcb81508f8a83c6fbf07e1539e83
	```

	For more details on Fuchsia packages and their contents,
	see [Structure of a package][pkg-struct].

	## Managing package servers

	Virtually all software running on a Fuchsia system is collected into Fuchsia
	packages. Beyond the base packages that comprise the foundation of the Fuchsia
	platform, additional packages can be downloaded from the
	[Fuchsia package server][fuchsia-package-server]. The Fuchsia package server is
	an HTTP(S) server managing Fuchsia packages using TUF (The Update Framework).
	This framework uses cryptographically signed BLOBs to securely distribute
	updated packages to devices running Fuchsia.

	For more information on how to start, stop, and list Fuchsia package servers
	running on your development host machine, see the following guides:

	* [Start package servers][start-package-servers]
	* [List running package servers][list-package-servers]
	* [Stop running package servers][stop-package-servers]

	## Connecting host and target

	The [Fuchsia source checkout][fuchsia-source] (`fuchsia.git`) contains the Fuchsia
	package server, a simple HTTP server that serves static files. And a Fuchsia build
	generates and serves a [TUF][TUF-home] file tree to the server.

	The update agent on a target Fuchsia device does not initially know where to
	look for updates. To connect the update agent on the target to the package server
	running on the development host machine, the target must be told the IP address
	of the development host machine.

	By default, the Fuchsia package server automatically registers itself with the
	default target. This behavior can be disabled by using the `--no-device` option
	when starting the server.

	The following commands are used for managing package repositories on target
	devices:

	* [`ffx target repository list`][ffx-target-repo-list]: Inspect registered
	package repositories on a target device.
	* [`ffx target repository register`][ffx-target-repo-register]: Register a new
	package repository or update an existing entry.
	* [`ffx target repository deregister`][ffx-target-repo-deregister]: Remove a
	package repository registration from a target device.

	To start the Fuchsia package server and configure the update agent on target
	devices, you can run the following command (or simply `fx serve`):

	```posix-terminal
	fx serve -v
	```

	The `fx serve` command runs the package server and is often what developers use.
	However, the `-v` option is recommended because it allows the command to print
	more output, which can help you with debugging. If the packager server connects
	successfully to the target devices, the command prints the
	`Ready to push packages!` message in the shell on the development host machine.

	The update agent on a target device remains configured until it is re-flashed.
	The Fuchsia package server attempts to reconfigure the update agent when the
	target device is rebooted.

	## Triggering package updates

	In Fuchsia, packages are not "installed" but they are cached on an as-needed
	basis.

	There are two collections of packages in a Fuchsia ecosystem:

	* Base: The `base` package set is a group of software critical to proper
	system function that must remain congruent. The Fuchsia build system
	assigns packages to `base` when they are provided to the `fx set` command
	using the `--with-base` flag.

	This type of software can only be updated by performing a whole system update,
	typically referred to as an OTA (Over The Air) update, which is performed
	using the `fx ota` command.

	* Ephemeral software: Packages included in the `cache` or `universe` package
	set are ephemeral software. These updates are delivered on demand. The Fuchsia
	build system assigns packages to `universe` when they are provided to the
	`fx set` command using the `--with` flag.

	Ephemeral software is updated to the latest available versions when new
	packages are fetched to the target.

	The following commands are used for publishing Fuchsia packages and updating
	target devices:

	* [`fx serve`][fx-serve]: Run the Fuchsia package server locally for both
	build-push and OTA to target devices.
	* [`fx ota`][fx-ota]: Trigger a full system update and reboot on target
	devices.
	* [`fx test`][fx-test]: Build and run tests for testing target devices.

	## Triggering an OTA

	Sometimes there may be many packages changed. For instance, the kernel may
	change or there may be changes in the system package. To introduce kernel
	changes or changes in the system package to target devices, an OTA or flashing
	is required since `base` packages are immutable for the runtime of a system.
	(An OTA update will usually be faster than flashing the device.)

	To trigger an OTA update to your target devices, run the following command:

	```posix-terminal
	fx ota
	```

	The `fx ota` command asks the target device to perform an update from any of
	the update sources available to it. To OTA update a build on the development
	host machine to a target device on the same LAN, you first need to build the
	system (`fx build`). Once the build is finished, if the `fx serve [-v]`
	command isn't already running on your development host machine, run the
	command so the target device can use the Fuchsia package server as an update
	source. The `-v` option prints more information about the files that the
	target device is requesting from the package server. With the `-v` option,
	there will be a flurry of output as the target device retrieves all the new
	files.

	After completing the OTA, the target device will reboot.

	## Issues and considerations

	Consider the following issues that can occur while working with Fuchsia
	packages.

	### You can fill up your disk

	Every update pushed is stored in the content-addressed file system, `blobfs`.
	Following a reboot, the updated packages may not be available because the
	index that locates them in `blobfs` is only held in RAM. The system currently
	does not [garbage collect][gc] inaccessible or no-longer-used packages (having
	garbage to collect is a recent innovation!), but will eventually.

	The `fx gc` command will reboot the target device and then evict all old
	ephemeral software from the device, freeing up space.

	### Restarting without rebooting

	If the package being updated hosts a service managed by Fuchsia, that service
	may need to be restarted. Rebooting is undesirable because both it is slow and
	the package will revert to the version flashed on the device. Typically
	a developer can terminate one or more running components on the system, either
	by asking the component to terminate gracefully, or by forcefully stopping the
	component using the [`ffx component stop`][ffx-component-stop] command. Upon
	reconnection to the component services, or by invocation via
	`ffx component start` or `fx test`, new versions available in the package server
	will be cached before launch.

	### Packaging code outside the Fuchsia tree

	Packaging and pushing code that lives outside the Fuchsia tree is possible, but
	will require more work. The Fuchsia package format is quite simple. It consists
	of a metadata file describing the package contents, which is described in more
	detail in the [Fuchsia package][pkg-struct] documentation. The metadata file is
	added to a TUF file tree and each of the contents are named after their merkle
	root hash and put in a directory at the root of the TUF file tree called `blobs`.

	<!-- Reference links -->

	[packages]: /docs/concepts/packages/README.md
	[fuchsia-packages]: /docs/concepts/packages/package.md
	[pkg-struct]: /docs/concepts/packages/package.md#structure-of-a-package
	[TUF-home]: https://theupdateframework.github.io "TUF Homepage"
	[pkg-doc]: /docs/development/build/build_system/fuchsia_build_system_overview.md
	[fuchsia-build]: /docs/get-started/learn/build/build-system.md
	[ffx-target-repo-list]: https://fuchsia.dev/reference/tools/sdk/ffx#ffx_target_repository_list
	[ffx-target-repo-register]: https://fuchsia.dev/reference/tools/sdk/ffx#ffx_target_repository_register
	[ffx-target-repo-deregister]: https://fuchsia.dev/reference/tools/sdk/ffx#ffx_target_repository_deregister
	[fuchsia-package-server]: /docs/concepts/packages/fuchsia_package_server.md
	[ffx-package-archive]: https://fuchsia.dev/reference/tools/sdk/ffx#ffx_package_archive
	[fx-serve]: https://fuchsia.dev/reference/tools/fx/cmd/serve
	[fx-ota]: https://fuchsia.dev/reference/tools/fx/cmd/ota
	[fx-test]: https://fuchsia.dev/reference/tools/fx/cmd/test
	[start-package-servers]: /docs/development/tools/ffx/workflows/start-package-servers.md
	[list-package-servers]: /docs/development/tools/ffx/workflows/list-package-servers.md
	[stop-package-servers]: /docs/development/tools/ffx/workflows/stop-package-servers.md
	[fuchsia-source]: /docs/get-started/get_fuchsia_source.md
	[gc]: /docs/concepts/packages/garbage_collection.md
	[ffx-component-stop]: /docs/development/tools/ffx/workflows/start-a-component-during-development.md#stop-a-component