clang/docs/ClangRepl.rst

   1 ===========
   2 Clang-Repl
   3 ===========
   4
   5 **Clang-Repl** is an interactive C++ interpreter that allows for incremental
   6 compilation. It supports interactive programming for C++ in a
   7 read-evaluate-print-loop (REPL) style. It uses Clang as a library to compile the
   8 high level programming language into LLVM IR. Then the LLVM IR is executed by
   9 the LLVM just-in-time (JIT) infrastructure.
  10
  11 Clang-Repl is suitable for exploratory programming and in places where time
  12 to insight is important. Clang-Repl is a project inspired by the work in
  13 `Cling <https://github.com/root-project/cling>`_, a LLVM-based C/C++ interpreter
  14 developed by the field of high energy physics and used by the scientific data
  15 analysis framework `ROOT <https://root.cern/>`_. Clang-Repl allows to move parts
  16 of Cling upstream, making them useful and available to a broader audience.
  17
  18
  19 Clang-Repl Basic Data Flow
  20 ==========================
  21
  22 .. image:: ClangRepl_design.png
  23    :align: center
  24    :alt: ClangRepl design
  25
  26 Clang-Repl data flow can be divided into roughly 8 phases:
  27
  28 1. Clang-Repl controls the input infrastructure by an interactive prompt or by
  29    an interface allowing the incremental processing of input.
  30
  31 2. Then it sends the input to the underlying incremental facilities in Clang
  32    infrastructure.
  33
  34 3. Clang compiles the input into an AST representation.
  35
  36 4. When required the AST can be further transformed in order to attach specific
  37    behavior.
  38
  39 5. The AST representation is then lowered to LLVM IR.
  40
  41 6. The LLVM IR is the input format for LLVM’s JIT compilation infrastructure.
  42    The tool will instruct the JIT to run specified functions, translating them
  43    into machine code targeting the underlying device architecture (eg. Intel
  44    x86 or NVPTX).
  45
  46 7. The LLVM JIT lowers the LLVM IR to machine code.
  47
  48 8. The machine code is then executed.
  49
  50 Build Instructions:
  51 ===================
  52
  53
  54 .. code-block:: console
  55
  56    $ cd llvm-project
  57    $ mkdir build
  58    $ cd build
  59    $ cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DLLVM_ENABLE_PROJECTS=clang -G "Unix Makefiles" ../llvm
  60
  61 **Note here**, above RelWithDebInfo - Debug / Release
  62
  63 .. code-block:: console
  64
  65    cmake --build . --target clang clang-repl -j n
  66       OR
  67    cmake --build . --target clang clang-repl
  68
  69 **Clang-repl** is built under llvm-project/build/bin. Proceed into the directory **llvm-project/build/bin**
  70
  71 .. code-block:: console
  72
  73    ./clang-repl
  74    clang-repl>
  75
  76
  77 Clang-Repl Usage
  78 ================
  79
  80 **Clang-Repl** is an interactive C++ interpreter that allows for incremental
  81 compilation. It supports interactive programming for C++ in a
  82 read-evaluate-print-loop (REPL) style. It uses Clang as a library to compile the
  83 high level programming language into LLVM IR. Then the LLVM IR is executed by
  84 the LLVM just-in-time (JIT) infrastructure.
  85
  86
  87 Basic:
  88 ======
  89
  90 .. code-block:: text
  91
  92   clang-repl> #include <iostream>
  93   clang-repl> int f() { std::cout << "Hello Interpreted World!\n"; return 0; }
  94   clang-repl> auto r = f();
  95    // Prints Hello Interpreted World!
  96
  97 .. code-block:: text
  98
  99    clang-repl> #include<iostream>
 100    clang-repl> using namespace std;
 101    clang-repl> std::cout << "Welcome to CLANG-REPL" << std::endl;
 102    Welcome to CLANG-REPL
 103    // Prints Welcome to CLANG-REPL
 104
 105
 106 Function Definitions and Calls:
 107 ===============================
 108
 109 .. code-block:: text
 110
 111    clang-repl> #include <iostream>
 112    clang-repl> int sum(int a, int b){ return a+b; };
 113    clang-repl> int c = sum(9,10);
 114    clang-repl> std::cout << c << std::endl;
 115    19
 116    clang-repl>
 117
 118 Iterative Structures:
 119 =====================
 120
 121 .. code-block:: text
 122
 123    clang-repl> #include <iostream>
 124    clang-repl> for (int i = 0;i < 3;i++){ std::cout << i << std::endl;}
 125    0
 126    1
 127    2
 128    clang-repl> while(i < 7){ i++; std::cout << i << std::endl;}
 129    4
 130    5
 131    6
 132    7
 133
 134 Classes and Structures:
 135 =======================
 136
 137 .. code-block:: text
 138
 139    clang-repl> #include <iostream>
 140    clang-repl> class Rectangle {int width, height; public: void set_values (int,int);\
 141    clang-repl... int area() {return width*height;}};
 142    clang-repl>  void Rectangle::set_values (int x, int y) { width = x;height = y;}
 143    clang-repl> int main () { Rectangle rect;rect.set_values (3,4);\
 144    clang-repl... std::cout << "area: " << rect.area() << std::endl;\
 145    clang-repl... return 0;}
 146    clang-repl> main();
 147    area: 12
 148    clang-repl>
 149    // Note: This '\' can be used for continuation of the statements in the next line
 150
 151 Lamdas:
 152 =======
 153
 154 .. code-block:: text
 155
 156    clang-repl> #include <iostream>
 157    clang-repl> using namespace std;
 158    clang-repl> auto welcome = []()  { std::cout << "Welcome to REPL" << std::endl;};
 159    clang-repl> welcome();
 160    Welcome to REPL
 161
 162 Using Dynamic Library:
 163 ======================
 164
 165 .. code-block:: text
 166
 167    clang-repl> %lib print.so
 168    clang-repl> #include"print.hpp"
 169    clang-repl> print(9);
 170    9
 171
 172 **Generation of dynamic library**
 173
 174 .. code-block:: text
 175
 176    // print.cpp
 177    #include <iostream>
 178    #include "print.hpp"
 179
 180    void print(int a)
 181    {
 182       std::cout << a << std::endl;
 183    }
 184
 185    // print.hpp
 186    void print (int a);
 187
 188    // Commands
 189    clang++-17  -c -o print.o print.cpp
 190    clang-17 -shared print.o -o print.so
 191
 192 Comments:
 193 =========
 194
 195 .. code-block:: text
 196
 197    clang-repl> // Comments in Clang-Repl
 198    clang-repl> /* Comments in Clang-Repl */
 199
 200
 201 Closure or Termination:
 202 =======================
 203
 204 .. code-block:: text
 205
 206    clang-repl>%quit
 207
 208
 209 Just like Clang, Clang-Repl can be integrated in existing applications as a library
 210 (using the clangInterpreter library). This turns your C++ compiler into a service that
 211 can incrementally consume and execute code. The **Compiler as A Service** (**CaaS**)
 212 concept helps support advanced use cases such as template instantiations on demand and
 213 automatic language interoperability. It also helps static languages such as C/C++ become
 214 apt for data science.
 215
 216
 217 Related Reading
 218 ===============
 219 `Cling Transitions to LLVM's Clang-Repl <https://root.cern/blog/cling-in-llvm/>`_
 220
 221 `Moving (parts of) the Cling REPL in Clang <https://lists.llvm.org/pipermail/llvm-dev/2020-July/143257.html>`_
 222
 223 `GPU Accelerated Automatic Differentiation With Clad <https://arxiv.org/pdf/2203.06139.pdf>`_