Skip to content

Commit d9f645b

Browse files
committed
Add docs for new standalone query cmake project generator
1 parent d34d47d commit d9f645b

File tree

2 files changed

+70
-0
lines changed

2 files changed

+70
-0
lines changed

docs/ForDevelopers/Debugging.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@ For the following instructions, we assume that LingoDB was built in Release mode
1919
* If yes: debug with this backend.
2020
* If not: you should use the [LLVM Debug Backend](#llvm-debug-backend)
2121

22+
## Guide: Quick iteration through standalone CMake projects
23+
As discussed [here](StandaloneQuery.md), LingoDB can compile SQL queries to C++ queries and create standalone CMake projects that allow for quick iterations, without adapting the compilation pipeline at all.
24+
2225
## Components for Debugging and Profiling
2326
### Location Tracking in MLIR
2427
In MLIR, every operation is associated with a *Location*, that must be provided during operation creation.
Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: Generating a standalone CMake project for a specific query
3+
---
4+
Sometimes, you want to quickly experiment with speeding up a particular SQL query without diving into LingoDB’s full compiler pipeline. For this, LingoDB provides a script that generates a standalone, minimal CMake project for just that query. The query is compiled ahead-of-time into C++ and linked against LingoDB’s runtime.
5+
6+
7+
### 1. Generate CMake project for your query
8+
9+
**Command:**
10+
```bash
11+
bash tools/standalone-query/create.sh \
12+
my_query.sql \
13+
my/db/dir \
14+
build-dir \
15+
/absolute/path/to/experiments/my-query \
16+
speedup-query
17+
```
18+
19+
- **my_query.sql**: path to your `.sql` file.
20+
- **my/db/dir**: path to an existing LingoDB database directory.
21+
- **build-dir**: directory containing the `compile-to-cpp` executable, e.g., `build/lingodb-debug`
22+
- **/absolute/path/to/experiments/my-query**: new worktree directory (must *not* exist).
23+
- **speedup-query**: name for the experimental branch (must *not* exist).
24+
25+
This script performs the following steps:
26+
1. generate sparse git worktree (to make sure that you can work with git/commit your changes)
27+
2. prepares the project (e.g., prepares custom CMakeLists.txt)
28+
3. compiles the SQL query to a C++ file that is placed in the new CMake project
29+
4. Finally, it prints some helpful information, for example:
30+
```bash
31+
32+
== Standalone query worktree created ==
33+
Branch: speedup-query
34+
Worktree directory: /home/alice/projects/experiments/my-query
35+
36+
== Commands to build the standalone query executable ==
37+
cd /home/alice/projects/experiments/my-query
38+
mkdir build && cd build
39+
cmake -DCMAKE_BUILD_TYPE=Release ..
40+
cmake --build . -j$(nproc)
41+
42+
== Commands to run the standalone query executable ==
43+
./main /home/alice/projects/lingodb/db-dir
44+
45+
== Commands to clean up the worktree ==
46+
cd /home/alice/projects/lingodb
47+
git worktree remove /home/alice/projects/experiments/my-query --force
48+
(optional) git branch -D speedup-query
49+
```
50+
51+
---
52+
53+
### 2. Use the generated project
54+
55+
- It’s a **normal CMake/C++** project—use your debugger, profiler, or editor of choice.
56+
- Feel free to edit **any** sources:
57+
- Tweak the generated `query.cpp`.
58+
- Modify runtime code.
59+
- Because it lives in a separate Git worktree & branch, your experiments won’t affect the main codebase.
60+
61+
---
62+
63+
### 3. Commit selected changes
64+
65+
- Any fixes or optimizations you make to runtime components will live on your **experimental branch**.
66+
- When ready, switch back to your main worktree and either cherry-pick or merge your changes
67+

0 commit comments

Comments
 (0)