Update README

2 files changed, 118 insertions, 20 deletions

diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..d4e0090
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,89 @@
+Installation Instructions
+=========================
+
+Prerequisites
+-------------
+
+To build from source, you will need:
+
+ * A relatively modern C compiler (GCC, Clang, and MSVC are known to work).
+
+ * [Meson](http://mesonbuild.com/), which depends on
+   [Python](http://python.org/).
+
+This is a brief overview of building this project with meson.  See the meson
+documentation for more detailed information.
+
+Configuration
+-------------
+
+The build is configured with the `setup` command, which creates a new build
+directory with the given name:
+
+    meson setup build
+
+Some environment variables are read during `setup` and stored with the
+configuration:
+
+  * `CC`: Path to C compiler.
+  * `CFLAGS`: C compiler options.
+  * `LDFLAGS`: Linker options.
+
+However, it is better to use meson options for configuration.  All options can
+be inspected with the `configure` command from within the build directory:
+
+    cd build
+    meson configure
+
+Options can be set by passing C-style "define" options to `configure`:
+
+    meson configure -Dc_args="-march=native" -Dprefix="/opt/mypackage/"
+
+Building
+--------
+
+From within a configured build directory, everything can be built with the
+`compile` command:
+
+    meson compile
+
+Similarly, tests can be run with the `test` command:
+
+    meson test
+
+Meson can also generate a project for several popular IDEs, see the `backend`
+option for details.
+
+Installation
+------------
+
+A compiled project can be installed with the `install` command:
+
+    meson install
+
+You may need to acquire root permissions to install to a system-wide prefix.
+The `DESTDIR` environment can be set during this command to add a path to the
+installation prefix (which is useful for packaging):
+
+    DESTDIR=/tmp/mypackage/ meson install
+
+The `--destdir` option can be used for the same purpose:
+
+    meson install --destdir=/tmp/mypackage/
+
+Compiler Configuration
+----------------------
+
+Several standard environment variables can be used to control how compilers are
+invoked:
+
+ * `CC`:       Path to C compiler
+ * `CFLAGS`:   C compiler options
+ * `LDFLAGS`:  Linker options
+
+The value of these environment variables is recorded during `meson setup`,
+they have no effect at any other stage.
+
+Note that there are also meson options that do the same thing as most of these
+environment variables, they are supported for convenience and compatibility
+with the conventions of other build systems.
diff --git a/README.md b/README.md
index f90b8c0..d5d729e 100644
--- a/README.md
+++ b/README.md
@@ -3,33 +3,42 @@ Zix
 
 Zix is a lightweight C library of portability wrappers and data structures.
 
+Components
+----------
+
+  * `ZixAllocator`: A customizable allocator.
+    * `ZixBumpAllocator`: A simple realtime-safe "bump-pointer" allocator.
+  * `ZixBitset`: A packed set of bits of arbitrary length.
+  * `ZixBTree`: A page-allocated B-tree.
+  * `ZixHash`: An open-addressing hash table.
+  * `ZixRing`: A lock-free realtime-safe ring buffer.
+  * `ZixSem`: A portable semaphore wrapper.
+  * `ZixThread`: A portable thread wrapper.
+  * `ZixTree`: A binary search tree.
+  * `zix_digest`: A hash function for arbitrary data.
+
+Platforms
+---------
+
+Zix is continually tested on:
+
+  * GNU/Linux (x86, arm32, and arm64)
+  * FreeBSD (x64)
+  * MacOS (x64)
+  * Node (as wasm via emscripten)
+
 Dependencies
 ------------
 
 None, except the C standard library.
 
-Building
---------
-
-Zix is a straightforward collection of C headers and implementation files which
-should be easy to build or incorporate into a project.
-
-A [Meson][] build definition is included which can be used to do a proper
-system installation with a `pkg-config` file, generate IDE projects, run the
-tests, and so on.  For example, the library and tests can be built and run like
-so:
-
-    meson setup build
-    cd build
-    ninja test
-
-See the [Meson documentation][] for more details on using Meson.
+Documentation
+-------------
 
-Usage
------
+Public interfaces are well-documented in the [headers](include/zix/).  There is
+no external documentation at this time.
 
-The [headers](include/zix/) are reasonably well documented.  There is no
-external documentation at this time.
+  * [Installation Instructions](INSTALL.md)
 
  -- David Robillard <d@drobilla.net>