From 09451fb22201a3b38b681d80bb7170032b5cd651 Mon Sep 17 00:00:00 2001
From: peterhinch <peter@hinch.me.uk>
Date: Sun, 29 Jan 2023 10:26:51 +0000
Subject: [PATCH] README.md: Add frozen bytecode appendix.

---
 README.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/README.md b/README.md
index 3941746..47e5b36 100644
--- a/README.md
+++ b/README.md
@@ -147,6 +147,7 @@ development so check for updates.
 8. [ESP32 touch pads](./README.md#8-esp32-touch-pads) Replacing buttons with touch pads.  
 9. [Realtime applications](./README.md#9-realtime-applications) Accommodating tasks requiring fast RT performance.  
 [Appendix 1 Application design](./README.md#appendix-1-application-design) Tab order, button layout, encoder interface, use of graphics primitives  
+[Appendix 2 Freezing bytecode](./README.md#appendix-2-freezing-bytecode) Optional way to save RAM.
 
 # 1. Basic concepts
 
@@ -413,6 +414,7 @@ There is scope for speeding loading and saving RAM by using frozen bytecode.
 The entire `gui` tree may be frozen but the directory structure must be
 maintained. For reasons that are unclear freezing display drivers does not
 work. For fexibility, consider keeping `hardware_setup.py` in the filesystem.
+See [Appendix 2 Freezing bytecode](./README.md#appendix-2-freezing-bytecode).
 
 ###### [Contents](./README.md#0-contents)
 
@@ -3079,3 +3081,43 @@ micro-gui.
 The `primitives.py` demo provides a simple example.
 
 ###### [Contents](./README.md#0-contents)
+
+## Appendix 2 Freezing bytecode
+
+This achieves a major saving of RAM. The correct way to do this is via a
+[manifest file](http://docs.micropython.org/en/latest/reference/manifest.html).
+The first step is to clone MicroPython and prove that you can build and deploy
+firmware to the chosen platform. Build instructions vary between ports and can
+be found in the MicroPython source tree in `ports/<port>/README.md`.
+
+The following is an example of how the entire
+GUI with fonts, demos and all widgets can be frozen on RP2.
+
+Build script:
+```bash
+cd /mnt/qnap2/data/Projects/MicroPython/micropython/ports/rp2
+MANIFEST='/mnt/qnap2/Scripts/manifests/rp2_manifest.py'
+
+make submodules
+make clean
+if make -j 8 BOARD=PICO FROZEN_MANIFEST=$MANIFEST
+then
+    echo Firmware is in build-PICO/firmware.uf2
+else
+    echo Build failure
+fi
+cd -
+```
+Manifest file contents (first line ensures that the default files are frozen):
+```python
+include("$(MPY_DIR)/ports/rp2/boards/manifest.py")
+freeze('/mnt/qnap2/Scripts/modules/rp2_modules')
+```
+The directory `/mnt/qnap2/Scripts/modules/rp2_modules` contains only a symlink
+to the `gui` directory of the `micropython-micro-gui` source tree. The freezing
+process follows symlinks and respects directory structures.
+
+It is usually best to keep `hardware_setup.py` unfrozen for ease of making
+changes. I also keep the display driver and `boolpalette.py` in the filesystem
+as I have experienced problems freezing display drivers - but feel free to
+experiment.