Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/flipperdevices/flipperzero-ufbt-action
Official ufbt Action wrapper for building Flipper Zero applications
https://github.com/flipperdevices/flipperzero-ufbt-action
fap faps flipper-plugin flipper-zero flipperzero
Last synced: about 1 month ago
JSON representation
Official ufbt Action wrapper for building Flipper Zero applications
- Host: GitHub
- URL: https://github.com/flipperdevices/flipperzero-ufbt-action
- Owner: flipperdevices
- Created: 2023-04-10T20:57:26.000Z (over 1 year ago)
- Default Branch: dev
- Last Pushed: 2024-03-06T21:26:48.000Z (10 months ago)
- Last Synced: 2024-11-13T16:46:04.622Z (about 2 months ago)
- Topics: fap, faps, flipper-plugin, flipper-zero, flipperzero
- Homepage: https://github.com/marketplace/actions/build-flipper-application-package-fap
- Size: 29.3 KB
- Stars: 99
- Watchers: 9
- Forks: 10
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
## GitHub Action for [ufbt, micro Flipper Build Tool](https://pypi.org/project/ufbt/)
This action brings all features of [ufbt](https://pypi.org/project/ufbt/) to GitHub Workflows. It is used to build applications for [Flipper Zero](https://flipperzero.one/). Building applications with `ufbt` is much faster than using `fbt` with [full firmware sources](https://github.com/flipperdevices/flipperzero-firmware), and it allows you to build applications for different versions of the firmware, including unofficial ones.
This action and has 3 modes of operation:
* **application builder**: builds .fap (Flipper Application Package) file for the application in specified directory and returns a list of built files;
* **linter**: runs linter (`clang-format`) on application's sources;
* **ufbt setup**: makes `ufbt` available in the environment, without running any tasks. This mode is used to set up `ufbt` command and SDK for other steps in the workflow.
You can use [all SDK update modes](https://github.com/flipperdevices/flipperzero-ufbt/blob/dev/README.md#managing-the-sdk) supported by `ufbt`, including downloads from unofficial sources. See [SDK source options](#sdk-source-options) for action inputs used to specify SDK origin.
> This action caches toolchain used for `ufbt` operations, so it can be reused without being re-downloaded in subsequent runs of workflows in your repository.
## Usage
To build your application with this action, you must create a workflow file in your repository. Place a file named `.github/workflows/build.yml` with one of the examples below, and, optionally, tune it to your needs.
### Basic example: build and lint
This example will build your application for bleeding edge version, `dev`, of the official firmware, and upload generated binaries to GitHub artifacts. It will also run linter on your sources and fail the workflow if there are any formatting errors.
```yaml
name: "FAP: Build and lint"
on: [push, pull_request]
jobs:
ufbt-build-action:
runs-on: ubuntu-latest
name: 'ufbt: Build for Dev branch'
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Build with ufbt
uses: flipperdevices/[email protected]
id: build-app
with:
# Set to 'release' to build for latest published release version
sdk-channel: dev
- name: Upload app artifacts
uses: actions/upload-artifact@v3
with:
name: ${{ github.event.repository.name }}-${{ steps.build-app.outputs.suffix }}
path: ${{ steps.build-app.outputs.fap-artifacts }}
# You can remove this step if you don't want to check source code formatting
- name: Lint sources
uses: flipperdevices/[email protected]
with:
# skip SDK setup, we already did it in previous step
skip-setup: true
task: lint
```
### Advanced example: build for multiple SDK sources
This example will build your application for 3 different SDK sources: `dev` and `release` channels of official firmware, and for an SDK from an unofficial source. It will upload generated binaries to GitHub artifacts. It will also do a build every day, even if there are no new commits in the repository, so you can be sure that your application is always up to date with the latest SDK.
```yaml
name: "FAP: Build for multiple SDK sources"
on:
push:
## put your main branch name under "braches"
#branches:
# - master
pull_request:
schedule:
# do a build every day
- cron: "1 1 * * *"
jobs:
ufbt-build-action:
runs-on: ubuntu-latest
strategy:
matrix:
include:
- name: dev channel
sdk-channel: dev
- name: release channel
sdk-channel: release
- name: Unofficial firmware
# example URL, replace with a valid one
# you can also use other modes for specifying SDK sources
sdk-index-url: https://flipper.example.com/directory.json
sdk-channel: dev
name: 'ufbt: Build for ${{ matrix.name }}'
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Build with ufbt
uses: flipperdevices/[email protected]
id: build-app
with:
sdk-channel: ${{ matrix.sdk-channel }}
sdk-index-url: ${{ matrix.sdk-index-url }}
- name: Upload app artifacts
uses: actions/upload-artifact@v3
with:
name: ${{ github.event.repository.name }}-${{ steps.build-app.outputs.suffix }}
path: ${{ steps.build-app.outputs.fap-artifacts }}
```
## Inputs
All inputs are **optional**. If you don't specify any inputs, `ufbt` will build your application for the latest release version of official firmware. You can use [fap-artifacts](#fap-artifacts) output to get a list of built files to [upload them](https://github.com/marketplace/actions/upload-a-build-artifact).
#### `task`
Task to run. Can be `setup`, `build` or `lint`. Default is `"build"`.
#### `app-dir`
Path to application's source code. Default is `"."` — the root of the repository.
#### `ufbt-version`
Version of `ufbt` to use. Default is `"latest"` — the latest version available on PyPI. If set to `prerelease`, this action will fetch the latest [pre-release version](https://pypi.org/project/ufbt/#history). You can also use a PyPI version specifier, such as `">=0.2.1,<0.3.0"`.
#### `ufbt-args`
Additional arguments to pass to `ufbt`. Default is `-s` — which suppresses build system output, only leaving subcommands' outputs, such as compiler messages. Set to `""` for extra verbosity.
Only handled when `task` is set to `build` or `lint`. See `ufbt` documentation for details.
#### `skip-setup`
If set to `true`, skips SDK setup. Useful when running multiple action multiple times. Default is `false`.
#### SDK source options
Table below describes options for SDK update. See ufbt documentation on available [SDK update modes](https://github.com/flipperdevices/flipperzero-ufbt/blob/dev/README.md#managing-the-sdk) for details.
| Input name | `ufbt update` argument | Description |
| --- | --- | --- |
| `sdk-channel` | `--channel` | Release channel to use. Can be `dev`, `rc` or `release` |
| `sdk-branch` | `--branch` | Branch to use |
| `sdk-index-url` | `--index-url` | Index URL to use in branch and channel modes |
| `sdk-file` | `--file` | Path to a local SDK file |
| `sdk-url` | `--url` | Fixed URL to a remote SDK file |
| `sdk-hw-target` | `--hw-target` | Hardware target to use |
## Outputs
#### `fap-artifacts`
A list of built `.fap` and `.fal` files. Can be used as input for `upload-artifact` action. Only available in `build` mode.
#### `fap-dir`
A directory with built artifacts and `.elf` files with debugging information. Only available in `build` mode.
#### `api-version`
API version used to build the application. Only available in `build` mode.
#### `suffix`
A suffix to use in artifact names, includes hardware target, API and SDK versions. Can be used for naming artifacts uploaded with `upload-artifact` action. Only available in `build` mode.
#### `lint-messages`
A list of linter messages, in case of any formatting errors. Only available in `lint` mode.
#### `build-errors`
A list of build errors, in case of any. Only available in `build` mode.
#### `ufbt-status`
A string, JSON object with ufbt status. Contains `ufbt status --json` output. Useful for extracting information about ufbt's directories, configured modes, etc. Useful in combination with [fromJSON() function](https://docs.github.com/en/actions/learn-github-actions/expressions#fromjson) to extract information from the output. For example, `${{ fromJSON(steps..ufbt-status).toolchain_dir }}`. Available in all modes.
#### `toolchain-version`
A version of the toolchain used to build the application. Defined by current SDK. Available in all modes.
## Acknowledgements
First version of this action was created by [Oleksii Kutuzov](https://github.com/oleksiikutuzov) and is available [here](https://github.com/oleksiikutuzov/flipperzero-ufbt-action). However, it no longer works with the latest version of `ufbt`. This version is a complete rewrite, with problem matcher borrowed from original verison.