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 the Fuchsia package server, which is a service that you can start (and stop) on the 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 and, when they're found, it serves the packages from this directory. Therefore, this directory is often the destination where you'd generate and store Fuchsia packages related to your development.
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
Create a new repository:
ffx repository create <REPO_PATH>
where
REPO_PATH
is the directory path for the new repository. Note: There is no check for existing contents in that directory, so it is recommended that you check that the directory does not exist before running this command.Optionally set the default name for the repository:
ffx repository default set <REPO_NAME>
Replace
REPO_NAME
with the name of a repository.The example command below sets
my-repo
to be the default repository:$ 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.
Start the Fuchsia package server
To be able to serve packages from Fuchsia package repositories on your host machine, the Fuchsia package server must be running on the machine.
To start the Fuchsia package server, run the following command:
ffx repository server start --foreground --repo-path <REPO_PATH>
This will start a package server in the foreground. The log messages will appear in the terminal window.
Alternatively, the server can be started in the background by using the
--background
flag. In this case the log messages will appear in ${log.dir}/repo-REPO_NAME.log
For more options, see Start package servers.
Register a package repository to a Fuchsia device
Once the package server is running, the server address needs to be registered on the target device. T 1. 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 this flag is not specified, the command selects the default repository.
The example below sets your current Fuchsia device to connect to the default
repository (my-repo
) at fuchsia.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. If this flag is
not specified, the command selects the default repository.
The example command below deregisters the my-repo
repository:
$ ffx target repository deregister -r my-repo
Stop the Fuchsia package server
To stop the 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 the deprecated daemon based 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. Note: There is no check for existing contents in that directory, so it is recommended that you check 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 this flag is not specified, the command names the new repository
devhost
by default.
- If this flag is not specified, the command names the new repository
The example command below creates a new repository and adds it with the name
my-repo
:$ ffx repository create ~/my-fuchsia-packages $ 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
Optionally set the new repository to be default:
ffx repository default set <REPO_NAME>
Replace
REPO_NAME
with the name of a repository.The example command below sets
my-repo
to be the default repository:$ 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 stat downloading Fuchsia packages from this new repository, you need to register this repository to the device.
Register a package repository to a Fuchsia device
To enable a Fuchsia device to download packages from a Fuchsia package repository on your host machine, 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 this flag is not specified, the command selects the default repository.The example below 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. If this flag is
not specified, the command selects the default repository.
The example command below deregisters the my-repo
repository:
$ ffx target repository deregister -r my-repo
After deregistering the repository, this command exits silently without output.
Remove a package repository
To remove a Fuchsia package repository, run the following command:
ffx repository remove <REPO_NAME>
Replace REPO_NAME
with the name of a repository.
The example command below removes the my-repo
repository:
$ ffx repository remove my-repo
After removing the repository, this command exits silently without output.
Start the Fuchsia package server
To be able to serve packages from Fuchsia package repositories on your host machine, the Fuchsia package server must be running on the machine.
To start the Fuchsia package server, 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.
Stop the Fuchsia package server
To stop the 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.