From 48919010aa94e787314b3668ca412fd963d7cecb Mon Sep 17 00:00:00 2001 From: Luke Gorrie Date: Mon, 6 Aug 2018 09:07:34 +0000 Subject: [PATCH] README.md: revised ahead of first release --- README.md | 57 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 35 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 2b335839d5..f3504698d6 100644 --- a/README.md +++ b/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