Mirror/Momentum-Firmware
1
0
Fork 0
mirror of https://github.com/Next-Flip/Momentum-Firmware.git synced 2026-04-24 03:29:57 -07:00
Code Issues Packages Projects Releases Wiki Activity

[FL-870] Auto-generated firmware documentation take two (#2944)

Browse Source 
* Add doxygen and doxygen-awesome css, cleanup docs files
* Ignore more libraries and remove leftover local variables
* Create an actual intro page
* .md files linting
* Add doxygen action
* Fix Doxygen path
* Fix doxyfile path
* Try to upload
* Change docs branch
* Add submudules checkout
* Disable doxygen on PR
* Mention the firmware docs in the readme
* More dev docs mentions in the readme
* Fix runner group, add tags
* Test dev in PR
* Disable running on PR
* Fix a typo in the doxyfile
* Try upload to S3
* Fix local path
* Fix S3 ACL
* Add delete flag, unifying dev and tags
* Update ignored directories
* More ignored directories
* Even more ignored directories
* Fix submodule
* Change S3 uploader
* Change S3 uploader version
* Fix aws sync flags
* Fix ACL
* Disable ACL
* Improve ignores, add WiFi devboard docs
* TEMP: generate dev docs
* TEMP: generate 0.89.0 docs
* Disabling PR trigger
* Enable submodules and test build
* Enable test build
* Disable test build
* Change docs directory structure
* Fix accidentally committed submodule
* Fix submodules
* Update links to the developer documentation
* Markdown linting
* Update workflow, enable test build
* Fix doxygen dir path
* Update Doxyfile-awesome.cfg
* Change paths
* Fix upload docs path
* Disable pull_request debug trigger
* Disable tags building
* Remove autolinks and namespaces
* Establish basic documentation structure
* Add missing changes
* Improve stylesheet, move some files
* Improve examples
* Improve the main page
* Improve application dev docs
* Improve system programming docs
* Improve development tools docs
* Improve other docs
* Improve application examples
* Fix formatting
* Fix PVS-studio warnings
* Improve visuals
* Fix doxygen syntax warnings
* Fix broken links
* Update doxygen action

Co-authored-by: DrunkBatya <drunkbatya.js@gmail.com>
Co-authored-by: あく <alleteam@gmail.com>
Co-authored-by: Georgii Surkov <georgii.surkov@outlook.com>
Co-authored-by: Georgii Surkov <37121527+gsurkov@users.noreply.github.com>
This commit is contained in:
Astra
2024-03-06 08:25:21 +02:00
committed by GitHub
parent 5e47048369
commit ecab4d53d2
89 changed files with 1208 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
documentation/AppsOnSDCard.md
View File

@@ -1,4 +1,4 @@
# FAP (Flipper Application Package)
# FAP (Flipper Application Package) {#apps_on_sd_card}
[fbt](./fbt.md) supports building applications as FAP files. FAPs are essentially `.elf` executables with extra metadata and resources bundled in.
@@ -6,7 +6,7 @@ FAPs are built with the `faps` target. They can also be deployed to the `dist` f
FAPs do not depend on being run on a specific firmware version. Compatibility is determined by the FAP's metadata, which includes the required [API version](#api-versioning).
## How to set up an application to be built as a FAP
## How to set up an application to be built as a FAP {#fap-howto}
FAPs are created and developed the same way as internal applications that are part of the firmware.
@@ -21,15 +21,15 @@ To build your application as a FAP, create a folder with your app's source code
FAPs can include static and animated images as private assets. They will be automatically compiled alongside application sources and can be referenced the same way as assets from the main firmware.
To use that feature, put your images in a subfolder inside your application's folder, then reference that folder in your application's manifest in the `fap_icon_assets` field. See [Application Manifests](./AppManifests.md#application-definition) for more details.
To use that feature, put your images in a subfolder inside your application's folder, then reference that folder in your application's manifest in the `fap_icon_assets` field. See [Application Manifests](AppManifests.md) for more details.
To use these assets in your application, put `#include "{APPID}_icons.h"` in your application's source code, where `{APPID}` is the `appid` value field from your application's manifest. Then you can use all icons from your application's assets the same way as if they were a part of `assets_icons.h` of the main firmware.
Images and animated icons should follow the same [naming convention](../assets/ReadMe.md#asset-naming-rules) as those from the main firmware.
Images and animated icons should follow the same [naming convention](../assets/ReadMe.md) as those from the main firmware.
## Debugging FAPs
**`fbt`** includes a script for gdb-py to provide debugging support for FAPs, `debug/flipperapps.py`. It is loaded in default debugging configurations by **`fbt`** and stock VS Code configurations.
`fbt` includes a script for gdb-py to provide debugging support for FAPs, `debug/flipperapps.py`. It is loaded in default debugging configurations by `fbt` and stock VS Code configurations.
With it, you can debug FAPs as if they were a part of the main firmware — inspect variables, set breakpoints, step through the code, etc.
@@ -43,7 +43,7 @@ To debug FAPs, do the following:
1. Build firmware with `./fbt`
2. Flash it with `./fbt flash`
3. [Build your FAP](#how-to-set-up-an-application-to-be-built-as-a-fap) and run it on Flipper
3. [Build your FAP](#fap-howto) and run it on Flipper
After that, you can attach with `./fbt debug` or VS Code and use all debug features.
@@ -59,25 +59,25 @@ Applications are built for a specific API version. It is a part of the hardware
The App Loader allocates memory for the application and copies it to RAM, processing relocations and providing concrete addresses for imported symbols using the [symbol table](#symbol-table). Then it starts the application.
## API versioning
## API versioning {#api-versioning}
Not all parts of firmware are available for external applications. A subset of available functions and variables is defined in the "api_symbols.csv" file, which is a part of the firmware target definition in the `targets/` directory.
**`fbt`** uses semantic versioning for the API. The major version is incremented when there are breaking changes in the API. The minor version is incremented when new features are added.
`fbt` uses semantic versioning for the API. The major version is incremented when there are breaking changes in the API. The minor version is incremented when new features are added.
Breaking changes include:
- Removing a function or a global variable
- Changing the signature of a function
API versioning is mostly automated by **`fbt`**. When rebuilding the firmware, **`fbt`** checks if there are any changes in the API exposed by headers gathered from `SDK_HEADERS`. If so, it stops the build, adjusts the API version, and asks the user to go through the changes in the `.csv` file. New entries are marked with a "`?`" mark, and the user is supposed to change the mark to "`+`" for the entry to be exposed for FAPs, or to "`-`" for it to be unavailable.
API versioning is mostly automated by `fbt`. When rebuilding the firmware, `fbt` checks if there are any changes in the API exposed by headers gathered from `SDK_HEADERS`. If so, it stops the build, adjusts the API version, and asks the user to go through the changes in the `.csv` file. New entries are marked with a "`?`" mark, and the user is supposed to change the mark to "`+`" for the entry to be exposed for FAPs, or to "`-`" for it to be unavailable.
**`fbt`** will not allow building a firmware until all "`?`" entries are changed to "`+`" or "`-`".
`fbt` will not allow building a firmware until all "`?`" entries are changed to "`+`" or "`-`".
**NB:** **`fbt`** automatically manages the API version. The only case where manually incrementing the major API version is allowed (and required) is when existing "`+`" entries are to be changed to "`-`".
**NB:** `fbt` automatically manages the API version. The only case where manually incrementing the major API version is allowed (and required) is when existing "`+`" entries are to be changed to "`-`".
### Symbol table
### Symbol table {#symbol-table}
The symbol table is a list of symbols exported by firmware and available for external applications. It is generated by **`fbt`** from the API symbols file and is used by the App Loader to resolve addresses of imported symbols. It is build as a part of the `fap_loader` application.
The symbol table is a list of symbols exported by firmware and available for external applications. It is generated by `fbt` from the API symbols file and is used by the App Loader to resolve addresses of imported symbols. It is build as a part of the `fap_loader` application.
**`fbt`** also checks if all imported symbols are present in the symbol table. If there are any missing symbols, it will issue a warning listing them. The application won't be able to run on the device until all required symbols are provided in the symbol table.
`fbt` also checks if all imported symbols are present in the symbol table. If there are any missing symbols, it will issue a warning listing them. The application won't be able to run on the device until all required symbols are provided in the symbol table.