From 537e3097932c429f15cfbf480aa79da8d35ee5bd Mon Sep 17 00:00:00 2001
From: Stefano D'Angelo <stefano.dangelo@orastron.com>
Date: Mon, 20 Feb 2023 18:09:17 +0100
Subject: [PATCH] updated README.md and added example building/running
 documentation

---
 README.md          |  2 +-
 examples/README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 examples/README.md

diff --git a/README.md b/README.md
index 7c79a17..f2790a9 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ You can find information and documentation [on the official web page](https://ww
 
 ## Subfolders
 
-* examples: synth and an effect examples in VST3 and Web Audio formats;
+* examples: synth and an effect examples in VST3, Web Audio, and Daisy Seed formats;
 * include: header files.
 
 ## Legal
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..a881914
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,65 @@
+# Examples
+
+Each subfolder contains an example application, except the `common` folder, which contains common code for all examples.
+
+In order to build an example just `cd` to `*example*/*platofrm*` and use the following platform-specific instructions.
+
+Building for any platform requires a recent enough version of [GNU Make](https://www.gnu.org/software/make/) installed.
+
+## VST3
+
+### Prerequisites
+
+Windows (via [MSYS2/Mingw-w64](https://www.msys2.org/)), macOS, and Linux OSes are supported. Building tested with [GCC](https://gcc.gnu.org/), probably also works with [Clang](https://clang.llvm.org/).
+
+You also need to download the [VST3 SDK](https://www.steinberg.net/developers/) and place it in the same folder as the Brickworks folder, or otherwise edit `common/vst3/vst3.mk` and change the `VST3_SDK_DIR` variable to point to the correct directory.
+
+### Build
+
+In order to build just type `make`. You'll find the resulting VST3 directory in `build/example.vst3`.
+
+### Installation
+
+If all went fine, you can install for the current user (i.e., into the user VST3 folder) by invoking `make install-user`.
+
+On macOS and Linux you can also install for all users (i.e., into the system VST3 folder) by `make install`.
+
+## Web
+
+### Prerequisites
+
+You need Clang with WebAssembly target support and [OpenSSL](https://www.openssl.org/) installed.
+
+### Build
+
+In order to build just type `make`. You'll find the resulting output directory in `build/web`.
+
+### Running
+
+The output files need to be served over HTTPS. A self-signed certificate is generated in the output directory (hence the OpenSSL requirement) to make it possible to run an HTTPS-enabled web server, e.g. `https-server -S`,  directly on/from the output folder.
+
+## Daisy Seed
+
+### Prerequisites
+
+Building and firmware upload was only tested on Linux. You need [arm-none-eabi-gcc](https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain) (for building) and [dfu-util](https://dfu-util.sourceforge.net/) (for firmware upload) installed.
+
+You also need to clone [libDaisy](https://github.com/electro-smith/libDaisy), `cd` to it, and run `make`. You should either place it in the same folder as the Brickworks folder, or otherwise edit `common/daisy-seed/daisy-seed.mk` and change the `LIBDAISY_DIR` variable to point to the correct directory.
+
+### Build
+
+In order to build just type `make`. You'll find the resulting output files in `build`.
+
+### Firmware upload
+
+To upload the firmware:
+
+1. branch the board to the uploading machine via USB;
+2. put the board in DFU mode by pressing BOOT, then RESET, then letting go of RESET and then of BOOT;
+3. type `make program-dfu`.
+
+Effect examples report output parameter values and CPU usage statistics via USB serial. You can read the output by, e.g., `screen /dev/ttyACM0`.
+
+## Thanks
+
+Thanks to [Mads Kjeldgaard](https://madskjeldgaard.dk/) for publishing [instructions to build for the Daisy Seed and uploading the firmware](https://madskjeldgaard.dk/posts/daisy-setup/).