Add tutorial and other contents for CppInterOp Documentation

Krishna-13-cyber · vgvassilev · commit 0d4ab9348fa9 · 2023-08-01T22:20:34.000Z
diff --git a/docs/DevelopersDocumentation.rst b/docs/DevelopersDocumentation.rst
@@ -4,7 +4,7 @@ Developers Documentation
 Building from source
 ---------------------
 
-Clang-Repl
+CppInterOp
 ===========
 
 .. code-block:: bash
@@ -23,9 +23,6 @@ Clang-Repl
 
     cmake --build . --target install
 
-
-CppInterOp is a C++ Language Interoperability Layer
-
 CppInterOp Internal Documentation
 =================================
 
diff --git a/docs/FAQ.rst b/docs/FAQ.rst
@@ -1,2 +1,24 @@
 FAQ 
-*****
+----
+
+1. **What is CppInterOp?**:
+
+- CppInterOp is a Clang-based C++ Interoperability library.
+
+2. **Why should you use CppInterOp?**:
+
+- It can help you to integrate C++ code with other languages, which can make your 
+code more portable and reusable.
+
+- It can help you to prototype environments for C++, which can make it easier to
+experiment with new ideas and developments.
+
+- It can help you to develop scientific applications that use C++ and other 
+languages, which can make your applications more powerful and flexible.
+
+3. **How can we integrate C++ code with other languages using CppInterOp?**:
+- You can refer the guides/tutorials here for:-
+
+- Installation And Usage Guide-:doc:`Installation and usage <InstallationAndUsage>`
+
+- Tutorials-:doc:`Tutorials <tutorials>`
diff --git a/docs/InstallationAndUsage.rst b/docs/InstallationAndUsage.rst
@@ -1,7 +1,6 @@
 InstallationAndUsage
 ---------------------
 
-
 Build cling with LLVM and clang:
 ===================================
 
@@ -29,41 +28,45 @@ Build cling with LLVM and clang:
    cmake --build . --target cling --parallel $(nproc --all)
    cmake --build . --target gtest_main --parallel $(nproc --all)
 
-Note down the llvm-project directory location as we will need it later:
+   Note down the llvm-project directory location as we will need it later:
 
    cd ../
    export LLVM_DIR=$PWD
    cd ../
 
-Clone the InterOp repo. Build it using cling and install. Note down the path to InterOp install directory. This will be referred to as INTEROP_DIR:
+   # Clone the InterOp repo. Build it using cling and install.
+   # Note down the path to InterOp install directory.
+   # This will be referred to as INTEROP_DIR:
 
    export INTEROP_DIR=$PWD/cppyy-backend/python/cppyy_backend
    git clone https://github.com/compiler-research/InterOp.git
    cd InterOp
    mkdir build && cd build
    INTEROP_BUILD_DIR=$(PWD)
-   cmake -DBUILD_SHARED_LIBS=ON -DUSE_CLING=ON -DUSE_REPL=Off -DCling_DIR=$LLVM_DIR/build -DCMAKE_INSTALL_PREFIX=$INTEROP_DIR ..
+   cmake -DBUILD_SHARED_LIBS=ON -DUSE_CLING=ON -DUSE_REPL=Off
+   -DCling_DIR=$LLVM_DIR/build -DCMAKE_INSTALL_PREFIX=$INTEROP_DIR ..
    cmake --build . --target install
 
 Build Clang-Repl:
 =================
 
-.. code-block:: text
+.. code-block:: bash
 
 
-   Get the llvm/release/16.x version:
+   # Get the llvm/release/16.x version:
    git clone https://github.com/llvm/llvm-project.git
    git checkout release/16.x
 
-   Patches for development
-   compgen -G "../patches/llvm/clang16-*.patch" > /dev/null && find ../patches/llvm/clang16-*.patch -printf "%f\n" 
+   # Patches for development
+   compgen -G "../patches/llvm/clang16-*.patch" > /dev/null
+   && find ../patches/llvm/clang16-*.patch -printf "%f\n"
    && git apply ../patches/llvm/clang16-*.patch
 
 
    mkdir build
    cd build
 
-   Build Clang-16 :
+   # Build Clang-16 :
 
       cmake -DLLVM_ENABLE_PROJECTS=clang                  \
              -DLLVM_TARGETS_TO_BUILD="host;NVPTX"          \
@@ -79,12 +82,12 @@ Build Clang-Repl:
 
       cmake --build . --target clang clang-repl --parallel $(nproc --all)
 
-   Note down the llvm-project directory location as we will need it later:
+   # Note down the llvm-project directory location as we will need it later:
    cd ../
    export LLVM_DIR=$PWD
    cd ../
 
-   Export Commands:
+   # Export Commands:
    export CB_PYTHON_DIR="$PWD/cppyy-backend/python"
    export INTEROP_DIR="$CB_PYTHON_DIR/cppyy_backend"
 
diff --git a/docs/UsingCppInterOp.rst b/docs/UsingCppInterOp.rst
@@ -1,16 +1,71 @@
 Using CppInterop
 ----------------
 
-This section briefly describes all the key functionalities offered by CppInterop.
-If you are just getting started with CppInterop, then this is the best place to start.
-You may want to skim some sections on the first read. 
+C++ Language Interoperability Layer
+===================================
 
-In case you haven't installed CppInterop already, then please do before proceeding 
-with this guide.
+The CppInterop comes with using it is a dynamic shared library, 
+**libclangInterOp.so** which resides in the CppInterOp/build/lib/.
 
-Let's get started.
+.. code-block:: bash
 
-C++ Language Interoperability Layer
-===================================
+    libInterop = ctypes.CDLL("./libclangInterOp.so")
+    
+The above method of usage is for Python; for C, we can include the headers of 
+the library. Including this library in our programme enables the user to use 
+the abilities of CppInterOp. CppInterOp helps programmers with multiple 
+verifications such as isClass, isBoolean, isStruct, and many more in different 
+languages. With the interop layer, we can access the scopes, namespaces of 
+classes and members that are being used. The interoperability layer helps us 
+with the instantiation of templates, diagnostic interaction, creation of 
+objects, and many more things.
+
+This section briefly describes all the key **features** offered by 
+CppInterop. If you are just getting started with CppInterop, then this is the 
+best place to start.
+
+Incremental Adoption
+====================
+CppInterOp can be adopted incrementally. While the rest of the framework is the 
+same, a small part of CppInterOp can be utilized. More components may be 
+adopted over time.
+
+Minimalist by design
+====================
+While the library includes some tricky code, it is designed to be simple and
+robust (simple function calls, no inheritance, etc.). The goal is to make it as
+close to the compiler API as possible, and each routine should do just one thing.
+that it was designed for.
+
+Further Enhancing the Dynamic/Automatic bindings in CPPYY
+=========================================================
+The main use case for CppInterOp is the CPPYY service. CPPYY is an
+automatic run-time bindings generator for Python and C++, and supports a wide
+range of C++ features (e.g., template instantiation). It operates on demand and
+generates only what is necessary. It requires a compiler (Cling or Clang-REPL).
+that can be available during programme runtime.
+
+Once CppInterOp is integrated with LLVM's Clang-REPL component (that can then
+be used as a runtime compiler for CPPYY), it will further enhance CPPYY's
+performance in the following ways:
+
+
+**Simpler codebase:** The removal of string parsing logic will lead to a simpler
+code base.
+
+**LLVM Integration:** The CppInterOp interfaces will be part of the LLVM 
+toolchain (as part of Clang-REPL).
+
+**Better C++ Support:** C++ features such as Partial Template Specialisation will
+be available through CppInterOp.
+
+**Fewer Lines of Code:** A lot of dependencies and workarounds will be removed,
+reducing the lines of code required to execute CPPYY.
+
+**Well tested interoperability Layer:** The CppInterOp interfaces have full
+unit test coverage.
 
 
+In case you haven't already installed CppInterop, please do so before proceeding
+with the Installation And Usage Guide.
+:doc:`Installation and usage <InstallationAndUsage>`
diff --git a/docs/reference.rst b/docs/reference.rst
@@ -1,5 +1,39 @@
 Reference
 ---------
 
-   
-   Add reference
+[1] Results of US Research Software Sustainability Institute (URSSI) 
+programming language survey, private communication from Dan Katz (UIUC/NCSA),
+https://spectrum.ieee. org/computing/software/the-2017-top-programming-languages 
+(Visited August 2021).
+
+[2] Beazley, David M. “SWIG: An Easy to Use Tool for Integrating Scripting 
+Languages with C and C++.” Tcl/Tk Workshop. Vol. 43. 1996.
+
+[3] SIP software home page, https://www.riverbankcomputing.com/ software/sip/intro (Visited Sep 2021)
+
+[4] Boost.Python Reference Manual (for software version 1.72), 
+https: //www.boost.org/doc/libs/1_65_1/libs/python/doc/html/reference/index.html, (Visited August 2021)
+
+[5] Pybind11 project homepage, http://pybind11.readthedocs.io/ (Visited August 2021).
+
+[6] ​​Vassilev, Vassil, et al. “Cling–the new interactive interpreter for ROOT 6.
+” Journal of Physics: Conference Series. Vol. 396. No. 5. IOP Publishing, 2012.
+
+[7] Cxx.jl GitHub repository, https://github.com/JuliaInterop/Cxx.jl (Visited September 2021)
+
+[8] Wim Lavrijsen, cppyy, presentation, https://compiler-research.org/meetings/#caas_02Sep2021 (Visited September 2021)
+
+[9] Cppyy Philosophy, https://cppyy.readthedocs.io/en/latest/philosophy.html#run-time-v-s-compile-time (Visited August 2021)
+
+[10] Clang: a C language family frontend for LLVM, https://clang.llvm.org/, (Visited August 2021)
+
+[11] Alexandru Militaru, Calling C++ libraries from a D-written DSL: A cling/cppyy-based approach, presentation,
+ https://compiler-research.org/meetings/#caas_04Feb2021, (Visited August 2021)
+
+[12] Keno Fischer, A brief history of Cxx.jl, https://compiler-research.org/meetings/#caas_05Aug2021, (Visited August 2021)
+
+[13] Template instantiation not happening in indirectly called function,
+ https://bitbucket.org/wlav/cppyy/issues/369/template-instantiation-not-happening-in (Visited August 2021).
+
+[14] Extend clang AST to provide information for the type as written in template instantiations,
+ https://llvm.org/OpenProjects.html#clang-template-instantiation-sugar (Visited August 2021).
diff --git a/docs/tutorials.rst b/docs/tutorials.rst
