The ffx repository
commands can create and manage
Fuchsia package repositories on the host machine.
Concepts
When a Fuchsia device needs to run new software or update existing software, the device requests and downloads Fuchsia packages from a Fuchsia package server, which is a service that you can run on your host machine. The Fuchsia package server then serves Fuchsia packages from a Fuchsia package repository configured on the host machine.
A Fuchsia package repository is mapped to a directory on the host machine. When handling requests from Fuchsia devices, the Fuchsia package server looks for Fuchsia packages in this directory. If they're found, the package server serves the packages to the devices directly from this directory. Therefore, this directory on the host machine is where you'll want to store your in-development Fuchsia packages for target devices.
Once a new Fuchsia package repository is created, you need to register the package repository to your Fuchsia device (or devices), which permits the device to download Fuchsia packages from this package repository. Fuchsia devices can only download Fuchsia packages from their registered Fuchsia package repositories.
Lastly, you can set up the Fuchsia package server to serve from multiple Fuchsia package repositories on the same host machine, where you may dedicate each package repository for a specific purpose (for instance, to separate stable packages from experimental packages).
Create a package repository
To create and set up a new package repository on your host machine, do the following:
Create a new repository:
ffx repository create <REPOPATH>
Replace
REPO_PATH
with the directory path for the new repository.However, there is no check for existing contents in that directory, so make sure that the directory does not exist before running this command.
(Optional) Set the default name for the repository:
ffx repository default set <REPO_NAME>
Replace
REPO_NAME
with the name of a package repository, for example:ffx repository default set my-repo
This is typically not needed since the build directory level configuration of
ffx
already contains the correct value.After setting the default repository, this command exits silently without output.
Start a Fuchsia package server
To be able to serve packages from Fuchsia package repositories on your host machine, a Fuchsia package server must be running on the machine.
To start a new Fuchsia package server, run the following command:
ffx repository server start --foreground --repo-path <REPO_PATH>
Replace REPO_PATH
with the path to a product bundle on your host machine,
for example:
$ ffx repository server start --foreground --repo-path ~/my-product-bundle
Also, notice that this command starts the package server in the foreground
(--foreground
). This means the server's log messages will be printed to
the terminal window. Alternatively, you can start the package server in the
background by using the --background
option. In this case, the log messages
will be stored in the ${log.dir}/repo-REPO_NAME.log
file. For more options,
see Start package servers.
Start a Fuchsia package server using a product bundle
To serve packages from an existing product bundle, you need to download the product bundle and start the package server using the product bundle.
Do the following:
View the list of available products:
ffx product list
Download your desired product bundle:
ffx product download <PRODUCT> <DOWNLOAD_DIR>
Replace the following:
PRODUCT_NAME
: The product name of your target Fuchsia device.DOWNLOAD_DIR
: The directory where you want to download the product bundle.
For example:
S ffx product download core.x64 ~/Downloads/product-bundles/
Start the Fuchsia package server:
ffx repository server start --background --product-bundle <DOWNLOAD_DIR>
Replace
DOWNLOAD_DIR
with the directory that contains a product bundle, for example:$ ffx repository server start --background --product-bundle ~/Downloads/product-bundles
You can confirm it is a product bundle directory by checking the presence of
product.bundle.json
file in the directory. For more information, see Start package servers.
Register a package repository to a Fuchsia device
Once the package server is running, you need to register the server address to the target device.
Do the following:
Enable your Fuchsia device to connect to the new repository:
ffx target repository register [-r <REPO_NAME>] --alias fuchsia.com --alias chromium.org
Replace
REPO_NAME
with the name of the repository that you want the Fuchsia device to connect to.If the
-r
flag is not specified, the command selects the default repository. For example, thiscommand sets your current Fuchsia device to connect to the default repository (my-repo
) atfuchsia.com
:$ ffx target repository register --alias fuchsia.com --alias chromium.org
After registering the repository, this command exits silently without output.
Verify that the new repository is registered:
ffx target repository list
This command prints output similar to the following:
$ ffx target repository list REPO URL ALIASES fuchsia-pkg://default ["http://10.0.2.2:8083/my-repo"] ["fuchsia.com", "chromium.org"]
Deregister a package repository
To deregister a Fuchsia package repository from the device, run the following command:
ffx target repository deregister [-r <REPO_NAME>]
Replace REPO_NAME
with the name of a registered repository,
for example:
$ ffx target repository deregister -r my-repo
If the -r
option is not specified, the command selects the default
repository.
Stop a Fuchsia package server
To stop a running Fuchsia package server, run the following command:
ffx repository server stop
This command prints output similar to the following:
$ ffx repository server stop
server stopped
For more options, see Stop running package servers.
Create a package repository for a daemon-based package server
To create a new Fuchsia package repository on your host machine, do the following:
Create a new repository:
ffx repository create <REPO_PATH>
where
REPO_PATH
is the directory path for the new repository, for example:$ ffx repository create ~/my-fuchsia-packages
However, there is no check for existing contents in that directory, so make sure that the directory does not exist before running this command.
Add the new repository to the
ffx
configuration:ffx repository add-from-pm <PM_REPO_PATH> [-r <REPO_NAME>]
Replace the following:
PM_REPO_PATH
: The path to a directory where Fuchsia packages are stored.REPO_NAME
: A user-defined name for the new repository. If the-r
option is not specified, the command names the new repositorydevhost
by default.
This example command creates a new repository and names it
my-repo
:$ ffx repository add-from-pm ~/my-fuchsia-packages -r my-repo
After creating a new repository, this command exits silently without output.
Verify that the new repository is created:
ffx repository list
This command prints output similar to the following:
$ ffx repository list NAME TYPE ALIASES EXTRA my-repo pm /usr/alice/my-fuchsia-packages
(Optional) Set the new repository to be default:
ffx repository default set <REPO_NAME>
Replace
REPO_NAME
with the name of a repository, for example:$ ffx repository default set my-repo
This is typically not needed since the build directory level configuration of ffx will already contain the correct value.
After setting the default repository, this command exits silently without output.
For a Fuchsia device to start downloading Fuchsia packages from this new repository, you need to register this repository to the device.
Start a daemon-based package server
To start the Fuchsia package server that is based on ffx
daemon,
run the following command:
ffx repository server start --daemon
This command prints output similar to the following:
$ ffx repository server start --daemon
server is listening on [::]:8083
For more options, see Start package servers.
Remove a package repository for a daemon-based package server
To remove a Fuchsia package repository, run the following command:
ffx repository remove <REPO_NAME>
Replace REPO_NAME
with the name of a repository, for example:
$ ffx repository remove my-repo
After removing the repository, this command exits silently without output.