### Build and Install Brotli with CMake

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/brotli/README.md

Use these CMake commands to build and install Brotli. Ensure you specify the build type and installation prefix.

```bash
mkdir out && cd out
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=./installed ..
cmake --build . --config Release --target install
```

--------------------------------

### Define Installation Directories

Source: https://github.com/ladybugdb/ladybug/blob/main/CMakeLists.txt

Sets installation directories for libraries, executables, headers, and CMake files using CACHE PATH variables.

```cmake
set(INSTALL_LIB_DIR
        lib
        CACHE PATH "Installation directory for libraries")
set(INSTALL_BIN_DIR
        bin
        CACHE PATH "Installation directory for executables")
set(INSTALL_INCLUDE_DIR
        include
        CACHE PATH "Installation directory for header files")
set(INSTALL_CMAKE_DIR
        ${DEF_INSTALL_CMAKE_DIR}
        CACHE PATH "Installation directory for CMake files")
```

--------------------------------

### Install Man Page

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/brotli/CMakeLists.txt

Installs the man page file if BROTLI_BUILD_TOOLS is enabled. This makes the command-line tool documentation available.

```cmake
if (BROTLI_BUILD_TOOLS)
  install(FILES "docs/brotli.1"
    DESTINATION "${CMAKE_INSTALL_FULL_MANDIR}/man1")
endif()
```

--------------------------------

### Start Local HTTP Endpoint

Source: https://github.com/ladybugdb/ladybug/blob/main/tools/dev/README.md

Run this command from the repository root to start a local HTTP endpoint for serving files. It binds to a specific address and port, and serves files from the current directory.

```bash
python3 tools/dev/range_file_server.py --bind 127.0.0.1 --port 8766 --root "$PWD"
```

--------------------------------

### Install pkg-config Files

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/brotli/CMakeLists.txt

Installs generated pkg-config files to the appropriate directory if BROTLI_BUNDLED_MODE is not enabled. This ensures that other projects can find the installed library using pkg-config.

```cmake
transform_pc_file("scripts/libbrotlicommon.pc.in" "${CMAKE_CURRENT_BINARY_DIR}/libbrotlicommon.pc" "${BROTLI_VERSION}")

transform_pc_file("scripts/libbrotlidec.pc.in" "${CMAKE_CURRENT_BINARY_DIR}/libbrotlidec.pc" "${BROTLI_VERSION}")

transform_pc_file("scripts/libbrotlienc.pc.in" "${CMAKE_CURRENT_BINARY_DIR}/libbrotlienc.pc" "${BROTLI_VERSION}")

if(NOT BROTLI_BUNDLED_MODE)
  install(FILES "${CMAKE_CURRENT_BINARY_DIR}/libbrotlicommon.pc"
    DESTINATION "${CMAKE_INSTALL_LIBDIR}/pkgconfig")
  install(FILES "${CMAKE_CURRENT_BINARY_DIR}/libbrotlidec.pc"
    DESTINATION "${CMAKE_INSTALL_LIBDIR}/pkgconfig")
  install(FILES "${CMAKE_CURRENT_BINARY_DIR}/libbrotlienc.pc"
    DESTINATION "${CMAKE_INSTALL_LIBDIR}/pkgconfig")
endif()  # BROTLI_BUNDLED_MODE
```

--------------------------------

### Configure C Example Executable with Ladybug Library

Source: https://github.com/ladybugdb/ladybug/blob/main/examples/c/CMakeLists.txt

Use these CMake commands to define an executable, link it to the Ladybug shared library, and set up include directories for your C example.

```cmake
add_executable(example_c main.c)
target_link_libraries(example_c lbug_shared)
target_include_directories(example_c PRIVATE ${PROJECT_SOURCE_DIR}/src/include/c_api)
```

--------------------------------

### Install Python Package with uv

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/python.md

Recommended method for installing the Python package in a virtual environment using uv. Ensure you are in the `tools/python_api` directory.

```bash
cd tools/python_api
uv venv
source .venv/bin/activate
uv pip install -e .
```

--------------------------------

### Include Install Directories

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/brotli/CMakeLists.txt

Includes the GNUInstallDirs module to define standard installation directory variables.

```cmake
include(GNUInstallDirs)
```

--------------------------------

### Build and Install Ladybug from Source

Source: https://github.com/ladybugdb/ladybug/blob/main/scripts/pip-package/README.md

Execute these commands to build and install Ladybug from source. Ensure you have the required toolchain including Cmake, Python 3, and a C++20 compatible compiler.

```bash
chmod +x package_tar.py
./package_tar.py
pip install lbug.tar.gz
```

--------------------------------

### Install Pybind11 Headers and Configuration Files

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/pybind11/CMakeLists.txt

Installs Pybind11 headers, CMake configuration files, and utility scripts. It handles different CMake versions for package configuration file generation.

```cmake
if(PYBIND11_INSTALL)
  install(DIRECTORY ${pybind11_INCLUDE_DIR}/pybind11 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
  set(PYBIND11_CMAKECONFIG_INSTALL_DIR
      "${CMAKE_INSTALL_DATAROOTDIR}/cmake/${PROJECT_NAME}"
      CACHE STRING "install path for pybind11Config.cmake")

  if(IS_ABSOLUTE "${CMAKE_INSTALL_INCLUDEDIR}")
    set(pybind11_INCLUDEDIR "${CMAKE_INSTALL_FULL_INCLUDEDIR}")
  else()
    set(pybind11_INCLUDEDIR "\${\${PACKAGE_PREFIX_DIR}}/${CMAKE_INSTALL_INCLUDEDIR}")
  endif()

  configure_package_config_file(
    tools/${PROJECT_NAME}Config.cmake.in "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}Config.cmake"
    INSTALL_DESTINATION ${PYBIND11_CMAKECONFIG_INSTALL_DIR})

  if(CMAKE_VERSION VERSION_LESS 3.14)
    # Remove CMAKE_SIZEOF_VOID_P from ConfigVersion.cmake since the library does
    # not depend on architecture specific settings or libraries.
    set(_PYBIND11_CMAKE_SIZEOF_VOID_P ${CMAKE_SIZEOF_VOID_P})
    unset(CMAKE_SIZEOF_VOID_P)

    write_basic_package_version_file(
      ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake
      VERSION ${PROJECT_VERSION}
      COMPATIBILITY AnyNewerVersion)

    set(CMAKE_SIZEOF_VOID_P ${_PYBIND11_CMAKE_SIZEOF_VOID_P})
  else()
    # CMake 3.14+ natively supports header-only libraries
    write_basic_package_version_file(
      ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake
      VERSION ${PROJECT_VERSION}
      COMPATIBILITY AnyNewerVersion ARCH_INDEPENDENT)
  endif()

  install(
    FILES ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}Config.cmake
          ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake
          tools/FindPythonLibsNew.cmake
          tools/pybind11Common.cmake
          tools/pybind11Tools.cmake
          tools/pybind11NewTools.cmake
    DESTINATION ${PYBIND11_CMAKECONFIG_INSTALL_DIR})

  if(NOT PYBIND11_EXPORT_NAME)
    set(PYBIND11_EXPORT_NAME "${PROJECT_NAME}Targets")
  endif()

  install(TARGETS pybind11_headers EXPORT "${PYBIND11_EXPORT_NAME}")

  install(
    EXPORT "${PYBIND11_EXPORT_NAME}"
    NAMESPACE "pybind11::"
    DESTINATION ${PYBIND11_CMAKECONFIG_INSTALL_DIR})

  # pkg-config support
  if(NOT prefix_for_pc_file)
    set(prefix_for_pc_file "${CMAKE_INSTALL_PREFIX}")
  endif()
  join_paths(includedir_for_pc_file "\${\${prefix}}" "${CMAKE_INSTALL_INCLUDEDIR}")
  configure_file("${CMAKE_CURRENT_SOURCE_DIR}/tools/pybind11.pc.in"
                 "${CMAKE_CURRENT_BINARY_DIR}/pybind11.pc" @ONLY)
  install(FILES "${CMAKE_CURRENT_BINARY_DIR}/pybind11.pc"
          DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/pkgconfig/")

  # Uninstall target
  if(PYBIND11_MASTER_PROJECT)
    configure_file("${CMAKE_CURRENT_SOURCE_DIR}/tools/cmake_uninstall.cmake.in"
                   "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake" IMMEDIATE @ONLY)

    add_custom_target(uninstall COMMAND ${CMAKE_COMMAND} -P
                                        ${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake)
  endif()
endif()
```

--------------------------------

### Install Brotli Executable

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/brotli/CMakeLists.txt

Installs the brotli executable to the runtime destination if BROTLI_BUILD_TOOLS is enabled and BROTLI_BUNDLED_MODE is not set.

```cmake
if (BROTLI_BUILD_TOOLS)
    install(
      TARGETS brotli
      RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}"
    )
  endif()
```

--------------------------------

### Install Brotli Libraries

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/brotli/CMakeLists.txt

Installs the core Brotli libraries (archive, library, and runtime) to their respective destinations when BROTLI_BUNDLED_MODE is not set.

```cmake
install(
    TARGETS ${BROTLI_LIBRARIES_CORE}
    ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}"
    LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}"
    RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}"
  )
```

--------------------------------

### Install Executable Target

Source: https://github.com/ladybugdb/ladybug/blob/main/tools/shell/CMakeLists.txt

Installs the 'lbug_shell' target to the appropriate location based on CMake installation rules.

```cmake
install(TARGETS lbug_shell)
```

--------------------------------

### Install Brotli Headers

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/brotli/CMakeLists.txt

Installs the Brotli header directory to the include destination when BROTLI_BUNDLED_MODE is not set.

```cmake
install(
    DIRECTORY ${BROTLI_INCLUDE_DIRS}/brotli
    DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
  )
```

--------------------------------

### Install Python Package with pip (Legacy)

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/python.md

Legacy method for installing the Python package using pip. Ensure you are in the `tools/python_api` directory.

```bash
cd tools/python_api
pip install -e .
```

--------------------------------

### Install Brotli Python Module

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/brotli/README.md

Install the latest release of the Brotli Python module using pip. For the development version, use the provided git repository.

```bash
pip install brotli
```

```bash
pip install --upgrade git+https://github.com/google/brotli
```

--------------------------------

### Configure Google Test Fetching in CMake

Source: https://github.com/ladybugdb/ladybug/blob/main/test/gtest/CMakeLists.txt

Configures CMake to either find an existing system installation of Google Test or fetch it from GitHub using FetchContent. Set PREFER_SYSTEM_DEPS to TRUE to prioritize system GTest.

```cmake
set(DOWNLOAD_GTEST TRUE)
if(${PREFER_SYSTEM_DEPS})
    find_package(GTest QUIET)
    if(GTest_FOUND)
        message(STATUS "Using system GTest")
        set(DOWNLOAD_GTEST FALSE)
    endif()
endif()
if (${DOWNLOAD_GTEST})
    message(STATUS "Fetching GTest from GitHub...")
    include(FetchContent)
    FetchContent_Declare(
        googletest
        GIT_REPOSITORY https://github.com/google/googletest.git
        GIT_TAG        v1.17.0
        GIT_SHALLOW    TRUE
    )
    if(WIN32)
        set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
    endif()
    FetchContent_MakeAvailable(googletest)
endif()
```

--------------------------------

### Setup Coverage Target

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/brotli/CMakeLists.txt

Configures a target for code coverage if ENABLE_COVERAGE is set to 'yes'. This is typically used for testing and analysis purposes.

```cmake
if (ENABLE_COVERAGE STREQUAL "yes")
  setup_target_for_coverage(coverage test coverage)
endif()
```

--------------------------------

### Start Local S3-Shaped Endpoint

Source: https://github.com/ladybugdb/ladybug/blob/main/tools/dev/README.md

Start a local S3-shaped endpoint using HTTPS. This server supports byte-range requests and uses a self-signed certificate. The `--strip-prefix` flag remaps URL paths.

```bash
python3 tools/dev/range_file_server.py \
  --bind 127.0.0.1 \
  --port 9443 \
  --root "$PWD" \
  --strip-prefix icebug \
  --cert /private/tmp/lbug_s3_cert.pem \
  --key /private/tmp/lbug_s3_key.pem
```

--------------------------------

### Set Relative Install Directory for Python Includes

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/pybind11/CMakeLists.txt

Configures the installation directory for Python include files based on whether Python include directories are defined and if relative paths are used.

```cmake
if(USE_PYTHON_INCLUDE_DIR AND DEFINED Python_INCLUDE_DIRS)
  file(RELATIVE_PATH CMAKE_INSTALL_INCLUDEDIR ${CMAKE_INSTALL_PREFIX} ${Python_INCLUDE_DIRS})
elseif(USE_PYTHON_INCLUDE_DIR AND DEFINED PYTHON_INCLUDE_DIR)
  file(RELATIVE_PATH CMAKE_INSTALL_INCLUDEDIR ${CMAKE_INSTALL_PREFIX} ${PYTHON_INCLUDE_DIRS})
endif()
```

--------------------------------

### Zstd Update Workflow

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/ports/zstd/README.md

Commands to fetch, extract, build (apply patches), and install a new version of zstd within the third_party directory. The patch script is idempotent.

```bash
cd third_party
./pkg zstd fetch     # Download new version (update VERSION in Makefile first)
./pkg zstd extract   # Extract source
./pkg zstd build     # Apply patches (rename .c, add namespace, remove asm)
./pkg zstd install   # Sync files to third_party/zstd/
```

--------------------------------

### Build All Extensions

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/extensions.md

Build all available extensions for the project. This command compiles all extensions.

```bash
# Build all extensions
make extension-build
```

--------------------------------

### Build and Run All Extension Tests

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/extensions.md

Build all extensions and then run all associated tests. This ensures the integrity of all extensions.

```bash
# Build and run all extension tests
make extension-test-build
make extension-test
```

--------------------------------

### Configure Build Options

Source: https://github.com/ladybugdb/ladybug/blob/main/CMakeLists.txt

Sets up various build options for features like grammar regeneration, benchmarks, extensions, and language APIs.

```cmake
option(AUTO_UPDATE_GRAMMAR "Automatically regenerate C++ grammar files on change." TRUE)
option(BUILD_BENCHMARK "Build benchmarks." FALSE)
option(BUILD_WAL_DUMP "Build WAL dump tool." FALSE)
option(BUILD_EXTENSIONS "Semicolon-separated list of extensions to build." "")
option(BUILD_EXAMPLES "Build examples." FALSE)
option(BUILD_JAVA "Build Java API." FALSE)
option(BUILD_NODEJS "Build NodeJS API." FALSE)
option(BUILD_PYTHON "Build Python API." FALSE)
option(BUILD_SHELL "Build Interactive Shell" TRUE)
option(BUILD_SINGLE_FILE_HEADER "Build single file header. Requires Python >= 3.9." TRUE)
option(BUILD_LBUG "Build Lbug." TRUE)
option(BUILD_SHARED_LBUG "Build the shared liblbug library." TRUE)
option(BUILD_STATIC_LBUG "Build the bundled static liblbug archive." TRUE)
option(LBUG_API_USE_PRECOMPILED_LIB "Link language bindings against a precompiled static liblbug archive." FALSE)
set(LBUG_API_PRECOMPILED_LIB_PATH "" CACHE FILEPATH "Path to the precompiled static liblbug archive used by language bindings.")
option(LBUG_NODEJS_USE_PRECOMPILED_LIB "Deprecated alias for LBUG_API_USE_PRECOMPILED_LIB." FALSE)
set(LBUG_NODEJS_PRECOMPILED_LIB_PATH "" CACHE FILEPATH "Deprecated alias for LBUG_API_PRECOMPILED_LIB_PATH.")
option(ENABLE_BACKTRACES "Enable backtrace printing for fatal signals and termination" FALSE)
option(PREFER_SYSTEM_DEPS "Only download certain deps if not found on the system" TRUE)
```

--------------------------------

### Build Ladybug Agent (Make)

Source: https://github.com/ladybugdb/ladybug/blob/main/AGENTS.md

Use these make commands for various build configurations. Prefer Ninja over make when possible.

```bash
make release
# Release build (fastest, for production/testing)
```

```bash
make debug
# Debug build (with debug symbols)
```

```bash
make relwithdebinfo
# RelWithDebInfo (recommended for testing with stack traces)
```

```bash
make all
# Full build with all components
```

```bash
make python        # Python API
make java          # Java API
make nodejs        # Node.js API
make shell         # Shell CLI
make benchmark     # Benchmarks
make example       # Examples
# Build specific components
```

```bash
make extension-build          # Build all extensions
make extension-debug          # Debug build with extensions
make extension-release       # Release build with extensions
# Build with extensions
```

--------------------------------

### Add Executable and Link Libraries

Source: https://github.com/ladybugdb/ladybug/blob/main/examples/cpp/CMakeLists.txt

Defines an executable target named 'example_cpp' using 'main.cpp', links it against the 'lbug_shared' library, and sets private include directories. It also adds a dependency on 'single_file_header'.

```cmake
add_executable(example_cpp main.cpp)
target_link_libraries(example_cpp lbug_shared)
target_include_directories(example_cpp PRIVATE ${CMAKE_BINARY_DIR}/src)
add_dependencies(example_cpp single_file_header)
```

--------------------------------

### Set Snappy Include Directories

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/snappy/CMakeLists.txt

Configures public build interface include directories for the 'snappy' target, pointing to the current source directory.

```cmake
target_include_directories(snappy PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>)
```

--------------------------------

### C++ Include Order and Imports Pattern

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/cpp_style.md

Follow this include order: C system headers, C++ system headers, third-party libraries, project headers from 'src/', and other local headers. Use full paths from 'src/' for project headers.

```cpp
// C++ system headers first
#include <format>
#include <memory>
#include <string>

// Third-party libraries
#include "spdlog/spdlog.h"

// Project headers (use full path from src/)
#include "main/client_context.h"
#include "storage/storage_manager.h"
```

--------------------------------

### Build Tools Option

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/brotli/CMakeLists.txt

Configures an option to control whether CLI tools are built and installed. Defaults to OFF.

```cmake
set(BROTLI_BUILD_TOOLS OFF CACHE BOOL "Build/install CLI tools")
```

--------------------------------

### Query Execution with Synchronization

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/incidents/2026-02-16-connection-close-sigsegv.md

Wraps the query execution process with calls to `registerQueryStart()` at the beginning and uses an RAII guard to ensure `registerQueryEnd()` is called upon completion or exception. This guarantees that the query count is accurately maintained.

```cpp
int QueryProcessor::execute(Task* task, ExecutionContext* context) {
  context->clientContext->registerQueryStart();
  QueryEndGuard guard(context->clientContext);
  // ... rest of the execution logic ...
  return scheduleTaskAndWaitOrError(task, context);
}
```

--------------------------------

### Add gtest Subdirectory

Source: https://github.com/ladybugdb/ladybug/blob/main/test/CMakeLists.txt

Includes the Google Test framework as a subdirectory for testing. Ensure gtest libraries are not installed system-wide.

```cmake
add_subdirectory(gtest EXCLUDE_FROM_ALL)
```

--------------------------------

### Release Build with Extensions

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/extensions.md

Perform a release build that includes extensions. This is optimized for production use.

```bash
# Release build with extensions
make extension-release
```

--------------------------------

### Morsel Assignment in Arrow Tables

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/morsel_parallelism.md

Delegates morsel assignment to ArrowNodeTableScanSharedState. This function is called to get the next morsel for scanning.

```cpp
if (const auto arrowTable = dynamic_cast<ArrowNodeTable*>(this->table)) {
        const auto tableSharedState = arrowTable->getTableScanSharedState();
        if (tableSharedState->getNextMorsel(static_cast<ColumnarNodeTableScanState*>(&scanState))) {
            scanState.source = TableScanSource::COMMITTED;
            progressSharedState.numMorselsScanned++;
        }
   }
```

--------------------------------

### Build with Statically Linked Extensions

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/extensions.md

Build the project with specified extensions statically linked. This embeds extensions directly into the binary.

```bash
# Build with statically linked extensions
EXTENSION_LIST=vector,json EXTENSION_STATIC_LINK_LIST=vector,json make extension-test-static-build
make extension-static-link-test
```

--------------------------------

### Set Minimum CMake Version

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/brotli/CMakeLists.txt

Specifies the minimum required CMake version for the project. Ensure your CMake installation meets this requirement.

```cmake
cmake_minimum_required(VERSION 3.15)
```

--------------------------------

### Test HTTP Init File with Shell

Source: https://github.com/ladybugdb/ladybug/blob/main/tools/dev/README.md

Pipe a Cypher command to the `lbug` shell, using an HTTP URL to access an init file. This tests VFS reads over HTTP, which requires byte-range support.

```bash
printf 'match (a)-[b]->(c) return *;\n:quit\n' \
  | ./build/release/tools/shell/lbug \
      -i http://127.0.0.1:8766/dataset/demo-db/icebug-disk/schema.cypher
```

--------------------------------

### Add LadybugDB Subdirectory with CMake

Source: https://github.com/ladybugdb/ladybug/blob/main/examples/README.md

To integrate LadybugDB into your project using CLion, add this line to your CMakeLists.txt file. This command includes the examples subdirectory.

```cmake
add_subdirectory(examples/cpp)
```

--------------------------------

### Run Node.js Addon Verification Tests

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/incidents/2026-02-16-connection-close-sigsegv.md

Build and run the Node.js addon tests using make. This includes a suite for resilience, covering scenarios like closing connections during or after use.

```bash
make nodejstest
```

--------------------------------

### Build Ladybug Agent (CMake/PowerShell)

Source: https://github.com/ladybugdb/ladybug/blob/main/AGENTS.md

Use these CMake commands with Ninja for building on Windows without make. Ensure CMake and Ninja are in your PATH.

```powershell
cmake -B build/relwithdebinfo -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo .
cmake --build build/relwithdebinfo --config RelWithDebInfo
# RelWithDebInfo (generates compile_commands.json for clangd/MCP)
```

```powershell
cmake -B build/release -G Ninja -DCMAKE_BUILD_TYPE=Release .
cmake --build build/release --config Release
# Release
```

```powershell
cmake -B build/debug -G Ninja -DCMAKE_BUILD_TYPE=Debug .
cmake --build build/debug --config Debug
# Debug
```

--------------------------------

### C++ Unit Test Structure

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/testing.md

Defines the basic structure for C++ unit tests using Google Test. Includes setup for test fixtures and a sample test case.

```cpp
#include "test_helper/test_helper.h"
#include <gtest/gtest.h>

namespace lbug {
namespace testing {

class MyTest : public DBTest {
    void SetUp() override {
        BaseGraphTest::SetUp();
        // Test setup
    }
};

TEST_F(MyTest, TestCaseName) {
    // Test implementation
}

} // namespace testing
} // namespace lbug
```

--------------------------------

### Configure System Configuration Header

Source: https://github.com/ladybugdb/ladybug/blob/main/CMakeLists.txt

Generates the system configuration header file from a template, applying specific options.

```cmake
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/cmake/templates/system_config.h.in ${CMAKE_CURRENT_BINARY_DIR}/src/include/common/system_config.h @ONLY)
```

--------------------------------

### Hash Join SIP Optimization Logic in C++

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/semi_mask_in_scan.md

Illustrates the optimization logic in `acc_hash_join_optimizer.cpp` for Semi-side Information Passing (SIP) in hash joins. It prioritizes 'build to probe' SIP and falls back to 'probe to build'.

```cpp
// Try build to probe SIP first
if (tryBuildToProbeHJSIP(op)) {
    // Semi mask is applied on build side
    sipInfo.direction = SIPDirection::BUILD_TO_PROBE;
}
// If that fails, try probe to build
tryProbeToBuildHJSIP(op);
```

--------------------------------

### Morsel Assignment for Native Node Tables

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/morsel_parallelism.md

This snippet shows how threads are assigned the next morsel (node group) in native node table scanning. It uses an atomic counter to ensure each thread gets a unique node group index. Called when a thread exhausts its current node group.

```cpp
if (currentCommittedGroupIdx < numCommittedNodeGroups) {
    nodeScanState.nodeGroupIdx = currentCommittedGroupIdx++;  // Atomic assign
    nodeScanState.source = TableScanSource::COMMITTED;
    return;
}
```

--------------------------------

### Build Python API

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/python.md

Use these make commands to build the Python API. Use `python-debug` for a debug build.

```bash
make python
# Build Python API
```

```bash
make python-debug
# Debug build
```

--------------------------------

### Define LadybugDB Planner Library

Source: https://github.com/ladybugdb/ladybug/blob/main/src/planner/operator/simple/CMakeLists.txt

Defines a CMake library target named 'lbug_planner_simple' and includes source files. Use this to build the planner library.

```cmake
add_library(lbug_planner_simple
        OBJECT
        logical_simple.cpp)
```

--------------------------------

### Build Specific Extensions

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/extensions.md

Build only a specified list of extensions. Use the EXTENSION_LIST variable to define which extensions to build.

```bash
# Build specific extensions
EXTENSION_LIST=vector,json make extension-build
```

--------------------------------

### Build and Test Specific Extension

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/extensions.md

Build and test a specific extension. This is useful for targeted testing during development.

```bash
# Build and test specific extension
EXTENSION_LIST=vector make extension-test-build
E2E_TEST_FILES_DIRECTORY=extension/vector/test/test_files ./build/relwithdebinfo/test/runner/e2e_test --gtest_filter="insert.InsertToNonEmpty"
```

--------------------------------

### Test Ladybug Agent (Make)

Source: https://github.com/ladybugdb/ladybug/blob/main/AGENTS.md

Commands for building and running tests for the Ladybug Agent. Use 'make test-build-release' for faster build times when testing.

```bash
make test-build
# Build tests (RelWithDebInfo)
```

```bash
make test
# Run all tests
```

```bash
make test-build-release
# Build and run tests (Release which is faster to build)
```

```bash
E2E_TEST_FILES_DIRECTORY=test/test_files build/release/test/runner/e2e_test --gtest_filter="*merge_tinysnb.Merge*"
# Run specific test with gtest filter
```

```bash
make extension-test-build
make extension-test
# Extension tests
```

```bash
make pytest           # Python tests
make javatest         # Java tests
make nodejstest       # Node.js tests
make rusttest         # Rust tests
make wasmtest         # WASM tests
# Language-specific tests
```

--------------------------------

### Add Library to Build

Source: https://github.com/ladybugdb/ladybug/blob/main/src/function/date/CMakeLists.txt

Use this to add a new library to the build process, specifying source files.

```cmake
add_library(lbug_function_date
        OBJECT
        date_functions.cpp)
```

--------------------------------

### Ladybug Build Configurations

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/build_tips.md

Customize Ladybug builds with specific configurations. Options include enabling runtime checks, treating warnings as errors, link-time optimization, and setting page size or vector capacity.

```bash
# Runtime checks
make debug RUNTIME_CHECKS=1
```

```bash
# Treat warnings as errors
make release WERROR=1
```

```bash
# Link-time optimization
make release LTO=1
```

```bash
# Page size configuration
make release PAGE_SIZE_LOG2=12
```

```bash
# Vector capacity configuration
make release VECTOR_CAPACITY_LOG2=11
```

--------------------------------

### Build miniz Static Library

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/miniz/CMakeLists.txt

Configures CMake to build the miniz library as a static library and sets public include directories.

```cmake
if(POLICY CMP0063)
    cmake_policy(SET CMP0063 NEW)
endif()

add_library(miniz STATIC miniz.cpp)

target_include_directories(
  miniz
  PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>)
```

--------------------------------

### Verify Checkpoint Order and FSM Serialization

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/incidents/2026-02-17-fsm-leak-copy-rollback-recovery.md

Confirm that the Finite State Machine (FSM) is serialized correctly within the checkpoint process and that reloaded data reflects the expected free page count.

```cpp
writeCheckpoint()
```

```cpp
checkpointStorage()
```

```cpp
serializeCatalogAndMetadata()
```

```cpp
serializeMetadata()
```

```cpp
logCheckpointAndApplyShadowPages()
```

```cpp
finalizeCheckpoint()
```

--------------------------------

### Fetch and Use cpptrace for Backtraces

Source: https://github.com/ladybugdb/ladybug/blob/main/CMakeLists.txt

Fetches the cpptrace library from GitHub if not found on the system and enables backtrace printing for fatal signals.

```cmake
set(DOWNLOAD_CPPTRACE TRUE)
    if(${PREFER_SYSTEM_DEPS})
        find_package(cpptrace QUIET)
        if(cpptrace_FOUND)
            message(STATUS "Using system cpptrace")
            set(DOWNLOAD_CPPTRACE FALSE)
        endif()
    endif()
    if(${DOWNLOAD_CPPTRACE})
        message(STATUS "Fetching cpptrace from GitHub...")
        include(FetchContent)
        FetchContent_Declare(
            cpptrace
            GIT_REPOSITORY https://github.com/jeremy-rifkin/cpptrace.git
            GIT_TAG        v0.8.3
            GIT_SHALLOW    TRUE
        )
        FetchContent_MakeAvailable(cpptrace)
    endif()
```

--------------------------------

### Run Ladybug Shell

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/shell.md

Execute the built shell from the ./build/release/tools/shell/ or ./build/debug/tools/shell/ directory.

```bash
# After building
./build/release/tools/shell/lbug

# Or with debug build
./build/debug/tools/shell/lbug
```

--------------------------------

### Handle Precompiled Library Options

Source: https://github.com/ladybugdb/ladybug/blob/main/CMakeLists.txt

Manages deprecated and aliased options for precompiled libraries, ensuring consistency between LBUG_API and LBUG_NODEJS settings.

```cmake
if(LBUG_NODEJS_USE_PRECOMPILED_LIB)
    set(LBUG_API_USE_PRECOMPILED_LIB TRUE)
endif()
if(LBUG_NODEJS_PRECOMPILED_LIB_PATH AND NOT LBUG_API_PRECOMPILED_LIB_PATH)
    set(LBUG_API_PRECOMPILED_LIB_PATH "${LBUG_NODEJS_PRECOMPILED_LIB_PATH}")
endif()
if(LBUG_API_USE_PRECOMPILED_LIB)
    set(LBUG_NODEJS_USE_PRECOMPILED_LIB TRUE CACHE BOOL "Deprecated alias for LBUG_API_USE_PRECOMPILED_LIB." FORCE)
    set(BUILD_LBUG FALSE CACHE BOOL "Build Lbug." FORCE)
endif()
if(LBUG_API_PRECOMPILED_LIB_PATH)
    set(LBUG_NODEJS_PRECOMPILED_LIB_PATH "${LBUG_API_PRECOMPILED_LIB_PATH}" CACHE FILEPATH "Deprecated alias for LBUG_API_PRECOMPILED_LIB_PATH." FORCE)
endif()
```

--------------------------------

### Add Snappy Static Library

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/snappy/CMakeLists.txt

Defines the 'snappy' library as a static library, including its source files.

```cmake
add_library(snappy
    STATIC
    snappy.cc
    snappy-sinksource.cc)
```

--------------------------------

### Add Ladybug Planner Factorization Library

Source: https://github.com/ladybugdb/ladybug/blob/main/src/planner/operator/factorization/CMakeLists.txt

Use this CMake command to add the lbug_planner_factorization library as an OBJECT library, compiling source files into object files.

```cmake
add_library(lbug_planner_factorization
        OBJECT
        flatten_resolver.cpp
        sink_util.cpp)
```

--------------------------------

### Include Directories for Generated Code and Libraries

Source: https://github.com/ladybugdb/ladybug/blob/main/src/extension/CMakeLists.txt

Sets include directories for the generated code and the httplib third-party library.

```cmake
include_directories(
        "${CMAKE_CURRENT_BINARY_DIR}/codegen/include/"
        ${PROJECT_SOURCE_DIR}/third_party/httplib
)
```

--------------------------------

### Set OS-Specific Definitions

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/brotli/CMakeLists.txt

Adds preprocessor definitions based on the detected operating system (Linux, FreeBSD, macOS).

```cmake
if(${CMAKE_SYSTEM_NAME} MATCHES "Linux")
  add_definitions(-DOS_LINUX)
elseif(${CMAKE_SYSTEM_NAME} MATCHES "FreeBSD")
  add_definitions(-DOS_FREEBSD)
elseif(${CMAKE_SYSTEM_NAME} MATCHES "Darwin")
  add_definitions(-DOS_MACOSX)
  set(CMAKE_MACOS_RPATH TRUE)
  set(CMAKE_INSTALL_NAME_DIR "${CMAKE_INSTALL_FULL_LIBDIR}")
endif()
```

--------------------------------

### Read JSON File with Options

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/yyjson/README.md

Reads a JSON file from disk, enabling options like comments and trailing commas for more lenient parsing. Error handling is included to report issues during file reading.

```c
// Read JSON file, allowing comments and trailing commas
yyjson_read_flag flg = YYJSON_READ_ALLOW_COMMENTS | YYJSON_READ_ALLOW_TRAILING_COMMAS;
yyjson_read_err err;
yyjson_doc *doc = yyjson_read_file("/tmp/config.json", flg, NULL, &err);

// Iterate over the root object
if (doc) {
    yyjson_val *obj = yyjson_doc_get_root(doc);
    yyjson_obj_iter iter;
    yyjson_obj_iter_init(obj, &iter);
    yyjson_val *key, *val;
    while ((key = yyjson_obj_iter_next(&iter))) {
        val = yyjson_obj_iter_get_val(key);
        printf("%s: %s\n", yyjson_get_str(key), yyjson_get_type_desc(val));
    }
} else {
    printf("read error (%u): %s at position: %ld\n", err.code, err.msg, err.pos);
}

// Free the doc
yyjson_doc_free(doc);

```

--------------------------------

### Run Copy Operation Verification Tests

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/incidents/2026-02-16-connection-close-sigsegv.md

Execute the copy operation tests. All 19 tests passed successfully.

```bash
build/relwithdebinfo/test/copy/copy_tests
```

--------------------------------

### Build Ladybug Shell

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/shell.md

Use 'make shell' to build the release version of the shell. Use 'make shell-debug' for a debug build.

```bash
make shell           # Build shell
make shell-debug     # Debug shell build
```

--------------------------------

### Run C API Verification Tests

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/incidents/2026-02-16-connection-close-sigsegv.md

Execute C API tests, specifically filtering for tests related to connection management. All tests passed.

```bash
build/relwithdebinfo/test/c_api/c_api_test --gtest_filter="*Connection*"
```

--------------------------------

### ClientContext Members for Query Synchronization

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/incidents/2026-02-16-connection-close-sigsegv.md

Adds members to ClientContext to track active queries and synchronize destruction. Use `registerQueryStart()` and `registerQueryEnd()` to manage the query count, and `waitForNoActiveQuery()` to block until all queries are finished.

```cpp
std::atomic<uint32_t> activeQueryCount;
std::mutex mtxForClose;
std::condition_variable cvForClose;
```

```cpp
void registerQueryStart() {
  activeQueryCount.fetch_add(1);
}
```

```cpp
void registerQueryEnd() {
  if (activeQueryCount.fetch_sub(1) == 1) {
    std::lock_guard<std::mutex> lock(mtxForClose);
    cvForClose.notify_all();
  }
}
```

```cpp
void waitForNoActiveQuery() {
  std::unique_lock<std::mutex> lock(mtxForClose);
  cvForClose.wait(lock, [this] { return activeQueryCount == 0; });
}
```

--------------------------------

### Enable Compiler Cache

Source: https://github.com/ladybugdb/ladybug/blob/main/CMakeLists.txt

Detects and enables 'ccache' or 'sccache' as the compiler launcher if available, improving build performance.

```cmake
find_program(CCACHE_PROGRAM ccache)
if (CCACHE_PROGRAM)
    set(CMAKE_C_COMPILER_LAUNCHER "${CCACHE_PROGRAM}")
    set(CMAKE_CXX_COMPILER_LAUNCHER "${CCACHE_PROGRAM}")
    message(STATUS "ccache found and enabled")
else ()
    find_program(CCACHE_PROGRAM sccache)
    if (CCACHE_PROGRAM)
        set(CMAKE_C_COMPILER_LAUNCHER "${CCACHE_PROGRAM}")
        set(CMAKE_CXX_COMPILER_LAUNCHER "${CCACHE_PROGRAM}")
        message(STATUS "sccache found and enabled")
    endif ()
endif ()
```

--------------------------------

### Schema API: getNumGroups() vs getGroupsPosInScope()

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/incidents/2026-02-16-copy-rel-segment-planner-schema-groups.md

Explains the difference between `getNumGroups()` which returns the total number of factorization groups, and `getGroupsPosInScope()` which returns the set of group positions with expressions in the current scope. This distinction is crucial for understanding the bug.

```cpp
#include "planner/operator/schema.h"

// ...

// getNumGroups() (public) returns groups.size() — the total number of factorization groups in the schema.
// getGroupsPosInScope() returns the set of group positions that have at least one expression in the current scope (projected columns).

// So the schema can have getNumGroups() > 1 while getGroupsPosInScope().size() == 1 if only one of the groups has expressions in scope.
```

--------------------------------

### Configure Generated Extension Loader Header

Source: https://github.com/ladybugdb/ladybug/blob/main/src/extension/CMakeLists.txt

This command configures an input header file for the extension loader, replacing placeholders with generated content. The output is placed in the binary directory.

```cmake
configure_file(
        "generated_extension_loader.h.in"
        "${CMAKE_CURRENT_BINARY_DIR}/codegen/include/generated_extension_loader.h"
        @ONLY
)
```

--------------------------------

### Include Directories Configuration

Source: https://github.com/ladybugdb/ladybug/blob/main/tools/benchmark/CMakeLists.txt

Specifies the directories to be included during the build process. Ensure these paths are correct relative to the project source directory.

```cmake
include_directories(
        ./include
        ${PROJECT_SOURCE_DIR}/test/include/test_helper)

```

--------------------------------

### Add LadybugDB Binder Query Library

Source: https://github.com/ladybugdb/ladybug/blob/main/src/binder/query/CMakeLists.txt

Use this CMake command to add the lbug_binder_query library as an object library, specifying its source files.

```cmake
add_library(
        lbug_binder_query
        OBJECT
        bound_insert_clause.cpp
        bound_delete_clause.cpp
        bound_merge_clause.cpp
        bound_set_clause.cpp
        query_graph.cpp
        query_graph_label_analyzer.cpp)
```

--------------------------------

### Rollback in Connection Destructor (Option A)

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/incidents/2026-02-17-minimal-test-checkpoint-timeout.md

Implement this logic in `Connection::~Connection()` after `waitForNoActiveQuery()` to ensure active transactions are rolled back before the client context is destroyed. This prevents potential issues during connection teardown.

```cpp
if (Transaction::Get(*clientContext)) {
  database->getTransactionManager()->rollback(*clientContext, Transaction::Get(*clientContext));
}
clientContext->preventTransactionRollbackOnDestruction = true;
```

--------------------------------

### Detect OS and Architecture

Source: https://github.com/ladybugdb/ladybug/blob/main/CMakeLists.txt

Sets OS_NAME and OS_ARCH based on the build environment. Handles Windows, macOS, and Linux, including ARM64 support. Also configures compiler definitions for Windows SDK headers.

```cmake
set(OS_NAME "unknown")
set(OS_ARCH "amd64")

set(CMAKE_TARGET_PROCESSOR "${CMAKE_SYSTEM_PROCESSOR}")
if(MSVC AND CMAKE_CXX_COMPILER_ARCHITECTURE_ID)
  set(CMAKE_TARGET_PROCESSOR "${CMAKE_CXX_COMPILER_ARCHITECTURE_ID}")
endif()
string(TOLOWER "${CMAKE_TARGET_PROCESSOR}" CMAKE_TARGET_PROCESSOR_LOWER)
string(REGEX MATCH "(arm64|aarch64)" IS_ARM "${CMAKE_TARGET_PROCESSOR_LOWER}")
if(IS_ARM)
  set(OS_ARCH "arm64")
elseif(FORCE_32_BIT)
  set(OS_ARCH "i386")
endif()

if(APPLE)
  set(OS_NAME "osx")
endif()
if(WIN32)
  set(OS_NAME "windows")
  # Prevent Windows min/max macros from breaking std::min/std::max (needed for Clang-on-Windows too)
  add_compile_definitions(NOMINMAX)
  # Required for Windows SDK headers (winnt.h) when using Clang; MSVC branch sets the target arch later.
  if(OS_ARCH STREQUAL "arm64")
    add_compile_definitions(_ARM64_)
    add_compile_definitions(PCG_LITTLE_ENDIAN=1)
  elseif(CMAKE_SIZEOF_VOID_P EQUAL 8)
    add_compile_definitions(_AMD64_)
  else()
    add_compile_definitions(_X86_)
  endif()
endif()
if(UNIX AND NOT APPLE)
  set(OS_NAME "linux") # sorry BSD
endif()
```

--------------------------------

### Quick-Reference Checklist for P0/P1 Incidents

Source: https://github.com/ladybugdb/ladybug/blob/main/security/incidents/INCIDENT_RESPONSE_PLAN.md

A checklist for handling critical (P0/P1) security incidents, covering initial steps, containment, resolution, and post-incident documentation.

```markdown
[ ] Confirm and reproduce the issue privately
[ ] Assign severity and Incident Commander
[ ] Open private tracking channel
[ ] Acknowledge reporter
[ ] Contain: yank/retract affected artifacts or take site offline
[ ] Rotate any leaked secrets
[ ] Develop fix on private branch
[ ] Write regression test
[ ] Peer review the fix
[ ] Coordinate patched release across all affected surfaces
[ ] Verify artifact integrity on all registries
[ ] Publish GitHub Security Advisory + CVE
[ ] Publish user-facing announcement on all channels
[ ] Monitor adoption of fix
[ ] Write post-incident document in security/incidents/
[ ] Update the incident index in this plan
```

--------------------------------

### Configure Roaring Bitmap CMake Policy

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/roaring_bitmap/CMakeLists.txt

Ensures compatibility with CMP0063 policy by setting it to NEW.

```cmake
if (POLICY CMP0063)
    cmake_policy(SET CMP0063 NEW)
endif ()
```

--------------------------------

### Configure Core Libraries Properties

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/brotli/CMakeLists.txt

Configures versioning, SOVERSION, and position-independent code for core Brotli libraries. It also appends include directories, including build-specific paths.

```cmake
foreach(lib ${BROTLI_LIBRARIES_CORE})
  target_link_libraries(${lib} ${LIBM_LIBRARY})
  set_property(TARGET ${lib} APPEND PROPERTY INCLUDE_DIRECTORIES ${BROTLI_INCLUDE_DIRS})
  set_target_properties(${lib} PROPERTIES
    VERSION "${BROTLI_ABI_COMPATIBILITY}.${BROTLI_ABI_AGE}.${BROTLI_ABI_REVISION}"
    SOVERSION "${BROTLI_ABI_COMPATIBILITY}")
  if(NOT BROTLI_EMSCRIPTEN)
    set_target_properties(${lib} PROPERTIES POSITION_INDEPENDENT_CODE TRUE)
  endif()
  set_property(TARGET ${lib} APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES "$<BUILD_INTERFACE:${BROTLI_INCLUDE_DIRS}>")
endforeach()
```

--------------------------------

### Include Directories Configuration

Source: https://github.com/ladybugdb/ladybug/blob/main/tools/shell/CMakeLists.txt

Specifies the directories to be searched for header files during the build process.

```cmake
include_directories(
        include
        ${PROJECT_SOURCE_DIR}/third_party/taywee_args/include
        ${PROJECT_SOURCE_DIR}/third_party/yyjson/src
        ${PROJECT_SOURCE_DIR}/extension/json/src/include
)
```

--------------------------------

### Build Roaring Bitmap as Static Library

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/roaring_bitmap/CMakeLists.txt

Defines the Roaring Bitmap as a static library using its C source file.

```cmake
add_library(roaring_bitmap STATIC roaring.c)
```

--------------------------------

### Configure Ladybug Specific Options

Source: https://github.com/ladybugdb/ladybug/blob/main/CMakeLists.txt

Sets Ladybug-specific build options for relation storage direction and page size log2. Ensures default values are set if not provided.

```cmake
option(LBUG_DEFAULT_REL_STORAGE_DIRECTION "Only store fwd direction in rel tables by default." BOTH)
if(NOT LBUG_DEFAULT_REL_STORAGE_DIRECTION)
    set(LBUG_DEFAULT_REL_STORAGE_DIRECTION BOTH)
endif()
set(LBUG_DEFAULT_REL_STORAGE_DIRECTION ${LBUG_DEFAULT_REL_STORAGE_DIRECTION}_REL_STORAGE)
option(LBUG_PAGE_SIZE_LOG2 "Log2 of the page size." 12)
if(NOT LBUG_PAGE_SIZE_LOG2)
    set(LBUG_PAGE_SIZE_LOG2 12)
endif()
message(STATUS "LBUG_PAGE_SIZE_LOG2: ${LBUG_PAGE_SIZE_LOG2}")
option(LBUG_VECTOR_CAPACITY_LOG2 "Log2 of the vector capacity." 11)
if(NOT LBUG_VECTOR_CAPACITY_LOG2)
    set(LBUG_VECTOR_CAPACITY_LOG2 11)
endif()
message(STATUS "LBUG_VECTOR_CAPACITY_LOG2: ${LBUG_VECTOR_CAPACITY_LOG2}")
```

--------------------------------

### Add Parquet Library

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/parquet/CMakeLists.txt

Adds the 'parquet' library as a static library, including its source files. Use this to build the static parquet library for the project.

```cmake
add_library(parquet
        STATIC
        parquet_constants.cpp
        parquet_types.cpp)
```

--------------------------------

### Run Linting Checks

Source: https://github.com/ladybugdb/ladybug/blob/main/AGENTS.md

Execute clang-tidy checks and retrieve clangd diagnostics using these make commands.

```bash
make tidy             # Run clang-tidy checks
make tidy-analyzer    # Run analyzer-specific tidy checks
make clangd-diagnostics  # Get clangd diagnostics
```

--------------------------------

### Clean Python API Build

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/python.md

Use this make command to clean the build artifacts for the Python API.

```bash
make clean-python-api
```

--------------------------------

### Configure Generated Extension Loader Source

Source: https://github.com/ladybugdb/ladybug/blob/main/src/extension/CMakeLists.txt

This command configures an input C++ source file for the extension loader, replacing placeholders with generated content. The output is placed in the binary directory.

```cmake
configure_file(
        "generated_extension_loader.cpp.in"
        "${CMAKE_CURRENT_BINARY_DIR}/codegen/generated_extension_loader.cpp"
        @ONLY
)
```

--------------------------------

### Define Shell Flags with args Library

Source: https://github.com/ladybugdb/ladybug/blob/main/tools/shell/shell_development_guide.md

This C++ code defines various command-line flags for the LadybugDB shell using the 'args' library. It includes positional arguments, help flags, value flags, and simple flags. Ensure flag strings are lowercase.

```cpp
args::ArgumentParser  parser("LbugDB Shell");
args::Positional<std::string> inputDirFlag(parser, "databasePath",
"Path to the database. If not given or set to ":memory:", the database will be opened "
"under in-memory mode.");
args::HelpFlag  help(parser, "help", "Display this help menu", {'h', "help"});
args::ValueFlag<uint64_t> bpSizeInMBFlag(parser, "",
"Size of buffer pool for default and large page sizes in megabytes",
{'d', "default_bp_size", "defaultbpsize"}, -1u);
args::Flag  disableCompression(parser, "no_compression", "Disable compression",
{"no_compression", "nocompression"});
```

--------------------------------

### Configure Architecture Definitions

Source: https://github.com/ladybugdb/ladybug/blob/main/CMakeLists.txt

Sets compiler definitions (__64BIT__ or __32BIT__) based on the size of a void pointer. Informs the user about the detected architecture.

```cmake
if(CMAKE_SIZEOF_VOID_P EQUAL 8)
    message(STATUS "64-bit architecture detected")
    add_compile_definitions(__64BIT__)
elseif(CMAKE_SIZEOF_VOID_P EQUAL 4)
    message(STATUS "32-bit architecture detected")
    add_compile_definitions(__32BIT__)
    set(__32BIT__ TRUE)
endif()
```

--------------------------------

### Compare Headers with Grep and Warn

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/pybind11/CMakeLists.txt

Compares header files found on disk with those defined in PYBIND11_HEADERS and warns if there are discrepancies. Requires CMake 3.12 or later.

```cmake
if(PYBIND11_MASTER_PROJECT AND NOT CMAKE_VERSION VERSION_LESS 3.12)
  file(
    GLOB_RECURSE _pybind11_header_check
    LIST_DIRECTORIES false
    RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}"
    CONFIGURE_DEPENDS "include/pybind11/*.h")
  set(_pybind11_here_only ${PYBIND11_HEADERS})
  set(_pybind11_disk_only ${_pybind11_header_check})
  list(REMOVE_ITEM _pybind11_here_only ${_pybind11_header_check})
  list(REMOVE_ITEM _pybind11_disk_only ${PYBIND11_HEADERS})
  if(_pybind11_here_only)
    message(AUTHOR_WARNING "PYBIND11_HEADERS has extra files:" ${_pybind11_here_only})
  endif()
  if(_pybind11_disk_only)
    message(AUTHOR_WARNING "PYBIND11_HEADERS is missing files:" ${_pybind11_disk_only})
  endif()
endif()
```

--------------------------------

### Add Ladybug Binder Visitor Library

Source: https://github.com/ladybugdb/ladybug/blob/main/src/binder/visitor/CMakeLists.txt

Defines a new library target named 'lbug_binder_visitor' as an OBJECT library, compiling the specified C++ source files.

```cmake
add_library(
        lbug_binder_visitor
        OBJECT
        confidential_statement_analyzer.cpp
        default_type_solver.cpp
        property_collector.cpp)

```

--------------------------------

### Add Ladybug Planner Scan Library

Source: https://github.com/ladybugdb/ladybug/blob/main/src/planner/operator/scan/CMakeLists.txt

Defines the Ladybug planner scan library as an object library and lists its source files.

```cmake
add_library(lbug_planner_scan
        OBJECT
        logical_count_rel_table.cpp
        logical_expressions_scan.cpp
        logical_index_look_up.cpp
        logical_rel_degree_table.cpp
        logical_scan_node_table.cpp)
```

--------------------------------

### Define Android Build

Source: https://github.com/ladybugdb/ladybug/blob/main/CMakeLists.txt

Defines the __ANDROID__ preprocessor macro when building for Android.

```cmake
message(STATUS "Android ABI detected: ${ANDROID_ABI}")
            add_compile_definitions(__ANDROID__)
            set(__ANDROID__ TRUE)
```

--------------------------------

### Build Brotli Executable

Source: https://github.com/ladybugdb/ladybug/blob/main/third_party/brotli/CMakeLists.txt

Builds the brotli command-line executable if BROTLI_BUILD_TOOLS is enabled. It links the necessary Brotli libraries.

```cmake
if(BROTLI_BUILD_TOOLS)
  add_executable(brotli c/tools/brotli.c)
  target_link_libraries(brotli ${BROTLI_LIBRARIES})
endif()
```

--------------------------------

### Add lbug_planner_sip Library to Build

Source: https://github.com/ladybugdb/ladybug/blob/main/src/planner/operator/sip/CMakeLists.txt

Configures CMake to add the 'lbug_planner_sip' library as an object library, compiling 'logical_semi_masker.cpp'. This is typically used for modular library inclusion in larger projects.

```cmake
add_library(lbug_planner_sip
        OBJECT
        logical_semi_masker.cpp)
```

```cmake
set(ALL_OBJECT_FILES
        ${ALL_OBJECT_FILES} $<TARGET_OBJECTS:lbug_planner_sip>
        PARENT_SCOPE)
```

--------------------------------

### Database Destructor Checkpoint Handling

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/incidents/2026-02-17-minimal-test-checkpoint-timeout.md

The `Database::~Database()` destructor already includes a try-catch block around `checkpoint(clientContext)`, which should theoretically prevent exceptions from propagating. Verify the current implementation and the build of the test binary.

```cpp
try {
  checkpoint(clientContext);
} catch (...) {}
```

--------------------------------

### Search for Direct PageManager Allocations

Source: https://github.com/ladybugdb/ladybug/blob/main/docs/incidents/2026-02-17-fsm-leak-copy-rollback-recovery.md

Grep for direct calls to `allocatePageRange` or similar functions outside of the optimistic allocator and LocalStorage rollback path. This helps identify untracked allocations.

```bash
grep \"allocatePageRange\", \"addNewPages\", \"getPageManager()->allocatePageRange\" outside of OptimisticAllocator and LocalStorage rollback path.
```

--------------------------------

### Enable Testing

Source: https://github.com/ladybugdb/ladybug/blob/main/test/CMakeLists.txt

Enables the CMake testing framework, allowing tests to be discovered and run.

```cmake
enable_testing()
```