test new examples README

examples/README.md

@@ -1,10 +1,10 @@
 # Examples
 
-Each subfolder contains an example application, except the `common` folder, which contains common code for all examples.
+## Premise
 
-In order to build an example just `cd` to `*example*/*platform*` and use the following platform-specific instructions.
+Each of these examples consists of a common part of code, shared by all examples, which contains all necessary boilerplate code and is not Brickworks-related, and a specific part which actually implements the audio engine. The common code is copied/generated by an external tool called [Tibia](https://github.com/sdangelo/tibia). If you downloaded an official Brickworks release you don't need to care about any of this - all needed files will already be present -, otherwise you first need to [run Tibia as outlined below](#tibia). You might also want to do that if you need to edit the location of third-party dependencies (this is better explained in the following platform-specific instructions).
 
-Building for any platform requires a recent enough version of [GNU Make](https://www.gnu.org/software/make/) installed.
+Each subfolder contains an example, except the `common` folder, which contains a good deal of common code and common Tibia metadata. In order to build an example just `cd` to `*example*/*platform*` 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
 
@@ -12,17 +12,31 @@ Building for any platform requires a recent enough version of [GNU Make](https:/
 
 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.
+You also need to download or clone the [VST3 C API](https://github.com/steinbergmedia/vst3_c_api) and place it in the same folder as the Brickworks folder, or otherwise edit `common/src/vst3-make.json` then change `cflags` to point to the correct directory and finally [run Tibia](#tibia), or invoke `make` with appropriate `CFLAGS` straight from the command line.
 
 ### Build
 
-In order to build just type `make`. You'll find the resulting VST3 directory in `build/example.vst3`.
+In order to build just type `make`. You'll find the resulting VST3 directory in <code>build/bw\_example\_*example*.vst3</code>.
 
 ### Installation
 
-If all went fine, you can install for the current user (i.e., into the user VST3 folder) by invoking `make install-user`.
+If all went fine, you can install for the current user (i.e., into the user VST3 folder) by invoking `make install-user` or for all users (i.e., into the system VST3 folder) by `make install`.
 
-On macOS and Linux you can also install for all users (i.e., into the system VST3 folder) by `make install`.
+## LV2
+
+### 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/install [LV2](https://lv2plug.in/), so that either header files are found by the compiler in its default include path, or otherwise you could add an appropriate `cflags` value to `common/src/lv2-make.json` and [run Tibia](#tibia), or invoke `make` with appropriate `CFLAGS` straight from the command line.
+
+### Build
+
+In order to build just type `make`. You'll find the resulting LV2 bundle in <code>build/bw\_example\_*example*.lv2</code>.
+
+### Installation
+
+If all went fine, you can install for the current user (i.e., into the user VST3 folder) by invoking `make install-user` or for all users (i.e., into the system VST3 folder) by `make install`.
 
 ## Web
 
@@ -44,7 +58,7 @@ The output files need to be served over HTTPS. A self-signed certificate is gene
 
 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.
+You also need to clone/download [libDaisy](https://github.com/electro-smith/libDaisy) (beware that since version 7.0.0 you also need to clone submodules, see the [release notes](https://github.com/electro-smith/libDaisy/releases/tag/v7.0.0)), `cd` to it, and run `make`. You should either place it in the same folder as the Brickworks folder, or otherwise edit `common/src/daisy-seed-make.json` then change `libdaisyDir` to point to the correct directory and finally [run Tibia](#tibia).
 
 ### Build
 
@@ -64,7 +78,7 @@ Effect examples report output parameter values and CPU usage statistics via USB
 
 ### Prerequisites
 
-Android examples are built without the help of Android Studio or Gradle. You'll however need to have a recent enough JDK (we need `javac` and `keytool`), as well as to download the latest stable:
+Android examples are built without the help of Android Studio or Gradle. You'll however need to have a recent enough JDK (we need `javac`), as well as to download the latest stable:
 
 - Android SDK (https://developer.android.com/studio/index.html) \*;
 - Android NDK (https://developer.android.com/ndk/downloads) \*;
@@ -77,7 +91,7 @@ Android examples are built without the help of Android Studio or Gradle. You'll
   - Koltin Coroutines Core JVM (https://mvnrepository.com/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-jvm);
 - `miniaudio.h` library (http://miniaud.io/).
 
-Then you'll probably also need to adjust paths in `common/android/android.mk`.
+Then you'll probably also need to adjust paths and values in `common/src/android-make.json` and [run Tibia](#tibia).
 
 \* You can install both the needed parts of the Android SDK and the NDK by downloading the so-called "command line tools" (https://developer.android.com/studio#command-line-tools-only) and using the included `sdkmanager` program. In such case you need to install the following packages: "platforms;android-*latest*",  "build-tools;*latest*", "platform-tools", and "ndk;*latest*".
 
@@ -87,9 +101,7 @@ In order to build just type `make`. You'll find the resulting `.apk` file in `bu
 
 ### Installation
 
-If all went fine, you can branch your device and install using `make install`.
+If all went fine, you can branch your device and install using `make install` or otherwise install manually.
-
-Otherwise, you can also install manually, but please remember to first uninstall the application from the device (`adb install -r` is not sufficient as the signature might have changed while building).
 
 ### Usage and known issues
 
@@ -105,7 +117,7 @@ iOS examples are not directly built by the supplied Makefiles. These rather gene
 
 For this to work you need to have the latest [Xcode](https://developer.apple.com/xcode/) and [XcodeGen](https://github.com/yonaskolb/XcodeGen) installed, as well as a copy of the latest [`miniaudio.h`](http://miniaud.io/).
 
-Finally, you might need to adjust header search path for miniaudio in `build/common/ios/project.yml`.
+Finally, you might need to adjust header search path for miniaudio in `common/src/ios-make.json`, `common/src/ios-make-cxx-fx.json`, and `common/src/io-make-cxx-synth.json`, and [run Tibia](#tibia).
 
 ### Build
 
@@ -120,3 +132,7 @@ At this point you can build and run as with any other iOS app.
 Effect examples process audio input signals, therefore they will require permission to use the capture device.
 
 Synth examples use input MIDI and support hotplugging.
+
+## Tibia
+
+...