| Name | ufbt JSON |
| Version |
0.2.5
JSON |
| download |
| home_page | |
| Summary | uFBT - micro Flipper Build Tool. Tool for building and developing applications (.fap) for Flipper Zero and its device family. |
| upload_time | 2023-12-22 10:34:56 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | GPL-3.0 |
| keywords |
ufbt
flipperzero
fbt
stm32
fap
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# uFBT - micro Flipper Build Tool
uFBT is a cross-platform tool for building applications for [Flipper Zero](https://flipperzero.one/). It is a simplified version of [Flipper Build Tool (FBT)](https://github.com/flipperdevices/flipperzero-firmware/blob/dev/documentation/fbt.md).
**uFBT has an [official GitHub Action](https://github.com/marketplace/actions/build-flipper-application-package-fap). With it, you can automate building and publishing your application using GitHub workflows.**
uFBT enables basic development tasks for Flipper Zero, such as building and debugging applications, flashing firmware, creating VSCode development configurations. It uses prebuilt binaries and libraries, so you don't need to build [the whole firmware](https://github.com/flipperdevices/flipperzero-firmware) to compile and debug your application for Flipper.
## Installation
- **Linux & macOS**: `python3 -m pip install --upgrade ufbt`
- **Windows**: `py -m pip install --upgrade ufbt`
uFBT uses your system's Python for running bootstrap code. Minimal supported version is **Python 3.8**. For executing actual build tasks, uFBT will download and use its own Python binaries and a toolchain built for your platform.
On first run, uFBT will download and install required SDK components from `release` update channel of official firmware. For more information on how to switch to a different version of the SDK, see [Managing the SDK](#managing-the-sdk) section.
### Using pyenv
If you are using `pyenv` to manage python versions, after installation you may need to run `pyenv rehash` to generate [shim](https://github.com/pyenv/pyenv#understanding-shims) for `ufbt` command.
## Usage
### Building & running your application
Run `ufbt` in the root directory of your application (the one with `application.fam` file in it). It will build your application and place the resulting binary in `dist` subdirectory.
You can upload and start your application on Flipper attached over USB using `ufbt launch`.
To see other available commands and options, run `ufbt -h`.
### Debugging
In order to debug your application, you need to be running the firmware distributed alongside with current SDK version. You can flash it to your Flipper using `ufbt flash` (using a supported SWD probe), `ufbt flash_usb` (over USB).
For other flashing and debugging options, see `ufbt -h`.
### VSCode integration
uFBT provides a configuration for VSCode that allows you to build and debug your application directly from the IDE. To deploy it, run `ufbt vscode_dist` in the root directory of your application. Then you can open the project in VSCode (`File`-`Open Folder...`) and use the provided launch (`ctrl+shift+b`) & debugging (`ctrl+shift+d`) configurations.
### Application template
uFBT can create a template for your application. To do this, run `ufbt create APPID=<app_id>` in the directory where you want to create your application. It will create an application manifest and its main source file. You can then build and debug your application using the instructions above.
Application manifests are explained in the [FBT documentation](https://github.com/flipperdevices/flipperzero-firmware/blob/dev/documentation/AppManifests.md).
### Other
* `ufbt cli` starts a CLI session with the device;
* `ufbt lint`, `ufbt format` run clang-format on application's sources;
* You can temporarily add toolchain binaries (compiler, linter, OpenOCD and others) to your PATH. See `ufbt --help` for more information.
## Managing the SDK
To update the SDK, run `ufbt update`. This will download and install all required SDK components from previously used source.
- To switch to SDK for a different **release channel**, run `ufbt update --channel=[dev|rc|release]`.
- uFBT also supports 3rd-party update indexers, following the same schema as [official firmware](https://github.com/flipperdevices/flipperzero-firmware). To use them, run `ufbt update --index-url=<url>`, where `<url>` is a URL to the index file, e.g. `https://update.flipperzero.one/firmware/directory.json`.
- To use SDK for a **certain release** or a not-yet-merged **branch** from official repo, run `ufbt update --branch=0.81.1` or `ufbt update --branch=owner/my-awesome-feature`.
- You can also use branches from other repos, where build artifacts are available from an indexed directory, by specifying `--index-url=<url>`.
- uFBT can also download and update the SDK from any **fixed URL**. To do this, run `ufbt update --url=<url>`.
- To use a **local copy** of the SDK, run `ufbt update --local=<path>`. This will use the SDK located in `<path>` instead of downloading it. Useful for testing local builds of the SDK.
### Global and per-project SDK management
By default, uFBT stores its state - SDK and toolchain - in `.ufbt` subfolder of your home directory. You can override this location by setting `UFBT_HOME` environment variable.
uFBT also supports dotenv (`.env`) files, containing environment variable overrides for the project in current directory. Most commonly, you will want to use this to override the default state directory to a local one, so that your project could use a specific version and/or hardware target of the SDK.
You can enable dotenv mode for current directory by running `ufbt dotenv_create`. This will create `.env` file in current directory with default values, linking SDK state to `.ufbt` subfolder in current directory, and creating a symlink for toolchain to `.ufbt/toolchain` in your home directory. You can then edit `.env` file to further customize the environment.
You can also specify additional options when creating the `.env` file. See `ufbt dotenv_create --help` for more information.
### ufbt-bootstrap
Updating the SDK is handled by uFBT component called _bootstrap_. It has a dedicated entry point, `ufbt-bootstrap`, with additional options that might be useful in certain scenarios. Run `ufbt-bootstrap --help` to see them.
## Troubleshooting
If something goes wrong and uFBT state becomes corrupted, you can reset it by running `ufbt clean`. If that doesn't work, you can try removing `.ufbt` subfolder manually from your home folder.
`ufbt-bootstrap` and SDK-related `ufbt` subcommands accept `--verbose` option that will print additional debug information.
## Contributing
uFBT is a small tool and does not contain the actual implementation of build system, project templates or toolchain. It functions as a downloader and manager of SDK components that are packaged [alongside with Flipper firmware](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/scripts/ufbt).
Issues and pull requests regarding `ufbt-bootstrap` features like SDK management should be reported to this project, and the rest - related to actual application development - to [Flipper firmware repo](https://github.com/flipperdevices/flipperzero-firmware/issues).
Raw data
{
"_id": null,
"home_page": "",
"name": "ufbt",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "ufbt,flipperzero,fbt,stm32,fap",
"author": "",
"author_email": "\"Flipper Devices Inc.\" <pypi@flipperdevices.com>",
"download_url": "https://files.pythonhosted.org/packages/68/ee/2c523dc976b1d428b561bc9651ac933fd3c3c6dee5ed23a69dd30c933fdb/ufbt-0.2.5.tar.gz",
"platform": null,
"description": "# uFBT - micro Flipper Build Tool\n\nuFBT is a cross-platform tool for building applications for [Flipper Zero](https://flipperzero.one/). It is a simplified version of [Flipper Build Tool (FBT)](https://github.com/flipperdevices/flipperzero-firmware/blob/dev/documentation/fbt.md).\n\n**uFBT has an [official GitHub Action](https://github.com/marketplace/actions/build-flipper-application-package-fap). With it, you can automate building and publishing your application using GitHub workflows.**\n\nuFBT enables basic development tasks for Flipper Zero, such as building and debugging applications, flashing firmware, creating VSCode development configurations. It uses prebuilt binaries and libraries, so you don't need to build [the whole firmware](https://github.com/flipperdevices/flipperzero-firmware) to compile and debug your application for Flipper.\n\n## Installation\n\n- **Linux & macOS**: `python3 -m pip install --upgrade ufbt`\n- **Windows**: `py -m pip install --upgrade ufbt`\n\nuFBT uses your system's Python for running bootstrap code. Minimal supported version is **Python 3.8**. For executing actual build tasks, uFBT will download and use its own Python binaries and a toolchain built for your platform.\n\nOn first run, uFBT will download and install required SDK components from `release` update channel of official firmware. For more information on how to switch to a different version of the SDK, see [Managing the SDK](#managing-the-sdk) section.\n\n### Using pyenv\n\nIf you are using `pyenv` to manage python versions, after installation you may need to run `pyenv rehash` to generate [shim](https://github.com/pyenv/pyenv#understanding-shims) for `ufbt` command. \n\n## Usage\n\n### Building & running your application\n\nRun `ufbt` in the root directory of your application (the one with `application.fam` file in it). It will build your application and place the resulting binary in `dist` subdirectory.\n\nYou can upload and start your application on Flipper attached over USB using `ufbt launch`. \n\nTo see other available commands and options, run `ufbt -h`.\n\n### Debugging\n\nIn order to debug your application, you need to be running the firmware distributed alongside with current SDK version. You can flash it to your Flipper using `ufbt flash` (using a supported SWD probe), `ufbt flash_usb` (over USB). \n\nFor other flashing and debugging options, see `ufbt -h`.\n\n### VSCode integration\n\nuFBT provides a configuration for VSCode that allows you to build and debug your application directly from the IDE. To deploy it, run `ufbt vscode_dist` in the root directory of your application. Then you can open the project in VSCode (`File`-`Open Folder...`) and use the provided launch (`ctrl+shift+b`) & debugging (`ctrl+shift+d`) configurations.\n\n### Application template\n\nuFBT can create a template for your application. To do this, run `ufbt create APPID=<app_id>` in the directory where you want to create your application. It will create an application manifest and its main source file. You can then build and debug your application using the instructions above.\n\nApplication manifests are explained in the [FBT documentation](https://github.com/flipperdevices/flipperzero-firmware/blob/dev/documentation/AppManifests.md).\n\n### Other\n\n * `ufbt cli` starts a CLI session with the device;\n * `ufbt lint`, `ufbt format` run clang-format on application's sources;\n * You can temporarily add toolchain binaries (compiler, linter, OpenOCD and others) to your PATH. See `ufbt --help` for more information.\n\n## Managing the SDK\n\nTo update the SDK, run `ufbt update`. This will download and install all required SDK components from previously used source.\n\n- To switch to SDK for a different **release channel**, run `ufbt update --channel=[dev|rc|release]`. \n - uFBT also supports 3rd-party update indexers, following the same schema as [official firmware](https://github.com/flipperdevices/flipperzero-firmware). To use them, run `ufbt update --index-url=<url>`, where `<url>` is a URL to the index file, e.g. `https://update.flipperzero.one/firmware/directory.json`.\n- To use SDK for a **certain release** or a not-yet-merged **branch** from official repo, run `ufbt update --branch=0.81.1` or `ufbt update --branch=owner/my-awesome-feature`. \n - You can also use branches from other repos, where build artifacts are available from an indexed directory, by specifying `--index-url=<url>`.\n- uFBT can also download and update the SDK from any **fixed URL**. To do this, run `ufbt update --url=<url>`.\n- To use a **local copy** of the SDK, run `ufbt update --local=<path>`. This will use the SDK located in `<path>` instead of downloading it. Useful for testing local builds of the SDK.\n\n### Global and per-project SDK management\n\nBy default, uFBT stores its state - SDK and toolchain - in `.ufbt` subfolder of your home directory. You can override this location by setting `UFBT_HOME` environment variable.\n\nuFBT also supports dotenv (`.env`) files, containing environment variable overrides for the project in current directory. Most commonly, you will want to use this to override the default state directory to a local one, so that your project could use a specific version and/or hardware target of the SDK. \n\nYou can enable dotenv mode for current directory by running `ufbt dotenv_create`. This will create `.env` file in current directory with default values, linking SDK state to `.ufbt` subfolder in current directory, and creating a symlink for toolchain to `.ufbt/toolchain` in your home directory. You can then edit `.env` file to further customize the environment. \n\nYou can also specify additional options when creating the `.env` file. See `ufbt dotenv_create --help` for more information.\n\n### ufbt-bootstrap\n\nUpdating the SDK is handled by uFBT component called _bootstrap_. It has a dedicated entry point, `ufbt-bootstrap`, with additional options that might be useful in certain scenarios. Run `ufbt-bootstrap --help` to see them.\n\n## Troubleshooting\n\nIf something goes wrong and uFBT state becomes corrupted, you can reset it by running `ufbt clean`. If that doesn't work, you can try removing `.ufbt` subfolder manually from your home folder.\n\n`ufbt-bootstrap` and SDK-related `ufbt` subcommands accept `--verbose` option that will print additional debug information.\n\n## Contributing\n\nuFBT is a small tool and does not contain the actual implementation of build system, project templates or toolchain. It functions as a downloader and manager of SDK components that are packaged [alongside with Flipper firmware](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/scripts/ufbt). \n\nIssues and pull requests regarding `ufbt-bootstrap` features like SDK management should be reported to this project, and the rest - related to actual application development - to [Flipper firmware repo](https://github.com/flipperdevices/flipperzero-firmware/issues).\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "uFBT - micro Flipper Build Tool. Tool for building and developing applications (.fap) for Flipper Zero and its device family.",
"version": "0.2.5",
"project_urls": {
"documentation": "https://github.com/flipperdevices/flipperzero-ufbt",
"homepage": "https://github.com/flipperdevices/flipperzero-ufbt",
"issues": "https://github.com/flipperdevices/flipperzero-ufbt/issues",
"repository": "https://github.com/flipperdevices/flipperzero-ufbt"
},
"split_keywords": [
"ufbt",
"flipperzero",
"fbt",
"stm32",
"fap"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "24c692b5ec7f9e351b965af8ffea66a01248a3e709a45f0b2d9dc7e7f810bbd1",
"md5": "607984b72394bb164af01ad99d623c21",
"sha256": "b478b847c14ba0fadeec894b7cf4f23988afed390e22fe71d5f8b9a26aa45c18"
},
"downloads": -1,
"filename": "ufbt-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "607984b72394bb164af01ad99d623c21",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 25739,
"upload_time": "2023-12-22T10:34:54",
"upload_time_iso_8601": "2023-12-22T10:34:54.935330Z",
"url": "https://files.pythonhosted.org/packages/24/c6/92b5ec7f9e351b965af8ffea66a01248a3e709a45f0b2d9dc7e7f810bbd1/ufbt-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "68ee2c523dc976b1d428b561bc9651ac933fd3c3c6dee5ed23a69dd30c933fdb",
"md5": "7b71a494d36fe6327f39a86e72d39334",
"sha256": "a5023ca529f95fa212276ae51087deea37b883b3d8f0784a21397519e98cbdff"
},
"downloads": -1,
"filename": "ufbt-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "7b71a494d36fe6327f39a86e72d39334",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26672,
"upload_time": "2023-12-22T10:34:56",
"upload_time_iso_8601": "2023-12-22T10:34:56.175967Z",
"url": "https://files.pythonhosted.org/packages/68/ee/2c523dc976b1d428b561bc9651ac933fd3c3c6dee5ed23a69dd30c933fdb/ufbt-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-22 10:34:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "flipperdevices",
"github_project": "flipperzero-ufbt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ufbt"
}
