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' 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 for ffx
, see
developing an ffx subtool.
We also keep a reference implementation of a subtool that does some basic things
called 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
Writer
for all output related to your subtool. If inclusion in the SDK is expected at some point, make sure that you use aMachineWriter
with a concrete serialize-able type and output works correctly when--machine json
is passed toffx
. - Properly delineate between user-actionable errors and bugs at the subtool
boundary using the
fho::Error
type. - If the subtool lives in the
ffx
tree, it should have a clearOWNERS
file describing both the team that owns it and individuals who can check CLs against that tool. - If it lives outside the
ffx
tree, but inside the fuchsia.git repository, it must have theffx owners file
referenced (ie.file:/src/developer/ffx/OWNERS
in its OWNERS file) applying to any files at the api boundary betweenffx
and the subtool so that we can make pro-active changes to that api boundary over time.