1 files changed, 24 insertions, 4 deletions

diff --git a/README.md b/README.md
index 83e9a6e9..5b577aee 100644
--- a/README.md
+++ b/README.md
@@ -24,11 +24,11 @@ Prebuilt binaries for Windows and macOS can be found in [Releases][rel].
 
 This is how to build Lagrange in a Unix-like environment. The required tools are a C11 compiler (e.g., Clang or GCC), CMake and `pkg-config`.
 
-1. Download and extract a source tarball from [Releases][rel]. (If you just clone this Git repository, [the_Foundation][tf] is expected to be already available on the system.)
-2. Check that you have the dependencies installed: SDL2, OpenSSL, libpcre, zlib, libunistring. For example, on macOS this would do the trick (using Homebrew): ```brew install sdl2 openssl@1.1 pcre libunistring``` Or on Ubuntu: ```sudo apt install libsdl2-dev libssl-dev libpcre3-dev zlib1g-dev libunistring-dev```
+1. Download and extract a source tarball from [Releases][rel]. Alternatively, you may also clone the repository and its submodules: `git clone --recursive --branch release https://git.skyjake.fi/skyjake/lagrange`
+2. Check that you have the dependencies installed: CMake, SDL 2, OpenSSL 1.1.1, libpcre, zlib, libunistring. For example, on macOS this would do the trick (using Homebrew): ```brew install cmake sdl2 openssl@1.1 pcre libunistring``` Or on Ubuntu: ```sudo apt install cmake libsdl2-dev libssl-dev libpcre3-dev zlib1g-dev libunistring-dev```
 3. Create a build directory.
-4. In your empty build directory, run CMake: ```cmake {path_of_lagrange_sources}```
-5. Built it: ```cmake --build .```
+4. In your empty build directory, run CMake: ```cmake {path_of_lagrange_sources} -DCMAKE_BUILD_TYPE=Release```
+5. Build it: ```cmake --build .```
 6. Now you can run `lagrange`, `lagrange.exe`, or `Lagrange.app`.
 
 ### Installing to a directory
@@ -40,5 +40,25 @@ To install to "/dest/path":
 
 This will also install an XDG .desktop file for launching the app.
 
+### macOS-specific notes
+
+When using OpenSSL 1.1.1 from Homebrew, you must add its pkgconfig path to your `PKG_CONFIG_PATH` environment variable, for example:
+
+    export PKG_CONFIG_PATH=/usr/local/Cellar/openssl@1.1/1.1.1g/lib/pkgconfig
+
+Also, SDL's trackpad scrolling behavior on macOS is not optimal for regular GUI apps because it emulates a physical mouse wheel. This may change in a future release of SDL, but at least in 2.0.12 a [small patch](https://git.skyjake.fi/skyjake/lagrange/raw/branch/dev/sdl2-macos-mouse-scrolling-patch.diff) is required to allow momentum scrolling to come through as single-pixel mouse wheel events.
+
+### Raspberry Pi notes
+
+You should use a version of SDL that is compiled to take advantage of the Broadcom VideoCore OpenGL ES hardware. This provides the best performance when running Lagrange in a console.
+
+When running under X11, software rendering is the best choice and in that case the SDL from Raspbian etc. is sufficient.
+
+The following build options are recommended on Raspberry Pi:
+
+* `ENABLE_KERNING=NO`: faster text rendering without noticeable loss of quality
+* `ENABLE_WINDOWPOS_FIX=YES`: workaround for window position restore issues (SDL bug)
+* `ENABLE_X11_SWRENDER=YES`: use software rendering under X11
+
 [rel]: https://git.skyjake.fi/skyjake/lagrange/releases
 [tf]:  https://git.skyjake.fi/skyjake/the_Foundation