Principle:Duckdb Duckdb Executable Building
Overview
Linking compiled libraries into executable binaries is the final step of the build pipeline. This principle governs how object files and static/shared libraries are combined with entry points to produce runnable programs such as CLI tools, test runners, and benchmark runners.
Description
After the core DuckDB library has been compiled (as described by the Core Library Compilation principle), the resulting object files and library archives must be linked into executable binaries that users and developers can run directly.
DuckDB produces several executable targets, each serving a distinct purpose:
| Executable | Purpose | Entry Point |
|---|---|---|
| duckdb (CLI shell) | Interactive SQL shell for end users | tools/shell/shell.c
|
| unittest | Automated test runner for correctness verification | test/unittest.cpp
|
| benchmark_runner | Performance benchmark execution | benchmark/benchmark_runner.cpp
|
The build system uses conditional compilation targets to control which executables are produced. Not every build needs all executables -- for example, a release distribution may only need the CLI shell, while a development build needs all three.
Conditional Build Gates
The following CMake options gate executable construction:
BUILD_UNITTESTS-- when enabled, the test runner and benchmark runner targets are included in the build.BUILD_BENCHMARKS-- when enabled, the benchmark runner target is included.BUILD_SHELL-- when enabled (defaultTRUE), the CLI shell is built.
These gates allow the build to be tailored to the deployment context, reducing unnecessary compilation.
Usage
This principle applies after core library compilation has completed. The sequence is:
- Third-party dependencies are compiled.
- Core library modules are compiled and archived into
duckdb_static(or linked asduckdbshared). - Executable targets are defined, linking against the compiled library and any additional dependencies (e.g.,
readlinefor the CLI shell). - The linker produces the final binary executables.
Theoretical Basis
Static Linking
DuckDB executables typically link against the static library (duckdb_static) to produce self-contained binaries with no runtime dependency on the DuckDB shared library. This ensures:
- Portability -- the binary can be distributed and run without requiring users to install the DuckDB library separately.
- Reproducibility -- the exact library code is embedded in the binary, eliminating version mismatch issues.
- Performance -- static linking enables more aggressive link-time optimizations.
Executable Entry Points
Each executable has a well-defined main() entry point that initializes the DuckDB engine and provides the appropriate interface:
- The CLI shell provides an interactive Read-Eval-Print Loop (REPL) for SQL execution.
- The test runner discovers and executes registered test cases, reporting pass/fail results.
- The benchmark runner executes predefined benchmark queries and reports timing metrics.
Conditional Compilation Targets
Conditional compilation targets reduce build times and binary sizes in contexts where not all executables are needed. This follows the principle of minimal builds -- only produce artifacts that are required for the current task.