Documentation update (#73)

* Updating debugger documentation

* Updating docs

* Updating docs

* Fixing issue #59

* Removing unwanted files

* Updating documentation and fixing issues in the profile generator

* Creating commant for formatting

* Creating commant for formatting

* Updating docker image

* Finishing issue #10

* Formatting

* Fixing tests

* Resolving #45

* Updating for CI to pass

* Removing .orig files

Makefile

@@ -24,6 +24,10 @@ linux-docker:
 linux-ci: linux-docker
 	docker run -it -v ${PWD}:/src --rm -t qir-passes-ubuntu:latest ./manage runci
 
+format-in-docker: linux-docker
+	docker run -it --rm -v ${PWD}:/src/ -t qir-passes-ubuntu:latest ./manage stylecheck --fix-issues
+
+
 test-examples:
 	mkdir -p Debug
 	cd Debug && cmake .. && make qat

docs/src/DeveloperGuide/ArchitectureOverview.md

@@ -57,15 +57,15 @@ similar mechanism that allows to activate or deactivate existing (and new) LLVM
 passes. We would thus need something like
 
 ```sh
-qat --always-inline --apply -S filename.ll
+qat --always-inline --profile base --apply -S filename.ll
 ```
 
 where `--apply` tells the tool to apply the profile and `-S` tells the tool to
 emit human readable LLVM IR code. Furthermore, if the inline pass is provided as
 an external module, we would need to be able load it
 
 ```sh
-qat --always-inline --load path/to/lib.(dylib|so|dll) --apply -S filename.ll
+qat --always-inline --profile base --load path/to/lib.(dylib|so|dll) --apply -S filename.ll
 ```
 
 We note that from a developer point of view, the underlying code would also need
@@ -118,4 +118,101 @@ needs while benefiting from the components that QAT ships with.
 
 ## Architecture description
 
-TODO(issue-9): Yet to be written
+On a high level, the process of the IRs can be divided into three main tasks: 1)
+Loading the QIR, 2) creating a generator and validator and 3) transform and
+validate the QIR. We summarize this process in the diagram below, listing the
+components and settings used in the process and how they feed into one and
+another:
+
+```text
+┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐
+                         User input
+└ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┬ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
+┌─────────────────────────────▼─────────────────────────────┐
+│            Configuration and parameter parser             │
+└─────────────┬───────────────────────────────┬─────────────┘
+┌─────────────▼─────────────┐   ┌─────────────▼─────────────┐
+│        IR file list       │   │      Profile config       │
+└─────────────┬─────────────┘   └─────────────┬─────────────┘
+┌─────────────▼─────────────┐   ┌─────────────▼─────────────┐
+│       Module loader       │   │     Profile Generator     │
+└─────────────┬─────────────┘   └─────────────┬─────────────┘
+┌─────────────▼─────────────┐   ┌─────────────▼─────────────┐
+│       Single module       │   │          Profile          │
+│      transformations      │   └──────┬──────────────┬─────┘
+└─────────────┬─────────────┘   ┌──────▼─────┐ ┌──────▼─────┐
+┌─────────────▼─────────────┐   │            │ │            │
+│   Adding debug symbols    ├───▶ Generation ├─┼▶Validation ├─────┐
+└───────────────────────────┘   │            │ │            │     │
+                                └──────┬─────┘ └──────┬─────┘     │
+                                ┌──────▼──────────────▼─────┐     │
+                                │          Logger           │     │
+                                └───────────────────────────┘     │
+                                              │                   │
+                                              ▼                   ▼
+                                     ┌ ─ ─ ─ ─ ─ ─ ─ ─ ┐┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐
+                                       Standard error     Standard Output:
+                                     │    or file:     ││   Resulting IR    │
+                                          JSON Logs
+                                     └ ─ ─ ─ ─ ─ ─ ─ ─ ┘└ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
+```
+
+The profile consists of a generator and a validator. The generator is
+responsible for performing as many transformations as possible to get the
+original QIR to be compliant with the selected profile. This is done by each of
+the components taking a configuration which then installs LLVM passes to execute
+said transactions. This is illustrated on the left hand-side in the following
+figure whereas the pass execution is illustrated on the right hand-side:
+
+```text
+                                                    ┌ ─ ─ ─ ─ ─ ─ ─ ┐
+                                                       LLVM module
+┌───┐                                               └ ─ ─ ─│─ ─ ─ ─ ┘
+│   │                                                      │ Apply profile
+│ C │                                                      │ process
+│ o │                                     ┌ Generator ─ ─ ─│─ ─ ─ ─ ─
+│ n │If                                            ┌───────▼───────┐ │
+│ f │component                     Install│        │  Inline pass  │
+│ i │active:  ┌───────────────────┐passes   ┌───┐  └───────┬───────┘ │
+│ g ├─────────▶    LLVM passes    │───────┼─▶   │  ┌───────▼───────┐
+│ u │         └───────────────────┘         │   │  │  Unroll pass  │ │
+│ r │                                     │ │ P │  └───────┬───────┘
+│ a │         ┌───────────────────┐         │ a │  ┌───────▼───────┐ │
+│ t ├─────────▶  Transformation   │───────┼─▶ s │  │Transform pass │
+│ i │         └───────────────────┘         │ s │  └───────┬───────┘ │
+│ o │                                     │ │   │  ┌───────▼───────┐
+│ n │         ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐         │ m │  │  Inline pass  │ │
+│   ├─────────▶    LLVM passes     ───────┼─▶ a │  └───────┬───────┘
+│ m │         └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘         │ n │  ┌───────▼───────┐ │
+│ a │                                     │ │ a │  │   Fold pass   │
+│ n │         ┌───────────────────┐         │ g │  └───────┬───────┘ │
+│ a ├─────────▶     Grouping      │───────┼─▶ e │  ┌───────▼───────┐
+│ g │         └───────────────────┘         │ r │  │  Group pass   │ │
+│ e │                                     │ │ s │  └───────┬───────┘
+│ r │                                       │   │          │         │
+│   │                                     │ │   │          │
+└───┘                                       └───┘          │         │
+                                          └ ─ ─ ─ ─ ─ ─ ─ ─│─ ─ ─ ─ ─
+                                                           │
+                                                   ┌ ─ ─ ─ ▼ ─ ─ ─ ┐
+                                                     Output module
+                                                   └ ─ ─ ─ ─ ─ ─ ─ ┘
+```
+
+For each component available, QAT checks if the component is active and if it
+is, the components setup function is ran with its configuration class. This
+class can be configured from the command line or through the profile. We note
+that the figure does not contain a comprehensive list of passes that can be
+installed. Whether or not any of the listed passes is added to the pass managers
+is happening at the discretion of each of the components and is further subject
+to the configuration provided to these components. This means that depending on
+the profile configuration, the pass may perform one task or another. This is in
+particular true for the transformation pass which uses a set of rules to perform
+replacements in the IR.
+
+The transformation component is a highly configurable component that does
+replacements of pieces of the DAG in the IR with using a custom replacer
+function. The infrastructure is written such that it is possible to express a
+new pattern in just a couple of lines and the developer can focus on the
+replacement routine rather than the task of capturing the right segment of
+instructions.

docs/src/DeveloperGuide/CodeQuality.md

@@ -47,23 +47,30 @@ version and on different platforms, it is recommended that you use a Docker
 image to perform these steps. TODO(issue-10): The Docker image is not added yet
 and this will be documented in the future.
 
-## Running tests
+## Style checking using Docker
 
-In order to run the tests, you first need to build the library. Assuming that
-this is already done and the corresponding build is in `Debug/`, run the tests
-from the `Debug` folder:
+In some cases it is not possible to replicate the necessary toolchain to perform
+style checks on the code. To address this, this repository is equipped with a
+Docker image that allows the developer to run the CI script:
 
 ```sh
-lit tests/ -v
--- Testing: 2 tests, 2 workers --
-PASS: Quantum-Passes :: QirAllocationAnalysis/case1.ll (1 of 2)
-PASS: Quantum-Passes :: QirAllocationAnalysis/case2.ll (2 of 2)
+make linux-ci
+```
 
-Testing Time: 0.27s
-  Passed: 2
+as well as automatically fix style issues where possible:
+
+```sh
+make format-in-docker
 ```
 
-The C++ test suite can also be ran from the debug by first building all targets:
+The latter command will mount the current source directory inside docker and use
+the Ubuntu image to run the style check. This image was created with the version
+of the tool that is officially supported by the maintainers.
+
+## Running tests
+
+In order to run the tests, you first need to build the library. Assuming that
+this is already done and the corresponding build is in `Debug/`:
 
 ```sh
 cmake ..

docs/src/UserGuide/BuildingLibrary.md

@@ -65,22 +65,46 @@ tools and packages are used:
 - Python packages specified in `requirements.txt`
 - clang-format
 - clang-tidy
+- NodeJS & Prettier
 
 The installation process varies depending on the platform you use. The following
 subsections provide details on how to install these tools on each platform.
 
 ### On macOS
 
-TODO(issue-45): Create developer prerequisites for macOS in docs.
+To install LLVM version 11, we use the `brew` package `llvm@11` which will
+install the LLVM libraries alongside with Clang 11, Clang format and Clang Tidy:
+
+```sh
+brew install llvm@11
+```
+
+Python and NodeJS can also be installed using `brew`:
+
+```sh
+brew install [email protected] node@16
+```
+
+After successful installation, you may need to update your environment variables
+to ensure that CMake will use the right version of Clang as well as the LLVM
+libraries:
+
+```sh
+export CC=clang-11
+export CXX=clang++-11
+export LDFLAGS="-L/usr/local/opt/llvm@11/lib -Wl,-rpath,/usr/local/opt/llvm@11/lib"
+export CPPFLAGS="-I/usr/local/opt/llvm@11/include"
+```
 
 ### On Ubuntu 20.04
 
-Installing the Clang tools on Ubuntu along with Python can be accomplished by
-running these commands:
+Installing the Clang tools on Ubuntu along with Python and NodeJS can be
+accomplished by running these commands:
 
 ```sh
 apt install clang-format-13 clang-tidy-13
 apt install python3 python3-pip
+apt install nodejs npm
 ```
 
 We recommend that you use version 13 of Clang in order to be consistent with the
@@ -98,8 +122,9 @@ export CXX=clang++-13
 Last but not least, we install the Python libraries that are required:
 
 ```sh
-      pip install -r requirements.txt
-      chmod +x manage
+pip install -r requirements.txt
+chmod +x manage
+npm install -g [email protected]
 ```
 
 As a result, the `manage` tool will be available for you to help you make sure
@@ -121,7 +146,17 @@ git submodule update --init --recursive
 
 ### Installing LLVM on macOS
 
-TODO(issue-45): Document installation process
+If you have previously installed the packages under
+[Developer prerequisites](#developer-prerequisites), you do not need to take any
+additional steps for macOS. If you are relying on the natively installed Clang,
+you may need to install the LLVM libraries:
+
+```sh
+brew install llvm@11
+```
+
+Additionally, you may need to update your `LDFLAGS` and `CPPFLAGS` for the
+toolchain to work properly.
 
 ### Installing LLVM on Ubuntu 20.04