lo Runtime Documentation

The default build of the lo runtime links to system libssl and zlib, but uses a custom version of libcurl to optimize startup time. You must install the development headers for these libraries using your package manager.

sudo apt install -y libcurl4-openssl-dev libssl-dev zlib1g-dev

To produce the smallest possible binary, build the zero runtime. This version uses static linking to minimize size.

lo build runtime runtime/zero

Building on Windows requires Chocolatey, Visual Studio with C++ workloads, and make. You must use an 'x64 Native Tools' command prompt to run the build commands.

# Install Chocolatey (Run as Administrator)
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install make and git via choco
choco install make
choco install git

# Run in 'x64 Native Tools' command prompt
make cleanall lo.exe test

Use make to build the runtime. You can specify the architecture or the compiler used.

# Default build (x64)
make lo

# arm64 architecture
make ARCH=arm64 lo

# Using clang instead of gcc
make CC="clang" CXX="clang++" lo

# Building from a specific branch or tag
export LO_HOME=$(pwd)
LO_VERSION=main make lo
CC="ccache gcc" CXX="ccache g++" LO_VERSION=main ./lo build runtime runtime/lo

# Fast rebuilds using ccache and mold
mold -run make C="ccache gcc" CC="ccache g++" lo

To download and prepare the V8 source code required for the build, run the following command.

make v8/src

To build a minimal runtime that contains only the core binding and no additional modules, use the lo build runtime command pointing to the runtime/core directory.

lo build runtime runtime/core

To build the complete lo runtime, which includes a standard library of common bindings and modules, use the following command:

lo build runtime runtime/lo

The base runtime is the initial runtime built to enable the construction of other runtimes. It packages the core, curl, and inflate bindings required by build scripts. Build it using:

lo build runtime runtime/base

Before building the lo runtime, ensure your system has the following tools installed:

Linux/macOS:

• gcc/g++ or clang/clang++
• make
• curl
• gunzip

Windows:

• Chocolatey
• Visual Studio (with "Desktop Development with C++" workload)
• make and git (via Chocolatey)

To update the V8 version used by lo, you must manually change the version in the Makefile and then perform a clean build.

make cleanall
## change v8 version in makefile
make lo

The lo runtime depends on libcurl (available by default) and openssl. You must install openssl via Homebrew. If your libraries are in a non-standard location, use the LIB_DIRS argument.

# Install openssl
brew install openssl@3

# Build for x64
make cleanall lo

# Build for arm64
make ARCH=arm64 cleanall lo

# Build with custom library directories
make LIB_DIRS=/opt/somewhere_else/lib ARCH=arm64 lo

The Query class is responsible for generating highly optimized JavaScript code to parse the binary or text results returned by PostgreSQL.

When query.generate() is called, it dynamically constructs a Function that uses the parser's state (like dv for DataView and buf for the buffer) to extract fields based on their OIDs (INT4OID, VARCHAROID) and formats (Binary vs Text). This avoids the overhead of generic parsing logic during high-frequency query execution.