tree: bdc4c20ae6f3753f09a09e6af1a2e6079aa83160 [path history] [tgz]
  1. contrib/
  2. lib/
  3. test/
  4. add-update-source
  5. aemu
  6. args
  7. build
  8. build-push
  9. clean
  10. clean-build
  11. cp
  12. doctor
  13. emu
  14. exec
  15. fdt
  16. flash
  17. gen
  18. get-build-dir
  19. get-device
  20. get-device-addr
  21. list-boards
  22. list-packages
  23. list-products
  24. list-usb-disks
  25. log
  26. metrics
  27. metrics_testing.md
  28. mkzedboot
  29. multi
  30. netaddr
  31. netboot
  32. netls
  33. ninjatrace2json
  34. ota
  35. OWNERS
  36. pave
  37. pave-zedboot
  38. push-package
  39. qemu
  40. README.md
  41. reboot
  42. run
  43. run-host-tests
  44. run-netboot
  45. run-test
  46. run-test-component
  47. scp
  48. serial
  49. serve
  50. serve-updates
  51. set
  52. set-build-dir
  53. set-device
  54. setup-macos
  55. setup-ufw
  56. sftp
  57. shell
  58. ssh
  59. status
  60. symbolize
  61. syslog
  62. unset-device
  63. update
  64. use
  65. vendor
  66. wait
tools/devshell/README.md

fx subcommands

Sub-commands of fx are defined in several directories:

//tools/devshell contains core scripts that are part of the supported fx workflow.

//tools/devshell/contrib contains scripts that have been contributed by team members that have other levels of support and/or ownership. The OWNERS file in the contrib directory provides a pointer to the individuals supporting the scripts there.

//vendor/*/scripts/devshell contains scripts that are relevant only to the particular vendor and will have an ownership and support model documented there.

Sub-commands can be implemented in a number of languages, but it is recommended to use bash at this time, so as to be able to consume some of the helpers provided by //tools/devshell/lib/vars.sh.

It is recommended that scripts be kept short and simple. Authoring large shell programs without a significant test plan can lead to hard to maintain tools. If there is a need to produce a more sophisticated program the recommended approach is to author a host tool program as part of the regular Fuchsia build, and only to wrap that program in a very slim way in a script. Examples of such cases can be found in fx pave and fx make-fuchsia-vol. A good rule of thumb here is that if a script only needs to launch and manage a one or a few sub-processes, then shell may be a fine language. If the program needs to perform any significant string manipulation or business logic, it is likely better authored in a language that provides more structural capabilities and standard library.

Consuming vars.sh / Implementing Subcommands

Most subcommands start with a pre-amble of this nature (paths vary slightly):

source "$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"/../lib/vars.sh || exit $?
fx-config-read

This pre-amble ensures that the devshell helpers are loaded, and then reads the active fx configuration from the user-selected Fuchsia build directory.

fx-config-read is required for most environment variables to be set, and is necessary for most scripts.

Helper functions

fx-config-read loads the current user configuration that is either defined by the fx configuration modulated by fx set and fx use, or by flags to fx such as --config and --dir. It is necessary as a pre-amble for any script that wants to consume build artifacts, as it defined most of the standard environment variables such as $FUCHSIA_BUILD_DIR.

fx-error and fx-warn simply print their arguments, prefixing them with ERROR: or WARNING: respectively. If the output stream supports color, then these outputs are colored.

fx-command-run and fx-command-exec execute another fx subcommand, for example, running fx-command-run shell will invoke the fx shell command. The run variant executes the subcommand in a subshell and the exec variant execs the subcommand, replacing the calling process.

fx-command-help prints the command output for the currently running subcommand.

TODO(raggi): rename the following two functions:

get-device-name returns either the device name that the user has set with fx set-device or fx -d <device-name>. If the user has not set a default device, the command will run device discovery, and will return a discovered device name provided there is only one device discovered.

get-fuchsia-device-addr consumes get-device-name and returns the Fuchsia IPv6 address of the device. The returned address is the “netstack address”, not the “netsvc address”.

The vars.sh script may define additional functions, however, they are considered internal and may change more often. Users can request additional helper functions by contacting the devshell owners, or by defining their own library scripts in contrib.

Environment Variables

After a successful invocation of fx-config-read in a script, one would observe the following environment variables:

FUCHSIA_ARCH         - The current architecture selected (currently one of x64/arm64)
FUCHSIA_BUILD_DIR    - The path to the current Fuchsia build directory
FUCHSIA_DIR          - The path to the root of the Fuchsia source tree
FUCHSIA_OUT_DIR      - (deprecated) "$FUCHSIA_DIR/out"
ZIRCON_BUILDROOT     - The path to the Zircon build directory
ZIRCON_TOOLS_DIR     - The path to the Zircon host-tools build directory.

fx-config-read and/or fx could set additional environment variables, but users should not rely on them - only the above list are to be preserved (unless marked deprecated).

Documenting Subcommands

As many fx subcommands delegate to sub-programs passing on flags directly to them, it is prohibitive to always be able to respond to the -h or --help flags. As such fx subcommands SHOULD implement -h and --help if possible, but this is not required.

It is required that all subcommands implement help documentation lines, which are defined as follows:

### a short one-line (<70 character) description for the command lines
## usage: fx <subcommand> [-a|-b|-c] --foo ...
##
## Long descriptions, flags, and so on

The first line starting with ### is consumed by fx help to produce a list of commands with one-line descriptions of what the command does. These lines should be kept short so as to render well under fx help.

Lines starting with ## are output when a user invokes fx help subcommand, and are used to provide full command help output. The long form output should document all flags and provide fuller description of the command behaviors as appropriate.

Where possible, a command can use fx-command-help to print out the long-form help (defined by ## lines). Many commands implement -h and --help to invoke fx-command-help and this is recommended.

Testing

Whenever possible, subcommands should have corresponding unit tests in //scripts/tests/. There are helper functions in //scripts/tests/lib/common.sh.

End-to-end manual testing should be documented in separate files in this directory, and listed below.