Merge pull request #74 from Soumyaworks/main

Incremental changes in README.md

Manylinux2014_Compliant_Source/pkg/setup.py

@@ -15,7 +15,7 @@
 )
 
 LLVM_LIBS = []
-VERSION = ""  
+VERSION = ""
 DESCRIPTION = ""
 
 with (pl.Path(__file__).resolve().parents[2] / "src" / "CMakeLists.txt").open() as f:

README.md

@@ -7,24 +7,48 @@ Please see [here](https://compilers.cse.iith.ac.in/projects/ir2vec/) for more de
 > IR2Vec: LLVM IR Based Scalable Program Embeddings, S. VenkataKeerthy, Rohit Aggarwal, Shalini Jain, Maunendra Sankar Desarkar, Ramakrishna Upadrasta, and Y. N. Srikant
 
 ![LLVM](https://img.shields.io/badge/LLVM-v12.0.0-blue)
+![PyPI Version](https://img.shields.io/pypi/v/your-package-name)
 ![Tests](https://github.com/IITH-Compilers/IR2Vec/workflows/Tests/badge.svg)
 ![Publish](https://github.com/IITH-Compilers/IR2Vec/workflows/Publish/badge.svg)
 ![pre-commit checks](https://github.com/IITH-Compilers/IR2Vec/workflows/pre-commit%20checks/badge.svg)
 
 ![Image](images/ir2vec.jpg)
 
 ## Table Of Contents
-* [Requirements](#requirements)
-* [Binaries and Libraries - Artifacts](#binaries-and-libraries---artifacts)
-* [Building from Source](#building-from-source)
+* [Installation](#installation)
+    * [Python](#python)
+    * [C++](#cpp)
+        * [Requirements](#requirements)
+        * [Building from Source](#building-from-source)
 * [Generating program representations](#generating-program-representations)
    * [Using Binary](#using-binary)
    * [Using Libraries](#using-libraries)
+   * [Using Python package (IR2Vec-Wheels)](#using-python-package-ir2vec-wheels)
+* [Binaries, Libraries and Wheels - Artifacts](#binaries-libraries-and-wheels---artifacts)
 * [Experiments](#experiments)
 * [Citation](#citation)
 * [Contributions](#contributions)
 * [License](#license)
 
+## Installation
+
+`IR2Vec` can be installed in different ways to accommodate individual preferences and requirements effectively. You may select to install via a user-friendly Python wheel setup if you are a Python user, or opt for a C++ based installation if you are looking to integrate with a compiler pass or necessitate advanced control and enhanced integration capabilities. The detailed setup steps are mentioned in the following sections.
+
+## Python
+
+If you prefer working with Python, you can easily install `IR2Vec` using `pip`.
+
+```
+pip install -U ir2vec
+```
+Now, you can import and use IR2Vec in your Python projects. Make sure you have a good understanding of Python and its package management system.
+
+We are actively working on improving the Python interfaces and providing better support. If you find any good-to-have interfaces that you may need for your use case missing, please feel free to raise a request.
+
+## Cpp
+
+If you're a C++ developer and require low-level control, optimization, or integration with C++ projects, you can build `IR2Vec` from source. First, ensure the below requirements are satisfied, then follow the steps mentioned in the [Building from source](#building-from-source) section.
+
 ## Requirements
 * cmake (>= 3.13.4)
 * GNU Make (4.2.1)
@@ -39,8 +63,6 @@ Please see [here](https://compilers.cse.iith.ac.in/projects/ir2vec/) for more de
 
 (Experiments are done on an Ubuntu 18.04 machine)
 
-## Binaries and Libraries - Artifacts
-Binaries and Libraries (.a and .so) are autogenerated for every relevant checkin using GitHub Actions. Such generated artifacts are tagged along with the successful runs of `Publish` workflow and can be found [here](https://github.com/IITH-Compilers/IR2Vec/actions?query=workflow%3APublish).
 
 ## Building from source
 1. `mkdir build && cd build`
@@ -58,8 +80,10 @@ This process would generate `ir2vec` binary under `build/bin` directory, `libIR2
 
 To ensure the correctness, run `make verify-all`
 
+
+
 ## Generating program representations
-`IR2Vec` can be used either as a stand alone tool using binary, or can be integrated with any third party tools using libraries. Please see below for the usage
+`IR2Vec` can be used either as a stand-alone tool using binary or can be integrated with any third-party tools using libraries. Please see below for the usage
 instructions.
 
 ### Using Binary
@@ -91,15 +115,16 @@ Please use `--help` for further details.
 >     <function-name> = <Embeddings>
 
 #### Flow-Aware Embeddings
+For all functions
 * `` ir2vec -fa -vocab vocabulary/seedEmbeddingVocab-300-llvm12.txt -o <output_file> -level <p|f>  -class <class-number> <input_ll_file>``
 
-#### Symbolic Embeddings
- * `` ir2vec -sym -vocab vocabulary/seedEmbeddingVocab-300-llvm12.txt -o <output_file> -level <p|f> -class <class-number> <input_ll_file>``
-
-#### On-demand Flow-Aware Embeddings
+For a specific function
 * `` ir2vec -fa -vocab vocabulary/seedEmbeddingVocab-300-llvm12.txt -o <output_file> -level f  -class <class-number> -funcName=\<function-name\><input_ll_file>``
 
-#### On-demand Symbolic Embeddings
+#### Symbolic Embeddings
+For all functions
+ * `` ir2vec -sym -vocab vocabulary/seedEmbeddingVocab-300-llvm12.txt -o <output_file> -level <p|f> -class <class-number> <input_ll_file>``
+For a specific function
  * `` ir2vec -sym -vocab vocabulary/seedEmbeddingVocab-300-llvm12.txt -o <output_file> -level f -class <class-number> -funcName=\<function-name\> <input_ll_file>``
 
 ## Using Libraries
@@ -159,6 +184,38 @@ for (auto val : pgmVec)
     outs() << val << "\t";
 ```
 
+## Using Python package (IR2Vec-Wheels)
+- Input:
+  - .ll/.bc file for which embeddings are needed
+  - `fa` -> Flow-Aware Encoddings; `sym` -> Symbolic Encodings
+  - `p` -> program level; `f` -> function level
+- Output:
+    - A dictionary containing:
+        - `Instruction_Dict`: Key: Instruction[String]; Value : Embedding Vector
+        - `Function_Dict`: Key: Function name[String]; Value : Embedding Vector
+        - `Program_List`: Program/Module Name[String]; Embedding Vector
+        - `Message`: [String] Appropriate debug message.
+        - `Status`: [Bool] True if everything went fine else False
+- The following code snippet contains an example to demonstrate the usage of the package.
+
+```python
+import IR2Vec as i2v
+
+emb = i2v.generateEmbeddings("/path/to/file.ll", "fa", "f")
+
+if emb["Status"]:
+    for x in emb["Function_Dict"]:
+        print("key: ", x)
+        print("Value: ", emb["Function_Dict"][x])
+    print("\n\n")
+    print(emb["Instruction_Dict"].keys())
+else:
+    print(emb["Message"])
+
+```
+## Binaries, Libraries and Wheels - Artifacts
+Binaries, Libraries (.a and .so), and whl files are autogenerated for every relevant check-in using GitHub Actions. Such generated artifacts are tagged along with the successful runs of [`Publish`](https://github.com/IITH-Compilers/IR2Vec/actions?query=workflow%3APublish) and [`Build Wheels`](https://github.com/IITH-Compilers/IR2Vec/actions/workflows/wheel.yml) actions.
+
 ## Experiments
 
 ### Note
@@ -191,7 +248,7 @@ keywords = {heterogeneous systems, representation learning, compiler optimizatio
 }
 ```
 ## Contributions
-Please feel free to raise issues to file a bug, to pose a question, or to initiate any related discussions. Pull requests are welcome :)
+Please feel free to raise issues to file a bug, pose a question, or initiate any related discussions. Pull requests are welcome :)
 
 ## License
 IR2Vec is released under a BSD 4-Clause License. See the LICENSE file for more details.