https://github.com/typefox/langium-llvm
https://github.com/typefox/langium-llvm
Last synced: 10 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/typefox/langium-llvm
- Owner: TypeFox
- Created: 2024-02-20T15:08:19.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-03-18T13:15:54.000Z (about 2 years ago)
- Last Synced: 2025-06-08T00:11:25.440Z (10 months ago)
- Language: TypeScript
- Size: 76.2 KB
- Stars: 6
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Ox: Implementation with Langium & LLVM
This repository contains a Langium and LLVM based implementation of the Ox language, a subset of the [Lox language](https://craftinginterpreters.com/the-lox-language.html).
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](https://www.npmjs.com/package/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](https://github.com/ApsarasX/llvm-bindings?tab=readme-ov-file#install)
- to generate LLVM IR and DI
2. Compile the Ox language and other sources
```bash
npm i
npm run langium:generate
npm run build
```
3. Install the [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb) 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`
```bash
node ./bin/cli.js generate ./examples/basic.ox -d ./examples/dbg
```
2. Compile `factorial.ll` into an executable `./examples/dbg/out` in debug mode
```bash
clang -g ./examples/dbg/factorial.ll -o ./examples/dbg/out
```
- To execute
```bash
./examples/dbg/out
```
3. To debug using the LLDB debugger CLI
```bash
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
```