Generating code for an mobile application
The simplest invocation is in this form:
% nimbus-fml generate --language <LANGUAGE> --channel <CHANNEL> <INPUT> <OUTPUT>
CHANNELis one of the channels specified in the FML file.
INPUTmay be a local file or directory.
OUTPUTshould be a local file or directory.
INPUT is a directory, it is recursively searches for any files with names ending in
This command should be called at build time of components and the build time of the application.
Adding repo files can be done with one or more
% nimbus-fml generate --language <LANGUAGE> --repo-file ./app-structure.json <INPUT> <OUTPUT>
Getting different versions of the same manifest
For remote manifests, the default branch to fetch from is
main. This can be changed with the
ref is equivalent to taking the remote repo of the manifest path and creating a
repo-file with that repo mapped to the given
This command uses feature manifest from the
releases_v118 branch of the https://github.com/mozilla-mobile/firefox-android repository:
% nimbus-fml generate --language <LANGUAGE> --ref releases_v118 @mozilla-mobile/firefox-android/fenix/app/nimbus.fml.yaml <OUTPUT>
Caching remote files
% nimbus-fml generate --language <LANGUAGE> --channel CHANNEL --cache-dir ./build/cache-dir <INPUT> <OUTPUT>
import directives in the FML, a remote file may be referenced. The cache directory is a local cache of these remote files.
For each of the following,
--repo-file flags are supported.
Generating a manifest file for experimenter
The reason to use a custom manifest format a language specific JSON serialization library is to do with keeping the code in sync with the experimenter web server.
For legacy reasons, this is a different format of yaml file, which should be checked in to version control and is periodically pulled in by experimenter.
% nimbus-fml generate-experimenter <INPUT> <OUTPUT>
This should only be called at the application level, with the one main fml file as an input.
--repo-file arguments are also supported.
Validating a manifest file
% nimbus-fml validate <INPUT>
This gives a view of the validation process for all channels.
% nimbus-fml validate @mozilla-mobile/firefox-android/fenix/app/nimbus.fml.yaml
ℹ️ Loaded modules:
Validating manifest for different channels:
Re-write a complicated distributed manifest into a single file
The FML spec allows you to import and include dependencies' manifests. This is convenient for engineers to place the feature manifest close to where the feature code lives.
However, for some circumstances, it may not be good for packagers or distributers of the software: e.g. if the file is to be distributed with the software.
To help this, the
single-file command is used to merge all imports and includes into the top level file, with a single channel.
% nimbus-fml single-file --channel release @mozilla-mobile/firefox-android/fenix/app/nimbus.fml.yaml single-file.fml.yaml
Generating a machine readable overview of a feature
% nimbus-fml info [--channel CHANNEL] [--json] <MANIFEST> [--feature FEATURE]
This prints a simplified YAML or JSON representation for each feature. e.g.
"description": "The homescreen that the user goes to when they press home or new tab.",
hashes object shows truncated SHA256 hashes for:
- the schema (the types, variable names, the enum variants available)
- the defaults (the default values of the feature variables)
- Changes in the schema hash might indicate a change in the feature code.
- Changes in the defaults hash would indicate a different configuration being used for the same code.
- Changes in the schema hash will almost always be accompanied by a change in the defaults hash, with the exception of changing variable types from
Stringtype to a
string-aliastype (or vice-versa).
types list is a sorted list of the types involved used to define the feature. This list may be used as a proxy for a measure of complexity of the feature configuration space.
In addition, the feature metadata is also displayed.
--feature argument is supplied, then restrict the output to just this feature.
--channel argument is supplied, then use this channel. This will affect the
You can use
--json JQ to output some interesting data:
Get the features for this app:
% nimbus-fml info <INPUT> --json | jq '.features|keys'
Get the channels for this app:
% nimbus-fml channels <INPUT> --json
Get the hashes for just the
% nimbus-fml info <INPUT> --json | jq '.features.homescreen.hashes'
--repo-file arguments are also supported.