|
| 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