Motivation

The idea of configuring external tools and forc plugins via the Forc.toml has been raised a few times recently, the fuel-indexer being the most recent (FuelLabs/fuel-indexer#89).

The goal is to allow for the most streamlined, smooth, batteries-included UX possible. Allowing for a single source of configuration could be a nice step towards this kind of experience.

That said, we also want to be careful not to unnecessarily conflate the role of forc itself with 3rd-party tools that are not always necessary for all projects. It's infeasible for forc to be aware of all possible use-cases of these 3rd-party tools, and it would be a never-ending can of worms if forc were to require constantly accepting PRs to its own manifest format to accommodate them, particularly as the ecosystem expands.

forc's approach to supporting plugins was inspired by the desire to solve extensibility in a similar manner, but only at the command level and not the configuration level.

Proposal - Support a metadata table in Forc.toml

I propose we follow cargo's lead and introduce the concept of a metadata table. The metadata table would be a dedicated table supported by forc that can be used to host custom configuration options for external tools.

It would explicitly not be forc's purview to parse or process any of the content under the metadata table itself. Instead, the idea would be to allow for 3rd-parties to use this table to host arbitrary configuration specifically for their external tools or plugins.

One of the major benefits of having a dedicated [metadata] table for this is that we can still lint the manifest and warn the user about unrecognised fields. Without such a check, unrecognised fields (e.g. caused by typos) have the potential to be difficult to spot, particularly as forc often supports default values in the case that the intended field was not present.

Conventions for [metadata]

If we are to support such a table, we should set some clear conventions for plugin developers from the beginning and document them under the forc plugins chapter.

Dedicated sub-tables

External tools should always use a dedicated sub-table under the metadata table. This is in order to clearly namespace their associated configuration and to avoid conflicts with other tools. E.g. always prefer:

[metadata.foo]
opt-1 = "bar"
opt-2 = "baz"

and never the following:

[metadata]
foo-opt-1 = "bar"
foo-opt-2 = "baz"

Resolving naming conflicts between two tools developed in isolation that happen to share the same name is explicitly outside of forc's responsibility and should be settled downstream.

Prioritise dedicated configuration files before Forc.toml

External tools should be very careful to not require a Forc.toml at all if their tool can at all be useful without it. The fuel-indexer would be a good example of such a tool.

External tools should support a "fallback" approach where they first check for configuration options within a dedicated configuration file before looking up the manifest and communicate this clearly to their users. E.g.

Our external tool will first check for a <plugin>.toml. If file or desired option is unavailable, we will then attempt to check for a Forc.toml and the relevant metadata.<plugin> table.

External tools planning to integrate configuration options in Forc.toml should consider also using the toml format in their dedicated configuration files. This would allow for a more consistent experience when moving configuration between a dedicated configuration file and a Forc.toml [metadata] entry.

Potential use-cases

Here are a few that come to mind:

• forc doc - customising generation of documentation (e.g. default themes/icons, enable documenting private items, etc).
• forc fmt - potentially host small sway formatting customisations e.g. for accessibility (otherwise discouraged).
• fuel-indexer - Fuel indexer configuration.
• forc wallet - configuration around custom wallet interop.
• forc dbg - debugger plugin configuration.

Bikeshedding

• Is [metadata] the best name? Possibly [plugin] or [extern] could be better? My inclination is that [metadata] is good enough and that it might be better to just follow Rust conventions and appease Rustacean expectations?

Implementation

Implementation should be pretty easy:

1. Document the above in the mdbook.
2. In forc_pkg::Manifest, explicitly ignore the metadata field during deserialization. Ensure it isn't linted as an unrecognised field.