feat: add docs

README.md

@@ -43,10 +43,11 @@ This README.md itself mostly records **LLVM backend** resources; for **Clang**-s
   - 🐉 [Create A Project](http://llvm.org/docs/Projects.html)
   - 🐉 [Exception Handling in LLVM](http://llvm.org/docs/ExceptionHandling.html)
 - 🐉 [CommandLine 2.0 Library Manual](http://llvm.org/docs/CommandLine.html) - LLVM's CLI option parser library, used by all LLVM CLI tools etc
-- 🐉 [Getting Started with the LLVM System](http://llvm.org/docs/GettingStarted.html) - LLVM project's build, configurations, directory layouts, etc
+- 🐉 [Getting Started with the LLVM System](http://llvm.org/docs/GettingStarted.html) - LLVM project's build, configurations, directory layouts etc
 - 🐉 [LLVM’s Analysis and Transform Passes](http://llvm.org/docs/Passes.html)
-  - 🐉 [LLVM Alias Analysis Infrastructure](http://llvm.org/docs/AliasAnalysis.html)
+  - 🐉 [Using the New Pass Manager](https://llvm.org/docs/NewPassManager.html) - LLVM's new pass manager for optimization (both CLI and API changed)
   - 🐉 [Writing an LLVM Pass](http://llvm.org/docs/WritingAnLLVMPass.html)
+  - 🐉 [LLVM Alias Analysis Infrastructure](http://llvm.org/docs/AliasAnalysis.html)
 - 🐉 [LLVM Testing Infrastructure Guide](http://llvm.org/docs/TestingGuide.html)
 - 🐉 [Writing an LLVM Backend](http://llvm.org/docs/WritingAnLLVMBackend.html)
 - 🐉 [LLVM FAQ](http://llvm.org/docs/FAQ.html)

docs/.gitignore

@@ -0,0 +1,2 @@
+build/
+.cache/

docs/opt.md

@@ -0,0 +1,3 @@
+```bash
+
+```

docs/optimizations.md

@@ -1,3 +1,5 @@
+# Control optimization from Clang Driver
+
 If you produced the .ll file with a command line along the lines of `clang –c –O0 –emit-llvm …`,
 then the IR functions will be annotated with the `optnone` attribute.
 If you don't want that, a better command line would be `clang –c –O2 –Xclang –disable-llvm-passes –emit-llvm …`

docs/whole-program-llvm.md

@@ -0,0 +1,13 @@
+# Motivation
+
+When applying analysis, we usually need to work on a `linked` LLVM bitcode file, rather than multiple bitcode files.
+
+# using `llvm-link`
+This requires each step of compilation to generate `bc` files and then apply `llvm-link` against all `bc` files.
+
+# using `gold link`
+Adding flags `-flto -fuse-ld=lld -Wl,-save-temps` to generate the temporal bc files.
+
+# using `wllvm` or `gllvm`
+[wllvm](https://github.com/travitch/whole-program-llvm) and [gllvm](https://github.com/SRI-CSL/gllvm) are solutions to generating linked bitcode files.
+For example, when using gllvm, you should ensure the corresponding compiler is gclang and gclang++, which can be typically set by using `export CC=gclang CXX=gclang++`.

docs/xref/CMakeLists.txt

@@ -0,0 +1,9 @@
+cmake_minimum_required(VERSION 3.6)
+project(xref)
+
+set(CMAKE_EXPORT_COMPILE_COMMANDS 1)
+# set(CMAKE_EXE_LINKER_FLAGS "-flto -fuse-ld=lld -Wl,-save-temps")
+
+add_executable(xref.out 
+    main.c
+    testnum.c)

docs/xref/main.c

@@ -0,0 +1,13 @@
+#include "testnum.h"
+
+extern int MYVAL;
+
+// int getLargest(int N1, int N2, int N3);
+
+int main(void) {
+    int N1 = 1;
+    int N2 = MYVAL;
+    int N3 = 5;
+    int Res = getLargest(N1, N2, N3);
+    return Res;
+}

docs/xref/testnum.c

@@ -0,0 +1,20 @@
+#include "testnum.h"
+
+int MYVAL = 444;
+
+/// \doc a function to get the largest value of the three
+int getLargest(int N1, int N2, int N3) {
+    int Res;
+    if (N1 >= N2) {
+        if (N1 >= N3)
+            Res = N1;
+        else
+            Res = N3;
+    } else {
+        if (N2 >= N3)
+            Res = N2;
+        else
+            Res = N3;
+    }
+    return Res;
+}

docs/xref/testnum.h

@@ -0,0 +1 @@
+int getLargest(int N1, int N2, int N3);

setup/gllvm.sh

@@ -3,4 +3,9 @@
 
 set -e
 go get github.com/SRI-CSL/gllvm/cmd/...
+which gclang
+which gclang++
+which gflang
+which get-bc
+which gsanity-check
 set +e

snippets/llvmcg.py

@@ -1,15 +1,14 @@
 #!/usr/bin/env python3
 
-from __future__ import print_function
 import os
-import sys
-import subprocess
+import platform
 import shutil
+import subprocess
+import sys
 import tempfile
-import platform
 
 if len(sys.argv) < 2:
-    print("usage: {} source.ll/source.bc".format(sys.argv[1]))
+    print(f"usage: {sys.argv[1]} source.ll/source.bc")
     sys.exit(1)
 
 ir_file = os.path.abspath(sys.argv[1])
@@ -29,17 +28,15 @@
 
 opt_plugin_args = ""
 
-opt_str = "opt {} {} -dot-callgraph {} -disable-output".format(
-    opt_plugin_args, more_args, temp_file
-)
+opt_str = f"opt {opt_plugin_args} {more_args} -dot-callgraph {temp_file} -disable-output"
 print(opt_str)
 p1 = subprocess.call(opt_str.split())
 
 dot_fname = "callgraph.dot"
 out_pdf = os.path.splitext(temp_file)[0] + ".pdf"
-dot_str = "dot -Tpdf {} -o {}".format(dot_fname, out_pdf)
+dot_str = f"dot -Tpdf {dot_fname} -o {out_pdf}"
 print(dot_str)
 subprocess.call(dot_str.split())
 
 open_cmd = "open" if platform.system() == "Darwin" else "xdg-open"
-os.system("{} {} &".format(open_cmd, out_pdf))
+os.system(f"{open_cmd} {out_pdf} &")

snippets/pyproject.toml

@@ -0,0 +1,137 @@
+[project]
+version = "1.0"
+name = "awesome-llvm"
+dependencies = ["graphviz>=0.20"]
+
+[project.optional-dependencies]
+test = ["pytest>=6.2.5"]
+######################### pyright ################################
+# as language server, https://github.com/microsoft/pyright/blob/main/docs/settings.md
+[tool.pyright]
+include = ["."]
+exclude = ["**/__pycache__"]
+pythonVersion = "3.10"
+pythonPlatform = "Linux"
+# basic checking (ruff does not type check)
+typeCheckingMode = "basic"
+
+reportMissingImports = true
+reportMissingTypeStubs = false
+reportUnusedImport = false
+reportUndefinedVariable = false
+
+# https://github.com/microsoft/pyright/discussions/3929
+[tool.python.analysis]
+# diagnosticMode = "workspace"
+diagnosticMode = "off"
+diagnosticSeverityOverrides = "none"
+autoImportCompletions = true
+useLibraryCodeForTypes = false
+
+
+######################### ruff ################################
+# as diagnostic tool and formatter https://beta.ruff.rs/docs/rules/
+[tool.ruff]
+select = [
+    # pycodestyle
+    "E",
+    "EXE",
+    # pyflakes
+    "F",
+    "W",
+    "Q",
+    "UP",
+    "I",
+    "N",
+    "COM812",
+]
+ignore = ["F403", "F405"]
+# ignore = ["E501","E226","E302","E71", "E203","F403","F405"]
+
+# Allow autofix for all enabled rules (when `--fix`) is provided.
+fixable = [
+    "A",
+    "B",
+    "C",
+    "D",
+    "E",
+    "F",
+    "G",
+    "I",
+    "N",
+    "Q",
+    "S",
+    "T",
+    "W",
+    "ANN",
+    "ARG",
+    "BLE",
+    "COM",
+    "DJ",
+    "DTZ",
+    "EM",
+    "ERA",
+    "EXE",
+    "FBT",
+    "ICN",
+    "INP",
+    "ISC",
+    "NPY",
+    "PD",
+    "PGH",
+    "PIE",
+    "PL",
+    "PT",
+    "PTH",
+    "PYI",
+    "RET",
+    "RSE",
+    "RUF",
+    "SIM",
+    "SLF",
+    "TCH",
+    "TID",
+    "TRY",
+    "UP",
+    "YTT",
+]
+unfixable = ["F401", "F841"]
+
+# Exclude a variety of commonly ignored directories.
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".hg",
+    ".nox",
+    ".pants.d",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "venv",
+]
+per-file-ignores = {}
+
+line-length = 120
+
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.mccabe]
+max-complexity = 30
+
+# currently unused
+[tool.pylsp-mypy]
+enabled = true
+live_mode = true
+strict = false
+dmypy = true