flipperzero-firmware/documentation/fbt.md
Max Andreev 93a4b9c4a9
[FL-2649] Drop Docker in CI/CD (#1412)
* enable sparseCheckout, moving github actions from docker to raw shell
* fix missing known_hosts while setting ssh priv key
* fix build.yml
* add ssh key to upload just in time
* fixing rsync syntax
* fix build.yml
* try to fix build.yml again
* testing rsync
* test rsync again
* add linters
* add Black Python linter to submodules
* add Black submodule
* add working python linter target, dirty file list
* up toolchain to version 4
* up toolchain to ver 5
* up toolchain version to 6
* fbt: using black 22.6.0
* remove Black submodule, up toolchain to ver 7
* fbt: added lint_py, format_py targets
* add pvs_studio workflow
* fix pvs_studio segfault
* fix pvs_studio command
* fix pvs_studio command 2
* show env before run pvs_studio
* try to debug pvs_studio
* try to strace pvs_studio..
* Add FBT_TOOLCHAIN_PATH, MacOS Rosseta check, and ignore non-x86_64 linux architectures
* prevent redownloading toolchain on github-runners
* fix toolchain download exitcode
* add strace to debug pvs_studio segfault
* disable strace to catch full code dump
* Add './fbt cli' target to access Flipper CLI via PySerial
* remove pvs_studio from this PR
* removing clang-format from toolchain due errors
* make source easy, and fix some mistakes found by @hedger
* Add check_submodules workflow, some fixes
* fixing mistakes

Co-authored-by: hedger <hedger@nanode.su>
Co-authored-by: hedger <hedger@users.noreply.github.com>
2022-08-02 23:05:31 +09:00

5.6 KiB

Flipper Build Tool

FBT is the entry point for firmware-related commands and utilities. It is invoked by ./fbt in the firmware project root directory. Internally, it is a wrapper around scons build system.

Requirements

Please install Python packages required by assets build scripts: pip3 install -r scripts/requirements.txt Make sure that gcc-arm-none-eabi toolchain & OpenOCD executables are in system's PATH.

NB

  • fbt constructs all referenced environments & their targets' dependency trees on startup. So, to keep startup time as low as possible, we're hiding construction of certain targets behind command-line options.
  • fbt always performs git submodule update --init on start, unless you set FBT_NO_SYNC=1 in environment:
    • On Windows, that's set "FBT_NO_SYNC=1" in the shell you're running fbt from
    • On *nix, it's $ FBT_NO_SYNC=1 ./fbt ...
  • fbt builds updater & firmware in separate subdirectories in build, with their names depending on optimization settings (COMPACT & DEBUG options). However, for ease of integration with IDEs, latest built variant's directory is always linked as built/latest. Additionally, compile_commands.json is generated in that folder, which is used for code completion support in IDE.

Invoking FBT

To build with FBT, call it specifying configuration options & targets to build. For example,

./fbt COMPACT=1 DEBUG=0 VERBOSE=1 updater_package copro_dist

To run cleanup (think of make clean) for specified targets, add -c option.

FBT targets

FBT keeps track of internal dependencies, so you only need to build the highest-level target you need, and FBT will make sure everything they depend on is up-to-date.

High-level (what you most likely need)

  • fw_dist - build & publish firmware to dist folder. This is a default target, when no other are specified
  • updater_package, updater_minpackage - build self-update package. Minimal version only inclues firmware's DFU file; full version also includes radio stack & resources for SD card
  • copro_dist - bundle Core2 FUS+stack binaries for qFlipper
  • flash - flash attached device with OpenOCD over ST-Link
  • flash_usb, flash_usb_full - build, upload and install update package to device over USB. See details on updater_package, updater_minpackage
  • debug - build and flash firmware, then attach with gdb with firmware's .elf loaded
  • debug_other - attach gdb without loading any .elf. Allows to manually add external elf files with add-symbol-file in gdb
  • updater_debug - attach gdb with updater's .elf loaded
  • blackmagic - debug firmware with Blackmagic probe (WiFi dev board)
  • openocd - just start OpenOCD
  • get_blackmagic - output blackmagic address in gdb remote format. Useful for IDE integration
  • lint, format - run clang-tidy on C source code to check and reformat it according to .clang-format specs
  • lint_py, format_py - run black on Python source code, build system files & application manifests

Firmware targets

  • firmware_extapps - build all plug-ins as separate .elf files
    • firmware_snake_game, etc - build single plug-in as .elf by its name
    • Check out --extra-ext-apps for force adding extra apps to external build
    • firmware_snake_game_list, etc - generate source + assembler listing for app's .elf
  • flash, firmware_flash - flash current version to attached device with OpenOCD over ST-Link
  • jflash - flash current version to attached device with JFlash using J-Link probe. JFlash executable must be on your $PATH
  • flash_blackmagic - flash current version to attached device with Blackmagic probe
  • firmware_all, updater_all - build basic set of binaries
  • firmware_list, updater_list - generate source + assembler listing
  • firmware_cdb, updater_cdb - generate compilation_database.json file for external tools and IDEs. It can be created without actually building the firmware.

Assets

  • resources - build resources and their Manifest
    • dolphin_ext - process dolphin animations for SD card
  • icons - generate .c+.h for icons from png assets
  • proto - generate .pb.c+.pb.h for .proto sources
  • proto_ver - generate .h with protobuf version
  • dolphin_internal, dolphin_blocking - generate .c+.h for corresponding dolphin assets

Command-line parameters

  • --options optionfile.py (default value fbt_options.py) - load file with multiple configuration values
  • --with-updater - enables updater-related targets and dependency tracking. Enabling this option introduces extra startup time costs, so use it when bundling update packages. Explicily enabling this should no longer be required, fbt now has specific handling for updater-related targets
  • --extra-int-apps=app1,app2,appN - forces listed apps to be built as internal with firmware target
  • --extra-ext-apps=app1,app2,appN - forces listed apps to be built as external with firmware_extapps target

Configuration

Default configuration variables are set in the configuration file fbt_options.py. Values set on command-line have higher precedence over configuration file.

You can find out available options with ./fbt -h.

Firmware application set

You can create customized firmware builds by modifying the application list to be included in the build. Application presets are configured with the FIRMWARE_APPS option, which is a map(configuration_name:str -> application_list:tuple(str)). To specify application set to use in a build, set FIRMWARE_APP_SET to its name. For example, to build a firmware image with unit tests, run ./fbt FIRMWARE_APP_SET=unit_tests.

Check out fbt_options.py for details.