Move interpreter/docs into interpreter/cling/docs

This was done by a mistake when porting a PR from root-project/cling

docs/ReadTheDocs/chapters/REPL.rst

@@ -0,0 +1,28 @@
+Cling is (also, but not only) REPL
+-----------------------------------
+
+A `read-eval-print-loop
+<https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop>`_
+(**REPL**) is an interactive programming environment that takes user inputs,
+executes them, and returns the result to the user. In order to enable
+interactivity in C++, Cling provides several extensions to the C++ language:
+Defining functions in the global scope: Cling redefines expressions at a global
+level. C++ provides limited support for this, Cling possesses the necessary
+semantics to re-define code while the program is running, minimizing the
+impedance mismatch between the **REPL** and the C++ codebase, and allowing for a
+seamlessly interactive programing experience.
+
+Allows for implementation of commands which provide information about the
+current state of the environment. eg.., has an `Application Programming
+Interface <https://en.wikipedia.org/wiki/API>`_ (**API**) to provide information
+about the current state of the environment.
+
+*Error recovery*: Cling has an efficient error recovery system which allows it
+ to– handle the errors made by the user without restarting or having to redo
+ everything from the beginning.
+
+*Tight feedback loop*: It provides feedback about the results of the developer’s
+ choices that is both accurate and fast.
+
+*Facilitates debugging*: The programmer can inspect the printed result before
+ deciding what expression to provide for the next line of code.

docs/ReadTheDocs/chapters/XEUS.rst

@@ -0,0 +1,12 @@
+C++ in Jupyter Notebook - Xeus Cling
+-----------------------------------
+
+The Jupyter Notebook technology allows users to create and share documents that
+contain live code, equations, visualizations and narrative text. It enables data
+scientists to easily exchange ideas or collaborate by sharing their analyses in
+a straight-forward and reproducible way.Jupyter’s official C++ kernel
+(Xeus-Cling) relies on Xeus, a C++ implementation of the kernel protocol, and
+Cling.  Using C++ in the Jupyter environment yields a different experience to
+C++ users. For example, Jupyter’s visualization system can be used to render
+rich content such as images, therefore bringing more interactivity into the
+Jupyter’s world.

docs/ReadTheDocs/chapters/background.rst

@@ -0,0 +1,18 @@
+When and why was Cling developed?
+--------------------------------------------
+
+Cling is a core component of `ROOT
+<https://github.com/sarabellei/rtd_tutorial/edit/main/docs/source/index.rst>`_
+providing essential functionality for the analysis of the vast amounts of very
+complex data produced by the experimental high-energy physics community,
+enabling interactive exploration, dynamic interoperability and rapid prototyping
+capabilities to C++ developers. It was first released in 2014 with the aim to
+facilitate the processing of scientific data in the field of high-energy physics
+as the interactive, C++ interpreter in ROOT.  ROOT is an open-source program
+written primarily in C++, developed by research groups in high-energy physics
+including `CERN <https://home.cern/>`_, `FERMILAB <https://www.fnal.gov/>`_ and
+`Princeton <https://www.princeton.edu/>`_ , and now used by most high-energy
+physics experiments. CERN is an European research organization that operates the
+largest particle physics laboratory in the world. Its experiments collect
+petabytes of data per year to be serialized, analyzed, and visualized as C++
+objects.

docs/ReadTheDocs/chapters/conclusion.rst

@@ -0,0 +1,11 @@
+Conclusion
+-----------------------------------
+
+Cling is not just a REPL, it is an embeddable and extensible execution system
+for efficient incremental execution of C++. Cling allows us to decide how much
+we want to compile statically and how much to defer for the target
+platform. Cling enables reflection and introspection information in
+high-performance systems such as ROOT, or Xeus Jupyter, where it provides
+efficient code for performance-critical tasks where hot-spot regions can be
+annotated with specific optimization levels. We will see more concrete examples
+in the slides to follow.

docs/ReadTheDocs/chapters/cudaC++.rst

@@ -0,0 +1,13 @@
+Interactive CUDA C++ with Cling 
+-----------------------------------
+
+The Cling CUDA extension brings the workflows of interactive C++ to GPUs,
+without losing performance and compatibility to existing software.  Through this
+extension, C++ and CUDA can be used interactively on the target machine,
+allowing for optimization for particular models of accelerator hardware. The
+extension can be run on a Jupyter setup. Cling CUDA found application in the
+field of modeling of high-energy particles and radiation produced by high-energy
+laser facilities. In this framework, Cling CUDA allows for an interactive
+approach which enables relaunching only a wanted part of a simulation, starting
+from a given point which can be decided by the user.
+

docs/ReadTheDocs/chapters/grammar.rst

@@ -0,0 +1,70 @@
+Command Line
+=====
+
+Cling has its own command line, which looks like any other Unix shell. The
+emacs-like command line editor is what we call interactive command line or
+interactive shell.
+
+Once we start Cling it automatically includes several header files and its own
+runtime universe. Thus it creates the minimal environment for the user to start.
+
+
+
+Grammar
+------------
+
+Cling is capable to parse everything that `Clang <https://clang.llvm.org/>`_ can
+do. In addition, Cling can parse some interpreter-specific C++ extensions.
+
+Metaprocessor
+------------
+
+Cling Metaprocessor provides convenient and easy to use interface for changing
+the interpreter’s internal state or for executing handy commands. Cling provides
+the following metaprocessor commands:
+
+**syntax: .(command)**, where command is:
+
+
+.. code:: bash
+
+    x filename.cxx
+    
+loads filename and calls void filename() if defined;
+
+
+.. code:: bash
+
+    L library | filename.cxx
+    
+loads library or filename.cxx;
+
+
+.. code:: bash
+
+   printAST
+    
+(DEBUG ONLY) shows the abstract syntax tree after each processed entity;
+
+
+.. code:: bash
+
+   I path
+    
+adds an include path;
+
+
+.. code:: bash
+
+   .@ 
+
+Cancels the multiline input;
+
+
+.. code:: bash
+
+   .dynamicExtensions
+
+Turns on cling's dynamic extensions. This in turn enables the dynamic lookup and
+the late resolving of the identifier. With that option cling tries to heal the
+compile-time failed lookups at runtime.

docs/ReadTheDocs/chapters/implementation.rst

@@ -0,0 +1,31 @@
+Used Technology
+-----------------------------------
+
+`LLVM <https://llvm.org/>`_ is a free, open-source compiler infrastructure under
+the `Apache License 2.0 <https://www.apache.org/licenses/LICENSE-2.0>`_. It is
+designed as a collection of tools including Front Ends parsers, Middle Ends
+optimizers, and Back Ends to produce machine code out of those programs.
+
+`Clang <https://clang.llvm.org/>`_ is a front-end that uses a LLVM
+license. Clang works by taking the source language (e.g. C++) and translating it
+into an intermediate representation that is then received by the compiler back
+end (i.e., the LLVM backend). Its library-based architecture makes it relatively
+easy to adapt Clang and build new tools based on it.  Cling inherits a number of
+features from LLVM and Clang, such as: fast compiling and low memory use,
+efficient C++ parsing, extremely clear and concise diagnostics, Just-In-Time
+compilation, pluggable optimizers, and support for `GCC <https://gcc.gnu.org/>`_
+extensions.
+
+Interpreters allow for exploration of software development at the rate of human
+thought. Nevertheless, interpreter code can be slower than compiled code due to
+the fact that translating code at run time adds to the overhead and therefore
+causes the execution speed to be slower. This issue is overcome by exploiting
+the *Just-In-Time* (`JIT
+<https://en.wikipedia.org/wiki/Just-in-time_compilation>`_) compilation
+method. With the JIT approach, assembly is generated by the interpreter with a
+pseudocode (an `intermediate language
+<https://en.wikipedia.org/wiki/Common_Intermediate_Language>`_ that is not
+understood by the computer). The intermediate code is then translated into
+machine language when required for use.  By following the JIT approach, Cling is
+able to evaluate whether a certain part of the source code is executed often,
+and then compile this part, therefore reducing the overall execution time.

docs/ReadTheDocs/chapters/interactivity.rst

@@ -0,0 +1,35 @@
+Interactivity in C++ with Cling
+-----------------------------------
+
+**Interactive programming** is a programming approach allowing developers to
+change and modify the program as it runs. The final result is a program that
+actively responds to a developers’ intuitions, allowing them to make changes in
+their code, and to see the result of these changes without interrupting the
+running program. Interactive programming gives programmers the freedom to
+explore different scenarios while developing software, writing one expression at
+a time, figuring out what to do next at each step, and enabling them to quickly
+identify and fix bugs whenever they arise.  As an example, the High-Energy
+Physics community includes professionals with a variety of backgrounds,
+including physicists, nuclear engineers, and software engineers. Cling allows
+for interactive data analysis in `ROOT
+<https://github.com/sarabellei/rtd_tutorial/edit/main/docs/source/index.rst>`_
+by giving researchers a way to prototype their C++ code, allowing them to tailor
+it to the particular scope of the analysis they want to pursue on a particular
+set of data before being added to the main framework.
+
+
+**Interpreted language** is a way to achieve interactive programming. In
+ statically compiled language, all source code is converted into native machine
+ code and then executed by the processor before being run. An interpreted
+ language instead runs through source programs line by line, taking an
+ executable segment of source code, turning it into machine code, and then
+ executing it. With this approach, when a change is made by the programmer, the
+ interpreter will convey it without the need for the entire source code to be
+ manually compiled. Interpreted languages are flexible, and offer features like
+ dynamic typing and smaller program size.
+
+**Cling** allows C++, a language designed to be compiled, to be
+ interpreted. When using Cling, the programmer benefits from both the power of
+ C++ language, such as high-performance, robustness, fastness, efficiency,
+ versatility, and the capability of an interpreter, which allows for interactive
+ exploration and on-the-fly inspection of the source-code.

docs/ReadTheDocs/chapters/references.rst

@@ -0,0 +1,105 @@
+Literature
+=====
+
+
+What is Cling?
+------------
+
+`Relaxing the One Definition Rule in Interpreted C++
+<https://dl.acm.org/doi/10.1145/3377555.3377901>`_
+
+*Javier Lopez Gomez et al.*, 29th International Conference on Compiler
+ Construction, 2020
+
+*This paper discusses how Cling enables redefinitions of C++ entities at the
+ prompt, and the implications of interpreting C++ and the One Definition Rule
+ (ODR) in C++*
+
+`Cling – The New Interactive Interpreter for ROOT 6
+<https://iopscience.iop.org/article/10.1088/1742-6596/396/5/052071>`_
+
+*V Vasilev et al* 2012 J. Phys.: Conf. Ser. 396 052071
+
+*This paper describes the link between Cling and ROOT. The concepts of REPL and
+ JIT compilation. Cling’s methods for handling errors, expression evaluation,
+ streaming out of execution results, runtime dynamism.*
+
+`Interactive, Introspected C++ at CERN
+<https://www.youtube.com/watch?v=K2KqEV866Ro>`_
+
+*V Vasilev*, CERN PH-SFT, 2013
+
+*Vassil Vasilev (Princeton University) explains how Cling enables interactivity
+ in C++, and illustrates the type introspection mechanism provided by the
+ interpreter.*
+
+`Introducing Cling, a C++ Interpreter Based on Clang/LLVM
+<https://www.youtube.com/watch?v=f9Xfh8pv3Fs>`_
+
+*Axel Naumann* 2012  Googletechtalks
+
+*Axel Naumann (CERN) discusses Cling’s most relevant features: abstract syntax
+ tree (AST) production, wrapped functions, global initialization of a function,
+ delay expression evaluation at runtime, and dynamic scopes.*
+
+`Creating Cling, an interactive interpreter interface
+<https://www.youtube.com/watch?v=BjmGOMJWeAo>`_
+
+*Axel Naumann* 2010 LLVM Developers’ meeting
+
+*This presentation introduces Cling, an ahead-of-time compiler that extends C++
+ for ease of use as an interpreter.*
+
+.. list-table:: Title
+   :widths: 25 25 50
+   :header-rows: 1
+
+   * - Link
+     - Info 
+     - Description
+   * - `Relaxing the One Definition Rule in Interpreted C++
+     <https://dl.acm.org/doi/10.1145/3377555.3377901>`_
+     - *Javier Lopez Gomez et al.*
+       
+       29th International Conference on Compiler Construction 2020
+     - This paper discusses how Cling enables redefinitions of C++ entities at the prompt, and the implications of interpreting C++ and the One Definition Rule (ODR) in C++
+   * - `Cling – The New Interactive Interpreter for ROOT 6
+     <https://iopscience.iop.org/article/10.1088/1742-6596/396/5/052071>`_
+     - *V Vasilev et al* 2012 J. Phys.: Conf. Ser. 396 052071
+     - This paper describes the link between Cling and ROOT. The concepts of
+       REPL and JIT compilation. Cling’s methods for handling errors, expression
+       evaluation, streaming out of execution results, runtime dynamism.
+   * - `Interactive, Introspected C++ at CERN
+     <https://www.youtube.com/watch?v=K2KqEV866Ro>`_
+     - *V Vasilev*, CERN PH-SFT, 2013
+     - Vassil Vasilev (Princeton University) explains how Cling enables
+       interactivity in C++, and illustrates the type introspection mechanism
+       provided by the interpreter.
+   * - `Introducing Cling, a C++ Interpreter Based on Clang/LLVM
+     <https://www.youtube.com/watch?v=f9Xfh8pv3Fs>`_
+     - *Axel Naumann* 2012  Googletechtalks
+     - Axel Naumann (CERN) discusses Cling’s most relevant features: abstract
+       syntax tree (AST) production, wrapped functions, global initialization of
+       a function, delay expression evaluation at runtime, and dynamic scopes.
+   * - `Creating Cling, an interactive interpreter interface
+     <https://www.youtube.com/watch?v=BjmGOMJWeAo>`_
+     - *Axel Naumann* 2010 LLVM Developers’ meeting
+     - This presentation introduces Cling, an ahead-of-time compiler that
+       extends C++ for ease of use as an interpreter.
+
+
+Demos, tutorials, Cling’s ecosystem:
+------------
+
+
+Language Interoperability with Cling:
+------------
+
+Cling for interactive CUDA C++:
+------------
+
+Cling on Jupyter:
+------------
+
+Clad:
+------------

docs/ReadTheDocs/chapters/why_interpreting.rst

@@ -0,0 +1,74 @@
+Why interpreting C++ with Cling?
+-----------------------------------
+
+1. **Learning C++**
+   
+   One use case of Cling is to aid the C++ learning process. Offering imediate
+   feedback the user can easily get familiar with the structures and spelling of
+   the language.
+
+2. **Creating scripts**
+   
+   The power of an interpreter lays as well in the compactness and ease of
+   repeatedly running a small snippet of code - aka a script. This can be done
+   in cling by inserting the bash-like style line:
+
+.. code:: bash
+   
+   #!/usr/bin/cling
+   
+3. **Rapid Application Development (RAD)**
+
+   Cling can be used successfully for Rapid Application Development allowing for
+   prototyping and proofs of concept taking advantage of dynamicity and feedback
+   during the implementation process.
+
+4. **Runtime-Generated Code**
+
+   Sometime it's convenient to create code as a reaction to input
+   (user/network/configuration). Runtime-generated code can interface with C++
+   libraries.
+   
+   
+Embedding Cling:
+-----------------------------------
+
+The functionality of an application can be enriched by embedding Cling. To embed
+Cling, the main program has to be provided. One of the things this main program
+has to do is initialize the Cling interpreter. There are optional calls to pass
+command line arguments to Cling. Afterwards, you can call the interpreter from
+any anywhere within the application.
+
+For compilation and linkage the application needs the path to the Clang and LLVM
+libraries and the invocation is order dependent since the linker cannot do
+backward searches.
+
+.. code:: bash
+
+   g++ embedcling.cxx -std=c++11 -L/usr/local/lib
+                    -lclingInterpreter -lclingUtils 
+                    -lclangFrontend -lclangSerialization -lclangParse -lclangSema 
+                    -lclangAnalysis -lclangEdit -lclangLex -lclangDriver -lclangCodeGen 
+                    -lclangBasic  -lclangAST  
+                    `llvm-config 
+                      --libs bitwriter mcjit orcjit native option 
+                        ipo profiledata instrumentation objcarcopts` 
+                      -lz -pthread -ldl -ltinfo 
+                    -o embedcling
+                    
+Embedding Cling requires the creation of the interpreter. Optionally compiler
+arguments and the resource directory of LLVM can be passed. An example is the
+following:
+
+.. code:: bash
+
+   #include "cling/Interpreter/Interpreter.h"
+
+   int main(int argc, char** argv) {
+      const char* LLVMRESDIR = "/usr/local/"; //path to llvm resource directory
+      cling::Interpreter interp(argc, argv, LLVMRESDIR);
+
+      interp.declare("int p=0;");
+    }
+        
+A more complete example could be found in `<tools/demo/cling-demo.cpp>`_.

docs/ReadTheDocs/conf.py

@@ -0,0 +1,36 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information
+
+project = 'Cling'
+copyright = '2022, Cling'
+author = 'Sara Bellei'
+
+release = '0.1'
+version = '0.1.0'
+
+# -- General configuration
+
+extensions = [
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
+intersphinx_disabled_domains = ['std']
+
+templates_path = ['_templates']
+
+# -- Options for HTML output
+
+html_theme = 'sphinx_rtd_theme'
+
+# -- Options for EPUB output
+epub_show_urls = 'footnote'
+

docs/ReadTheDocs/index.rst

@@ -0,0 +1,42 @@
+Cling interprets C++
+=======================================
+
+.. figure:: images/fig1.jpeg
+
+**Cling** is an interactive C++ interpreter built on top of `Clang
+<https://clang.llvm.org/>`_ and `LLVM <https://llvm.org/>`_.  It uses LLVM's
+*Just-In-Time* (`JIT <https://en.wikipedia.org/wiki/Just-in-time_compilation>`_)
+compiler to provide a fast and optimized compilation pipeline. Cling uses the
+`read-eval-print-loop
+<https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop>`_
+(**REPL**) approach, making rapid application development in C++ possible,
+avoiding the classic edit-compile-run-debug cycle approach.
+
+
+Cling's last release, download instructions, dependencies, and any other useful
+information for developers can be found on `Cling's GitHub webpage
+<https://github.com/vgvassilev/cling>`_.
+
+Find out more about **Interpreting C++** on the `Compiler Research Group
+<https://compiler-research.org/>`_'s webpage.
+   
+
+Table of Contents
+--------
+
+ .. toctree::
+    :numbered:
+   
+    chapters/background
+    chapters/interactivity
+    chapters/implementation
+    chapters/REPL
+    chapters/XEUS
+    chapters/cudaC++
+    chapters/grammar
+    chapters/references
+
+.. note::
+
+  This project is under active development.
+  Cling has its documentation hosted on Read the Docs.