[FL-2859,2838] fbt: improvements for FAPs (#1813)

* fbt: assets builder for apps WIP
* fbt: automatically building private fap assets
* docs: details on how to use image assets
* fbt: renamed fap_assets -> fap_icons
* fbt: support for fap_extbuild field
* docs: info on fap_extbuild
* fbt: added --proxy-env parame ter
* fbt: made firmware_cdb & updater_cdb targets always available
* fbt: renamed fap_icons -> fap_icon_assets
* fbt: deprecated firmware_* target names for faps; new alias is "fap_APPID"
* fbt: changed intermediate file locations for external apps
* fbt: support for fap_private_libs; docs: updates
* restored mbedtls as global lib
* scripts: lint.py: skip "lib" subfolder
* fbt: Sanity checks for building advanced faps as part of fw
* docs: info on fap_private_libs; fbt: optimized *.fam indexing
* fbt: cleanup; samples: added sample_icons app
* fbt: moved example app to applications/examples
* linter fix
* docs: readme fixes
* added applications/examples/application.fam stub
* docs: more info on private libs

Co-authored-by: あく <alleteam@gmail.com>

documentation/AppManifests.md

@@ -41,9 +41,12 @@ Only 2 parameters are mandatory: ***appid*** and ***apptype***, others are optio
 * **order**: Order of an application within its group when sorting entries in it. The lower the order is, the closer to the start of the list the item is placed. *Used for ordering startup hooks and menu entries.* 
 * **sdk_headers**: List of C header files from this app's code to include in API definitions for external applications.
 
+
+#### Parameters for external applications
+
 The following parameters are used only for [FAPs](./AppsOnSDCard.md):
 
-* **sources**: list of strings, file name masks, used for gathering sources within app folder. Default value of `["*.c*"]` includes C and CPP source files.
+* **sources**: list of strings, file name masks, used for gathering sources within app folder. Default value of `["*.c*"]` includes C and C++ source files. Application cannot use `"lib"` folder for their own source code, as it is reserved for **fap_private_libs**.
 * **fap_version**: tuple, 2 numbers in form of (x,y): application version to be embedded within .fap file. Default value is (0,1), meanig version "0.1".
 * **fap_icon**: name of a .png file, 1-bit color depth, 10x10px, to be embedded within .fap file.
 * **fap_libs**: list of extra libraries to link application against. Provides access to extra functions that are not exported as a part of main firmware at expense of increased .fap file size and RAM consumption.
@@ -51,6 +54,58 @@ The following parameters are used only for [FAPs](./AppsOnSDCard.md):
 * **fap_description**: string, may be empty. Short application description.
 * **fap_author**: string, may be empty. Application's author.
 * **fap_weburl**: string, may be empty. Application's homepage.
+* **fap_icon_assets**: string. If present, defines a folder name to be used for gathering image assets for this application. These images will be preprocessed and built alongside the application. See [FAP assets](./AppsOnSDCard.md#fap-assets) for details.
+* **fap_extbuild**: provides support for parts of application sources to be build by external tools. Contains a list of `ExtFile(path="file name", command="shell command")` definitions. **`fbt`** will run the specified command for each file in the list.
+Note that commands are executed at the firmware root folder's root, and all intermediate files must be placed in a application's temporary build folder. For that, you can use pattern expansion by **`fbt`**: `${FAP_WORK_DIR}` will be replaced with the path to the application's temporary build folder, and `${FAP_SRC_DIR}` will be replaced with the path to the application's source folder. You can also use other variables defined internally by **`fbt`**. 
+
+Example for building an app from Rust sources:
+
+```python
+    sources=["target/thumbv7em-none-eabihf/release/libhello_rust.a"],
+    fap_extbuild=(
+        ExtFile(
+            path="${FAP_WORK_DIR}/target/thumbv7em-none-eabihf/release/libhello_rust.a",
+            command="cargo build --release --verbose --target thumbv7em-none-eabihf --target-dir ${FAP_WORK_DIR}/target --manifest-path ${FAP_SRC_DIR}/Cargo.toml",
+        ),
+    ),
+```
+
+* **fap_private_libs**: list of additional libraries that are distributed as sources alongside the application. These libraries will be built as a part of the application build process. 
+Library sources must be placed in a subfolder of "`lib`" folder within the application's source folder.
+Each library is defined as a call to `Lib()` function, accepting the following parameters:
+
+    - **name**: name of library's folder. Required.
+    - **fap_include_paths**: list of library's relative paths to add to parent fap's include path list. Default value is `["."]` meaning  library's source root.
+    - **sources**: list of filename masks to be used for gathering include files for this library. Default value is `["*.c*"]`.
+    - **cflags**: list of additional compiler flags to be used for building this library. Default value is `[]`.
+    - **cdefines**: list of additional preprocessor definitions to be used for building this library. Default value is `[]`.
+    - **cincludes**: list of additional include paths to be used for building this library. Can be used for providing external search paths for this library's code - for configuration headers. Default value is `[]`.
+
+Example for building an app with a private library:
+
+```python
+    fap_private_libs=[
+            Lib(
+                name="mbedtls",
+                fap_include_paths=["include"],
+                sources=[
+                    "library/des.c",
+                    "library/sha1.c",
+                    "library/platform_util.c",
+                ],
+                cdefines=["MBEDTLS_ERROR_C"],
+            ),
+            Lib(
+                name="loclass",
+                cflags=["-Wno-error"],
+            ),
+        ],
+```
+
+For that snippet, **`fbt`** will build 2 libraries: one from sources in `lib/mbedtls` folder, and another from sources in `lib/loclass` folder. For `mbedtls` library, **`fbt`** will add `lib/mbedtls/include` to the list of include paths for the application and compile only the files specified in `sources` list. Additionally, **`fbt`** will enable `MBEDTLS_ERROR_C` preprocessor definition for `mbedtls` sources. 
+For `loclass` library, **`fbt`** will add `lib/loclass` to the list of include paths for the application and build all sources in that folder. Also **`fbt`** will disable treating compiler warnings as errors for `loclass` library specifically - that can be useful when compiling large 3rd-party codebases.
+
+Both libraries will be linked into the application.
 
 
 ## .fam file contents