{"id":13759487,"url":"https://github.com/raptorjit/raptorjit","last_synced_at":"2025-05-10T09:32:43.016Z","repository":{"id":92088241,"uuid":"84760564","full_name":"raptorjit/raptorjit","owner":"raptorjit","description":"RaptorJIT: A dynamic language for system programming (LuaJIT fork)","archived":false,"fork":false,"pushed_at":"2024-08-22T14:22:50.000Z","size":8247,"stargazers_count":843,"open_issues_count":127,"forks_count":39,"subscribers_count":57,"default_branch":"master","last_synced_at":"2024-11-16T16:37:09.397Z","etag":null,"topics":["jit-compiler","lua","luajit"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raptorjit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-03-12T22:00:21.000Z","updated_at":"2024-11-06T14:37:31.000Z","dependencies_parsed_at":"2024-05-31T11:58:54.936Z","dependency_job_id":"27c99786-0c63-4839-abea-7a94f41e50f2","html_url":"https://github.com/raptorjit/raptorjit","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raptorjit%2Fraptorjit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raptorjit%2Fraptorjit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raptorjit%2Fraptorjit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raptorjit%2Fraptorjit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raptorjit","download_url":"https://codeload.github.com/raptorjit/raptorjit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253397258,"owners_count":21902027,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jit-compiler","lua","luajit"],"created_at":"2024-08-03T13:00:53.906Z","updated_at":"2025-05-10T09:32:42.350Z","avatar_url":"https://github.com/raptorjit.png","language":"C","funding_links":[],"categories":["C","Resources","Other"],"sub_categories":["Lua 5.1"],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"doc/raptorjit.png\" alt=\"RaptorJIT\"\u003e\u003c/p\u003e\n\n[![Build Status](https://travis-ci.org/raptorjit/raptorjit.svg?branch=master)](https://travis-ci.org/raptorjit/raptorjit)\n\n**RaptorJIT** is a Lua implementation suitable for high-performance\nlow-level system programming. If you want to use a simple dynamic\nlanguage to write a network stack; a hypervisor; a unikernel; a\ndatabase; etc, then you have come to the right place.\n\nRaptorJIT is a fork of [LuaJIT](https://luajit.org/) where we aim to\nprovide:\n\n- Ubiquitous tracing and profiling to make application\n  performance and compiler behaviour transparent to programmers.\n- Interactive tools for inspecting and cross-referencing\n  trace and profiler data ([Studio](https://github.com/studio/studio/)).\n- Collaborative and distributed development based on the Linux kernel\n  fork-and-merge model.\n\nThe most notable technical changes since forking LuaJIT are:\n\n- Added `auditlog` and `vmprofile` low-overhead (\"always on\") binary\n  tracing and profiler logging features. Removed obsoleted tracing\n  based on introspection including `jit.v`, `jit.dump`, and `jit.p`.\n- Reduced code maintenance footprint ~50% by removing `#ifdef`\n  features that are not required for Linux/x86-64 e.g. Windows\n  support, 32-bit heap support, and non-x86 backends. This is a\n  necessary short-term expedient to make the code maintainable while\n  we bootstrap the project.\n- Compiler heuristics tightened to reduce the risk of bytecode\n  blacklisting causing catastrophic performance drops.\n- Started using `git merge` to accept contributions of both code and\n  development history from other forks.\n\nRaptorJIT is used successfully by\nthe [Snabb](https://github.com/snabbco/snabb) community to develop\nhigh-performance production network equipment. Join us!\n\n### RaptorJIT compilation for users\n\nBuild using LuaJIT to bootstrap the VM:\n\n```shell\n$ make  # requires LuaJIT (2.0 or 2.1) to run DynASM\n```\n\nBuild without bootstrapping, when not hacking the VM:\n\n```shell\n$ make reusevm  # Reuse reference copy of the generated VM code\n$ make          # Does not require LuaJIT now\n```\n\n### Inspecting trace and profiler data interactively\n\nTo understand how your program executes you first produce diagnostic data (*auditlog* and *vmprofile* files) and then you inspect them interactively with [Studio](https://github.com/studio/studio).\n\nYou can produce diagnostic data on the command line:\n\n```shell\n$ raptorjit -a audit.log -p default.vmprofile ...\n```\n\nOr within your Lua code:\n\n```lua\njit.auditlog(\"audit.log\")\nlocal vmprofile = require(\"jit.vmprofile\")\nvmprofile.open(\"default.vmprofile\")\n```\n\nThen you can copy the file `audit.log` and `*.vmprofile` into a\ndirectory `/somepath` and inspect that with the Studio script:\n\n```\nwith import \u003cstudio\u003e;\nraptorjit.inspect /somepath\n```\n\nStudio will then parse, analyze, cross-reference, etc, the diagnostic\ndata and present an interactive user-interface for browsing how the\nprogram ran.\n\nHere are tutorial videos for Studio:\n\n- [How to load Snabb diagnostic data into Studio](https://www.youtube.com/watch?v=x6e1vFFpq5Q). Covers installing Studio and running a script. (Uses a Snabb-specific mechanism for producing diagnostic data which is implemented in Lua.)\n- [Inspecting RaptorJIT IR code with Studio](https://www.youtube.com/watch?v=MQyxXSPXcwg). Covers profiling and inspecting small Lua scripts. Runs Lua code directly from the Studio UI.\n\n### RaptorJIT compilation for VM hackers\n\nRaptorJIT uses [Nix](http://nixos.org/nix/) to provide a reference\nbuild environment. You can use Nix to build/test/benchmark RaptorJIT\nwith suitable versions of all dependencies provided.\n\nNote: Building with nix will be slow the first time because it\ndownloads the exact reference versions of the toolchain (gcc, etc)\nand all dependencies (glibc, etc). This is all cached for future\nbuilds.\n\n#### Build with nix\n\nInstall nix:\n\n```\n$ curl https://nixos.org/nix/install | sh\n```\n\nBuild in batch-mode and run the test suite (option 1a):\n\n```shell\n$ nix-build    # produces result/bin/raptorjit\n```\n\nBuild in batch-mode without the test suite (option 1b):\n\n```shell\n$ nix-build -A raptorjit\n```\n\nBuild interactively (option 2):\n\n```shell\n$ nix-shell    # start sub-shell with pristine build environment in $PATH\n[nix-shell]$ make -j    # build manually as many times as you like\n[nix-shell]$ exit       # quit when done\n```\n\n#### Build without nix\n\n```shell\n$ make\n```\n\n... but make sure you have at least `make`, `gcc`, and `luajit` in your `$PATH`.\n\n### Run the benchmarks\n\nNix can also run the full benchmark suite and generate visualizations\nwith R/ggplot2.\n\nThe simplest incantation tests one branch:\n\n```shell\n$ nix-build testsuite/bench --arg Asrc ./.   # note: ./. means ./\n```\n\nYou can also test several branches (A-E), give them names, specify\ncommand-line arguments, say how many tests to run, and allow parallel\nexecution:\n\n```shell\n# Run the benchmarks and create result visualizations result/\n$ nix-build testsuite/bench                     \\\n            --arg    Asrc ~/git/raptorjit       \\\n            --argstr Aname master               \\\n            --arg    Bsrc ~/git/raptorjit-hack  \\\n            --argstr Bname hacked               \\\n            --arg    Csrc ~/git/raptorjit-hack2 \\\n            --argstr Cname hacked-O1            \\\n            --argstr Cargs -O1                  \\\n            --arg    runs 100                   \\\n            -j 5           # Run up to 5 tests in parallel\n```\n\nIf you are using a distributed nix environment such\nas [Hydra](https://nixos.org/hydra/) then the tests can be\nautomatically parallelized and distributed across a suitable build\nfarm.\n\n### Optimization resources\n\nThese are the authoritative optimization resources for processors\nsupported by RaptorJIT. If you are confused by references to CPU\ndetails in discussions then these are the places to look for answers.\n\n- [Computer Architecture: A Quantitative Approach](https://www.amazon.com/Computer-Architecture-Fifth-Quantitative-Approach/dp/012383872X) by Hennessy and Patterson.\n- [Intel Architectures Optimization Reference Manual](http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html).\n- Agner Fog's [software optimization resources](http://www.agner.org/optimize/):\n    - [Instruction latency and throughput tables](http://www.agner.org/optimize/instruction_tables.pdf).\n    - [Microarchitecture of Intel, AMD, and VIA CPUs](http://www.agner.org/optimize/microarchitecture.pdf).\n    - [Optimizing subroutines in assembly language for x86](http://www.agner.org/optimize/optimizing_assembly.pdf).\n\nThe [AnandTech review of the Haswell microarchitecture](http://www.anandtech.com/show/6355/intels-haswell-architecture) is also excellent lighter reading.\n\n### Quotes\n\nHere are some borrowed words to put this branch into context:\n\n\u003e I'm outta here in a couple of days. Good luck. You'll need it.\n\u003e _[Mike Pall](http://www.freelists.org/post/luajit/Turning-Lua-into-C-was-alleviate-the-load-of-the-GC)_\n\n\u003e Optimal code is not optimal to maintain. _[Vyacheslav Egorov](https://www.youtube.com/watch?v=EaLboOUG9VQ)_\n\n\u003e If a programmer is indispensable, get rid of him as quickly as possible. _[Gerald M. Weinberg](https://www.amazon.com/Psychology-Computer-Programming-Silver-Anniversary/dp/0932633420)_\n\n\u003e If a system is to serve the creative spirit, it\n\u003e must be entirely comprehensible to a single individual. _[Dan\n\u003e Ingalls](https://www.cs.virginia.edu/~evans/cs655/readings/smalltalk.html)_\n\n\u003e The competent programmer is fully aware of the strictly limited size of his own skull; therefore he approaches the programming task in full humility, and among other things he avoids clever tricks like the plague. _[E.W. Dijkstra](https://www.cs.utexas.edu/~EWD/transcriptions/EWD03xx/EWD340.html)_\n\n\u003e There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult. _[C.A.R. Hoare](http://zoo.cs.yale.edu/classes/cs422/2014/bib/hoare81emperor.pdf)_\n\n\u003e Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it? _[Brian Kernighan](http://www2.ing.unipi.it/~a009435/issw/extra/kp_elems_of_pgmng_sty.pdf)_\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraptorjit%2Fraptorjit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraptorjit%2Fraptorjit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraptorjit%2Fraptorjit/lists"}