Note: This document describes the legacy plugin macro system and is here only as a reference while we still have some plugins using it around. See the top level ffx development docs for documentation on writing subtools.
When developing a new plugin, the experimental (or ‘work in progress’) nature of the work is indicated by marking the plugin as experimental.
Experimental plugins:
When defining a plugin function within the plugin lib.rs file, there will be an entry point decorated with ffx_plugin
such as:
#[ffx_plugin()]
or
#[ffx_plugin(MyProxy = "fuchsia.example.Service")]
To mark a plugin as experimental and simultaneously declare the token used to enable the experiment, add an initial string parameter. In the following example the tag “zippy” may (or may not) match the plugin command name. The label may be arbitrary, but it's recommended to choose a value that relates to the plugin:
#[ffx_plugin("zippy")]
or
#[ffx_plugin("zippy", MyProxy = "fuchsia.example.Service")]
In both examples above, the plugin will be guarded by a feature token named “zippy”. When users try to execute ffx zippy
they will be informed that zippy is experimental, then instructions for enabling the zippy feature will be shown.
After following the instructions to enable zippy, future calls (for that user) will operate as if zippy were not experimental, i.e. they have opted-in to using the zippy feature.
Experimental plugins must not be used as a mechanism to bypass code quality concerns, design, security, privacy and other concerns. Every element of ffx must adhere to a common base standard for inclusion in the IDK.
Before leaving the experimental state a plugin must have: