Merge pull request #178 from lukego/readme-update

README.md: revised ahead of first release

README.md

@@ -2,25 +2,39 @@
 
 [![Build Status](https://travis-ci.org/raptorjit/raptorjit.svg?branch=master)](https://travis-ci.org/raptorjit/raptorjit)
 
-**RaptorJIT** is a fork of LuaJIT focused on _predictably high performance_.
-
-Making performance predictable for application developers brings new requirements:
-
-- Minimizing the performance impact of non-deterministic JIT decisions.
-- Providing an accurate mental model of how the JIT works and which programming techniques are effective.
-- Providing diagnostic tools ([Studio](https://hydra.snabb.co/job/lukego/studio-manual/studio-manual-html/latest/download-by-type/file/Manual#view-hot-traces)) consistent with this mental model to make the actual operation transparent.
-- Making profiling completely ubiquitous in development, testing, and production environments.
-
-The development process has to support moving quickly in these directions:
-
-- Quality assurance based on repeatable standard benchmarks executed by CI.
-- Streamlined codebase: x86-64 architecture, Linux kernel, 64-bit heap (GC64), "no `#ifdef`."
-- Distributed development with many maintainers, forks, and merges.
-
-Once these requirements have been thoroughly satisfied then new
-requirements can be introduced. For example, new architectures like
-ARM64 and operating systems like MacOS can be supported as the project
-matures.
+**RaptorJIT** is a Lua implementation suitable for high-performance
+low-level system programming. If you want to use a simple dynamic
+language to write a network stack; a hypervisor; a unikernel; a
+database; etc, then you have come to the right place.
+
+RaptorJIT is a fork of [LuaJIT](https://luajit.org/) where we aim to
+provide:
+
+- Ubiquitous tracing and profiling to make application
+  performance and compiler behaviour transparent to programmers.
+- Interactive tools for inspecting and cross-referencing
+  trace and profiler data ([Studio](https://github.com/studio/studio/)).
+- Collaborative and distributed development based on the Linux kernel
+  fork-and-merge model.
+
+The most notable technical changes since forking LuaJIT are:
+
+- Added `auditlog` and `vmprofile` low-overhead ("always on") binary
+  tracing and profiler logging features. Removed obsoleted tracing
+  based on introspection including `jit.v`, `jit.dump`, and `jit.p`.
+- Reduced code maintenance footprint ~50% by removing `#ifdef`
+  features that are not required for Linux/x86-64 e.g. Windows
+  support, 32-bit heap support, and non-x86 backends. This is a
+  necessary short-term expedient to make the code maintainable while
+  we bootstrap the project.
+- Compiler heursitics tightened to reduce the risk of bytecode
+  blacklisting causing catastrophic performance drops.
+- Started using `git merge` to accept contributions of both code and
+  development history from other forks.
+
+RaptorJIT is used successfully by
+the [Snabb](https://github.com/snabbco/snabb) community to develop
+high-performance production network equipment. Join us!
 
 ### Performance
 
@@ -39,14 +53,13 @@ The CI benchmark suite will evolve over time starting from the [standard LuaJIT
 
 ### Compilation for users
 
-Simple build:
+Build using LuaJIT to bootstrap the VM:
 
 ```shell
 $ make  # requires LuaJIT (2.0 or 2.1) to run DynASM
 ```
 
-Alternative if you don't have LuaJIT available and you are building a
-pristine copy from the master branch:
+Build without bootstrapping, when not hacking the VM:
 
 ```shell
 $ make reusevm  # Reuse reference copy of the generated VM code