FFX is divided into some areas of responsibility, with core functionality
related to finding and running fuchsia-interacting programs being in the core
program (the ffx cli) and
the actual programs being built as 'subtools' (formerly plugins) that may either
be compiled in with the
ffx cli, or run as external tools (using the
FHO subtool interface).
In order to add functionality to be accessible through
ffx, you can write your
own subtools and integrate them into the build.
Get started with subtools
To get started building a simple subtool (formerly called plugins) for
developing an ffx subtool.
If you have an existing plugin and want or need to migrate it to the new subtool interface, take a look at migrating an existing plugin.
We also keep a reference implementation of a subtool that does some basic things
ffx-echo that should always act as
a canonical source of how to write a subtool.
New subtool checklist
If this is the start of a larger project, there are some things you should try to do to make sure your new subtool will work over time:
- Mark your new subtool as experimental to establish an expectation that it will be changing before stabilization.
- Use a
Writerfor all output related to your subtool. If inclusion in the SDK is expected at some point, make sure that you use a
MachineWriterwith a concrete serialize-able type and output works correctly when
--machine jsonis passed to
- Properly delineate between user-actionable errors and bugs at the subtool
boundary using the
- If the subtool lives in the
ffxtree, it should have a clear
OWNERSfile describing both the team that owns it and individuals who can check CLs against that tool.
- If it lives outside the
ffxtree, but inside the fuchsia.git repository, it must have the
ffx owners filereferenced (ie.
file:/src/developer/ffx/OWNERSin its OWNERS file) applying to any files at the api boundary between
ffxand the subtool so that we can make pro-active changes to that api boundary over time.
Legacy plugin references
If you're looking for information about the legacy plugin macro interface, see: