Ox: Implementation with Langium & LLVM

This repository contains a Langium and LLVM based implementation of the Ox language, a subset of the Lox language.

The main purpose of the Ox language is to show how Langium and LLVM can be used together to get an executable and debuggable language. In the screenshot below, you can see the VSCode window where a factorial program written in Ox language is running in debug mode.

The implementation includes:

• Ox grammar and LSP services generated by Langium
• LLVM IR and Debug Information (DI) generator
  • depends on llvm-bindings, a binding library for calling the LLVM API in TypeScript
• CLI for the LLVM IR code generation

Code samples in Ox are located in the ./examples folder.

How to build

1. Install the library llvm-bindings
   • to generate LLVM IR and DI
2. Compile the Ox language and other sources

npm i
npm run langium:generate
npm run build

3. Install the CodeLLDB extension
   • to debug Ox in VSCode and not using the debugger CLI

How to execute and debug Ox

In the IDE

1. Run the Ox IDE using the VSCode Run Extension launch config
2. Open the ./examples folder. It has .ox files and its own VSCode launch config
3. Open any .ox file in the editor, set a breakpoint, and use the Debug launch config

• make sure that the VSCode Debug: Allow Breakpoints Everywhere flag is set to true

Using the CLI

1. Generate factorial.ll with LLVM IR and DI for ./examples/factorial.ox in ./examples/dbg

node ./bin/cli.js generate ./examples/basic.ox -d ./examples/dbg

2. Compile factorial.ll into an executable ./examples/dbg/out in debug mode

clang -g ./examples/dbg/factorial.ll -o ./examples/dbg/out

• To execute

  ./examples/dbg/out

3. To debug using the LLDB debugger CLI

lldb ./examples/dbg/out
(lldb) b 3     # sets the breakpoint on line 3
(lldb) r       # runs the program
(lldb) print n # prints the value of the variable n
(lldb) next    # go to the next line 4
(lldb) q       # quit the debugger