Implementation:Duckdb Duckdb Append Metadata CMake

Field	Value
source	extension/extension_build_tools.cmake, scripts/append_metadata.cmake, extension/generated_extension_loader.cpp.in
domains	Extension_Development, Build_System
last_updated	2026-02-07

Overview

Concrete tool for building DuckDB extensions and appending metadata sections provided by the CMake build system. This implementation handles two stages: (1) compiling the extension source code into a loadable shared library target, and (2) running a post-build CMake script that appends a structured metadata section to the resulting binary.

Code Reference

Target Creation

Source: extension/extension_build_tools.cmake (lines 100-170)

This CMake module defines the build targets for each loadable extension. It creates a shared library target named <extension_name>_loadable_extension that links against the DuckDB core library and compiles the extension source files into a platform-appropriate shared library (.so, .dylib, or .dll).

Metadata Appending

Source: scripts/append_metadata.cmake (lines 1-69)

This CMake script is executed as a post-build step and appends the metadata section to the compiled binary. It writes the following fields in a fixed format to the end of the file:

[extension binary data]
[platform string, padded to fixed width]
[duckdb version string]
[extension version string]
[ABI type string]
[256 bytes of zeros -- signature placeholder]
[metadata footer magic bytes]

Loader Template

Source: extension/generated_extension_loader.cpp.in (lines 1-29)

A C++ template file that is configured by CMake at generation time. It produces the entry point function that DuckDB calls when loading the extension, wiring up the extension's initialization logic.

I/O Contract

API

Build command:

cmake --build . --target <extension_name>_loadable_extension

Post-build metadata appending (invoked automatically, or manually):

cmake -DEXTENSION=<path_to_built_extension> \
      -DPLATFORM_FILE=<platform_identifier> \
      -DDUCKDB_VERSION=<version> \
      -DEXTENSION_VERSION=<ext_version> \
      -DABI_TYPE=<abi_type> \
      -P scripts/append_metadata.cmake

Parameters

Parameter	Description	Example
EXTENSION	Path to the built .duckdb_extension file	build/release/extension/httpfs/httpfs.duckdb_extension
PLATFORM_FILE	Platform identifier string	linux_amd64, osx_arm64, windows_amd64
DUCKDB_VERSION	DuckDB version the extension is built against	v0.10.0
EXTENSION_VERSION	Version of the extension itself	v0.10.0 or a commit hash
ABI_TYPE	ABI compatibility type	C_STRUCT or CPP

Inputs

• Extension source code (C/C++ files registered in CMakeLists.txt)
• Compiled DuckDB core library (linked at build time)
• scripts/append_metadata.cmake script

Outputs

• <extension_name>.duckdb_extension binary file with appended metadata section containing:
  • Platform string (padded to fixed width)
  • DuckDB version
  • Extension version
  • ABI type string
  • 256-byte signature placeholder (zeroed)
  • Magic footer bytes

Usage Examples

Building the httpfs extension with metadata:

# Configure the build with extensions enabled
mkdir build && cd build
cmake .. -DBUILD_EXTENSIONS="httpfs"

# Build the loadable extension (metadata is appended automatically as post-build step)
cmake --build . --target httpfs_loadable_extension

Manually appending metadata (e.g., in a custom CI pipeline):

cmake -DEXTENSION=build/release/extension/httpfs/httpfs.duckdb_extension \
      -DPLATFORM_FILE=linux_amd64 \
      -DDUCKDB_VERSION=v0.10.0 \
      -DEXTENSION_VERSION=v0.10.0 \
      -DABI_TYPE=C_STRUCT \
      -P scripts/append_metadata.cmake

Verifying metadata was appended (inspect the tail of the binary):

# The last bytes of the file should contain the metadata footer
xxd build/release/extension/httpfs/httpfs.duckdb_extension | tail -20

Related Pages

• Principle:Duckdb_Duckdb_Extension_Build_And_Metadata