Getting Started with LLVM (WIP draft)

llvm.getting.started.md

Getting Started with LLVM (WIP)

The guide will hopefully help you quickly graps the basics of LLVM. Links to useful self-learning article, video and tools will be listed below.

Basic overview

• http://www.aosabook.org/en/llvm.html
• What goes behind LLVM Compiler Infrastructure : Tanmay Bakshi https://youtu.be/IR_L1xf4PrU
• https://proglangdesign.net/wiki/llvm

Learning - LLVM IR generation

• https://mukulrathi.co.uk/create-your-own-programming-language/llvm-ir-cpp-api-tutorial/
• https://mukulrathi.co.uk/create-your-own-programming-language/concurrency-runtime-language-tutorial/
• LLVM IR Tutorial - Phis, GEPs and other things, oh my! - LLVM 2019 https://youtu.be/m8G_S5LwlTo
• https://mapping-high-level-constructs-to-llvm-ir.readthedocs.io/en/latest/README.html
• LLVM LIT Testing framework : https://medium.com/@mshockwave/using-llvm-lit-out-of-tree-5cddada85a78
• IR code debugging : https://github.com/vaivaswatha/debugir
• Official tutorial : https://llvm.org/docs/tutorial/MyFirstLanguageFrontend/index.html
  • https://github.com/llvm/llvm-project/tree/master/llvm/examples

Example code

• Minimum code to generate LLVM IR : https://github.com/ruvi-d/llvm_codegen
• LLVM IR and runtime linking test app: https://github.com/ruvi-d/LLVM-runtime-test
• C-Rust-Interop : https://github.com/ruvi-d/C-Rust-Interop

Learning - Adding debugging support to a language

• 2014 LLVM Developers’ Meeting: “Debug Info Tutorial ” - https://youtu.be/_wqX9H2A66M
• https://llvm.org/docs/tutorial/MyFirstLanguageFrontend/LangImpl09.html

Tools

• https://godbolt.org/
• https://llvm.godbolt.org/

Official references

• Repo : https://github.com/llvm/llvm-project
• Docs : https://llvm.org/docs/
  • Commandline tool reference : https://llvm.org/docs/CommandGuide/
  • IR Syntax reference : https://llvm.org/docs/LangRef.html

Other references

C/C++

• Modern C++ reference : https://www.amazon.com/C-Crash-Course-Josh-Lospinoso/dp/1593278888/
• C++ Best practices : https://leanpub.com/cppbestpractices
• Advanced C and C++ Compiling : https://www.amazon.com/Advanced-C-Compiling-Milan-Stevanovic-ebook/dp/B01HXFLQH0
• Modern C++: Snippets and Examples : https://alandefreitas.github.io/moderncpp/
• Modern Linux C++ debugging tools - under the covers (CppCon 2019) : https://youtu.be/WoRmXjVxuFQ
• Professional CMake, A Practical Guide https://crascit.com/professional-cmake/
• Useful tools for checking and fixing C/C++ code : https://github.com/qarmin/Instrukcje-i-Tutoriale/blob/master/AnalizatoryCC%2B%2BENG.md#useful-tools-for-checking-and-fixing-cc-code-and-others-languages-too

LLVM

• Packt Getting Started With LLVM Core Libraries : https://www.amazon.com/Getting-Started-LLVM-Core-Libraries/dp/1782166920
• https://github.com/HongxuChen/awesome-llvm

Misc compiler

• https://github.com/MattPD/cpplinks/blob/master/compilers.md
  • https://gist.github.com/MattPD/00573ee14bf85ccac6bed3c0678ddbef#llvm
• https://www.reddit.com/r/ProgrammingLanguages/comments/hsj2o9/i_have_a_year_to_finish_my_undergrad_thesis_on_pl/fyef3ze/
• https://www.reddit.com/r/programming/comments/kjjijf/a_complete_guide_to_llvm_for_programming_language/

llvm.on.windows.md

LLVM on Windows

• Pre-built binaries at https://github.com/llvm/llvm-project/releases for Windows only contain the clang and a few other binaries. Pre-built core libs are not available for Windows 1 2
• As such we will have to build are own LLVM libs for nBAllerina
• Using MSVC it is not possible to build dynamic libs of LLVM. Only Static libs are supported. LLVM anyway only recommends synamic libs for development purposes only.

Background info on building on Windows

• Make sure that you use the correct toolset (e.g. x86 vs x64)
  • https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-160#developer_command_prompt_shortcuts
• You can directly compile CPP files using cl command (akin to running gcc or clang)
  • https://docs.microsoft.com/en-us/cpp/build/walkthrough-compiling-a-native-cpp-program-on-the-command-line?view=msvc-160
  • https://docs.microsoft.com/en-us/cpp/build/reference/compiler-command-line-syntax?view=msvc-160
  • e.g. cl /W4 /EHsc file1.cpp file2.cpp file3.cpp /link /out:program1.exe
• But Using CMake to generate .vcxproj targets and building them with msbuild is the preferred, more portable option
  • CMake : https://docs.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio?view=msvc-160
  • MSBuild

    • https://docs.microsoft.com/en-us/cpp/build/msbuild-visual-cpp?view=msvc-160

    • https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild?view=vs-2019

      cmake ..\
      msbuild ALL_BUILD.vcxproj /p:configuration=debug
      

• /MD, /MT, /LD : https://docs.microsoft.com/en-us/cpp/build/reference/md-mt-ld-use-run-time-library?view=msvc-160

Building LLVM on Windows

Prerequisites

• Build Tools for Visual Studio 2019
  • Select C++ build tools with the following optional ones
    • C++ CMake tools for Windows
    • C++ ATL for latest v142 build tools (x86 & x64)
    • C++ Clang comiler & Clang-cl build tools
• Python3 (latest)

Building LLVM

• Get source code from : https://github.com/llvm/llvm-project/releases/download/llvmorg-11.0.1/llvm-11.0.1.src.tar.xz
  • Cloning full source code is optional
• Go to LLVM directory
  • Create a build and install directory
• Change directory to build and execute the following in x64 Native Tools Command Prompt for VS 2019

$ cmake -DCMAKE_BUILD_TYPE="Release" -Thost=x64 -G "Visual Studio 16 2019" -A x64 -DLLVM_USE_CRT_RELEASE=MT -DCMAKE_INSTALL_PREFIX="<path>" ../ 
$ msbuild INSTALL.vcxproj /p:configuration=release

Setting up a test app to generate LLVM IR

• Example app : https://github.com/ruvi-d/llvm_codegen/tree/windows

Bonus

Open Powershell with x64 dev tools

• Create a system variable called dev64 with the value "&{Import-Module """C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\Common7\Tools\Microsoft.VisualStudio.DevShell.dll"""; Enter-VsDevShell ff0ceaa0 -DevCmdArguments '-arch=x64]'}"
  • Change the ff0ceaa0 value to match your environment
• Create a shortcut with the following target : C:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe -noe -c %dev64%

Using Clang on windows

https://docs.microsoft.com/en-us/cpp/build/clang-support-cmake?view=msvc-160

• Install
  • C++ Clang Compiler for windows
  • C++ Clang-cl for v142 buil tools (x64/x86)
• To use the Clang version that is part of the Visual Studio 2019 build tools with CMake
  • cmake -G "Visual Studio 16 2019" -A x64 -T ClangCL ..\
  • The -T ClangCL target is the key point
• To use a custom installation of Clang/LLVM with CMake
  • USe this fork to create the correct targets: https://github.com/ruvi-d/llvm-utils
  • cmake -G "Visual Studio 16 2019" -A x64 -T LLVM-vs142 ..\