From 0b5254b769d38398d0e224805f24bf00620adadb Mon Sep 17 00:00:00 2001
From: Dmitry Stogov <dmitry@zend.com>
Date: Thu, 5 Oct 2023 21:04:28 +0300
Subject: [PATCH] Update README.md

---
 README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 58 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index f22454d..f860950 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,16 @@
 # IR - Lightweight JIT Compilation Framework
 
-The main task of this framework is transformation of the IR (Intermediate
-Representation) into an optimized in-memory target machine code, that may
-be directly executed.
+IR Framework is a practical solution for implementing JIT in medium-size projects. 
+It defines Intermediate Representaion (IR), provies simple API for IR construction and
+a set of algorithms for optimization, scheduling, register allocation and code
+generation. The resulting generated in-memory code, may be directly executed.
 
-This is not a stable finished product yet. It’s used as a base for development
-of the next generation JIT compiler for PHP-9. There are a lot of required
-things are not implemented yet.
+This is not a stable finished product yet. It’s still under active development.
+It was started as a base for development of the next generation JIT compiler for PHP-9,
+but it's completly PHP independent.
+
+A preesentation about IR framewor design and implementation details is available at
+[researchgate](https://www.researchgate.net/publication/374470404_IR_JIT_Framework_a_base_for_the_next_generation_JIT_for_PHP).
 
 ## IR - Intermediate Representation
 
@@ -109,6 +113,10 @@ and inserts the necessary spill load/store and SSA deconstruction code.
 - GDB/JIT interface to allow debugging of JIT-ed code
 - Linux perf interface to analyze the code performance
 
+## LLVM interopability
+
+Under development...
+
 ## IR Example
 
 Let's try to generate code for the following function:
@@ -272,6 +280,50 @@ test:
 A new experimental JIT for PHP based on IR is developed at [php-ir](https://github.com/dstogov/php-src/tree/php-ir/ext/opcache/jit) branch.
 See [README-IR.md](https://github.com/dstogov/php-src/blob/php-ir/ext/opcache/jit/README-IR.md).
 
+### Building and Testing PHP with JIT based on IR Framework
+
+Install pre-requested libraries. PHP and their extensions may require different libraries.
+JIT itself needs just **libcapstone** to produce disassembler output.
+
+```
+sudo dbf install capstone-devel
+```
+
+Build PHP
+
+```
+git clone -b php-ir --single-branch git@github.com:dstogov/php-src.git php-ir
+cd php-ir
+./buildconf --force
+mkdir install
+./configure --with-capstone --prefix=`pwd`/install --with-config-file-path=`pwd`/install/etc
+make
+make install
+mkdir install/etc
+cat > install/etc/php.ini <<EOL
+zend_extension=opcache.so
+opcache.enable=1
+opcache.enable_cli=1
+opcache.optimization_level=-1
+opcache.jit_buffer_size=32M
+opcache.jit=tracing
+opcache.huge_code_pages=1
+EOL
+```
+
+Check if opcache s loaded
+
+```
+sapi/cli/php -v | grep -i opcache
+```
+
+See JIT in action
+
+```
+sapi/cli/php -d opcache.jit=tracing -d opcache.jit_debug=1 Zend/bench.php
+sapi/cli/php -d opcache.jit=function -d opcache.jit_debug=1 Zend/bench.php
+```
+
 ## References
 
 1. C. Click, M. Paleczny. “A Simple Graph-Based Intermediate Representation” In ACM SIGPLAN Workshop on Intermediate Representations (IR '95), pages 35-49, Jan. 1995.