Building pgvector for IBM Power11 Architecture
This document provides step-by-step instructions for building and installing the pgvector PostgreSQL extension optimized for IBM Power11 architecture using GCC 14.2.1 with advanced SIMD optimizations.
Note: These build instructions also work for IBM Power10 systems.
Table of Contents
Prerequisites
Install GCC Toolset 14
The build requires GCC 14.2.1 or later for optimal Power11 support:
yum install -y gcc-toolset-14 gcc-toolset-14-gcc gcc-toolset-14-gcc-c++
Verification:
Expected output:
gcc (GCC) 14.2.1 20250110 (Red Hat 14.2.1-13)
Copyright (C) 2024 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Install PostgreSQL Development Headers
Install the EDB Advanced Server 18 development package (or your PostgreSQL version):
yum install -y edb-as18-server-devel
Install Git (if not already installed)
Getting the Source Code
Clone the pgvector Repository
Clone the official pgvector repository from GitHub:
git clone git@github.com:pgvector/pgvector.git
cd pgvector
Alternative using HTTPS:
If you don't have SSH keys configured, use HTTPS:
git clone https://github.com/pgvector/pgvector.git
cd pgvector
Verify the clone:
ls -la
total 120
drwxr-xr-x 8 root root 4096 May 30 14:00 .
drwxr-xr-x 3 root root 4096 May 30 14:00 ..
drwxr-xr-x 8 root root 4096 May 30 14:00 .git
-rw-r--r-- 1 root root 123 May 30 14:00 .editorconfig
-rw-r--r-- 1 root root 456 May 30 14:00 .gitignore
-rw-r--r-- 1 root root 8234 May 30 14:00 CHANGELOG.md
-rw-r--r-- 1 root root 1234 May 30 14:00 Dockerfile
-rw-r--r-- 1 root root 1067 May 30 14:00 LICENSE
-rw-r--r-- 1 root root 3456 May 30 14:00 Makefile
-rw-r--r-- 1 root root 2345 May 30 14:00 README.md
drwxr-xr-x 2 root root 4096 May 30 14:00 sql
drwxr-xr-x 2 root root 4096 May 30 14:00 src
drwxr-xr-x 3 root root 4096 May 30 14:00 test
-rw-r--r-- 1 root root 234 May 30 14:00 vector.control
Optional: Checkout a Specific Version
To build a specific release version:
# List available tags
git tag
# Checkout a specific version (e.g., v0.8.2)
git checkout v0.8.2
For production use, it's recommended to use a tagged release rather than the master branch.
Makefile Optimization Patch
The Makefile already includes Power11 optimizations (lines 25-35). If you need to apply or verify the patch:
Current Power11 Optimization Block
# PowerPC optimization flags
ifneq ($(filter ppc64%, $(shell uname -m)), )
# IBM Power 11 optimized flags for GCC 14
# -O3: Aggressive optimization including auto-vectorization
# -mcpu=power11: Target Power 11 architecture
# -mtune=power11: Tune for Power 11 performance
# -mmma: Enable Matrix-Multiply Assist (MMA) instructions - critical for vector ops
# -mvsx: Enable VSX (Vector-Scalar Extension)
# -maltivec: Enable AltiVec/VMX instructions
OPTFLAGS = -O3 -mcpu=power11 -mtune=power11 -mmma -mvsx -maltivec
endif
Manual Patch (if needed)
If the Makefile doesn't have these optimizations, apply this patch:
cat > power11_optimization.patch << 'EOF'
--- Makefile.orig
+++ Makefile
@@ -23,6 +23,15 @@
endif
endif
+# PowerPC optimization flags
+ifneq ($(filter ppc64%, $(shell uname -m)), )
+ # IBM Power 11 optimized flags for GCC 14
+ OPTFLAGS = -O3 -mcpu=power11 -mtune=power11 -mmma -mvsx -maltivec
+endif
+
# RISC-V64 doesn't support -march=native
ifeq ($(shell uname -m), riscv64)
OPTFLAGS =
EOF
patch -p0 < power11_optimization.patch
Build Process
Step 1: Clean Previous Build Artifacts
make clean PG_CONFIG=/usr/edb/as18/bin/pg_config
What this does:
- Removes compiled object files (*.o)
- Removes shared library (vector.so)
- Removes LLVM bitcode files (*.bc)
- Removes generated SQL files
- Removes test artifacts
Expected output:
rm -f vector.so libvector.a libvector.pc
rm -f sql/vector--0.8.2.sql
rm -f src/bitutils.o src/bitvec.o src/halfutils.o src/halfvec.o src/hnsw.o ...
rm -rf results/ regression.diffs regression.out tmp_check/ tmp_check_iso/ log/ output_iso/
Step 2: Compile the Extension
make PG_CONFIG=/usr/edb/as18/bin/pg_config
What this does:
- Compiles all C source files with Power11 optimizations
- Links object files into the shared library (vector.so)
- Generates LLVM bitcode for JIT compilation support
- Creates SQL migration scripts
Key compilation flags applied:
gcc -Wall -Wmissing-prototypes -Wpointer-arith -Wdeclaration-after-statement \
-Werror=vla -Wendif-labels -Wmissing-format-attribute \
-Wimplicit-fallthrough=3 -Wcast-function-type -Wshadow=compatible-local \
-Wformat-security -fno-strict-aliasing -fwrapv -fexcess-precision=standard \
-Wno-format-truncation -Wno-stringop-truncation \
-O2 -flto=auto -ffat-lto-objects -fexceptions -g -grecord-gcc-switches \
-pipe -Wall -Werror=format-security -Wp,-D_FORTIFY_SOURCE=2 \
-Wp,-D_GLIBCXX_ASSERTIONS -specs=/usr/lib/rpm/redhat/redhat-hardened-cc1 \
-fstack-protector-strong -specs=/usr/lib/rpm/redhat/redhat-annobin-cc1 \
-m64 -mcpu=power9 -mtune=power9 -fasynchronous-unwind-tables \
-fstack-clash-protection \
-O3 -mcpu=power11 -mtune=power11 -mmma -mvsx -maltivec \
-ftree-vectorize -fassociative-math -fno-signed-zeros -fno-trapping-math \
-fPIC -fvisibility=hidden \
-I. -I./ -I/usr/edb/as18/include/server -I/usr/edb/as18/include/internal \
-D_GNU_SOURCE -I/usr/include -I/usr/include/libxml2 \
-c -o src/bitutils.o src/bitutils.c
Compilation process for each source file:
gcc ... -c -o src/bitutils.o src/bitutils.c
gcc ... -c -o src/bitvec.o src/bitvec.c
gcc ... -c -o src/halfutils.o src/halfutils.c
gcc ... -c -o src/halfvec.o src/halfvec.c
gcc ... -c -o src/hnsw.o src/hnsw.c
gcc ... -c -o src/hnswbuild.o src/hnswbuild.c
gcc ... -c -o src/hnswinsert.o src/hnswinsert.c
gcc ... -c -o src/hnswscan.o src/hnswscan.c
gcc ... -c -o src/hnswutils.o src/hnswutils.c
gcc ... -c -o src/hnswvacuum.o src/hnswvacuum.c
gcc ... -c -o src/ivfbuild.o src/ivfbuild.c
gcc ... -c -o src/ivfflat.o src/ivfflat.c
gcc ... -c -o src/ivfinsert.o src/ivfinsert.c
gcc ... -c -o src/ivfkmeans.o src/ivfkmeans.c
gcc ... -c -o src/ivfscan.o src/ivfscan.c
gcc ... -c -o src/ivfutils.o src/ivfutils.c
gcc ... -c -o src/ivfvacuum.o src/ivfvacuum.c
gcc ... -c -o src/sparsevec.o src/sparsevec.c
gcc ... -c -o src/vector.o src/vector.c
Build artifacts created:
vector.so # Main shared library
src/*.o # Object files
src/*.bc # LLVM bitcode files
sql/vector--0.8.2.sql # Generated SQL script
Installation
Install the Extension
make install PG_CONFIG=/usr/edb/as18/bin/pg_config
What this does:
- Installs vector.so to PostgreSQL's library directory
- Installs SQL migration scripts to extension directory
- Installs header files for C extension development
- Installs LLVM bitcode files for JIT compilation
- Creates ThinLTO index for optimized linking
Installation locations:
/usr/edb/as18/lib/vector.so # Shared library
/usr/edb/as18/share/extension/vector.control # Extension control file
/usr/edb/as18/share/extension/vector--*.sql # Migration scripts
/usr/edb/as18/include/server/extension/vector/*.h # Header files
/usr/edb/as18/lib/bitcode/vector/ # LLVM bitcode
/usr/edb/as18/lib/bitcode/vector.index.bc # ThinLTO index
Expected output:
/usr/bin/mkdir -p '/usr/edb/as18/lib'
/usr/bin/mkdir -p '/usr/edb/as18/share/extension'
/usr/bin/mkdir -p '/usr/edb/as18/share/extension'
/usr/bin/install -c -m 755 vector.so '/usr/edb/as18/lib/vector.so'
/usr/bin/install -c -m 644 .//vector.control '/usr/edb/as18/share/extension/'
/usr/bin/install -c -m 644 .//sql/vector--0.1.0--0.1.1.sql ... '/usr/edb/as18/share/extension/'
/usr/bin/mkdir -p '/usr/edb/as18/include/server/extension/vector/'
/usr/bin/install -c -m 644 .//src/halfvec.h .//src/sparsevec.h .//src/vector.h '/usr/edb/as18/include/server/extension/vector/'
/usr/bin/mkdir -p '/usr/edb/as18/lib/bitcode/vector'
/usr/bin/mkdir -p '/usr/edb/as18/lib/bitcode'/vector/src/
/usr/bin/install -c -m 644 src/bitutils.bc '/usr/edb/as18/lib/bitcode'/vector/src/
...
cd '/usr/edb/as18/lib/bitcode' && /usr/lib64/llvm20/bin/llvm-lto -thinlto -thinlto-action=thinlink -o vector.index.bc vector/src/*.bc
Verification
Verify Binary Architecture
file /usr/edb/as18/lib/vector.so
Expected output:
/usr/edb/as18/lib/vector.so: ELF 64-bit LSB shared object, 64-bit PowerPC or cisco 7500,
version 1 (SYSV), dynamically linked, BuildID[sha1]=60dc95f5cfe3fb2e691801b2f3210e624d4a42bf,
with debug_info, not stripped
Explanation:
ELF 64-bit LSB: Linux executable format, 64-bit, little-endianPowerPC: Confirms Power architecturedynamically linked: Uses shared librarieswith debug_info: Contains debugging symbolsnot stripped: Symbols preserved for debugging
Verify Compiler Version
readelf -p .comment /usr/edb/as18/lib/vector.so
Expected output:
String dump of section '.comment':
[ 0] GCC: (GNU) 14.2.1 20250110 (Red Hat 14.2.1-13)
Explanation:
- Confirms the binary was compiled with GCC 14.2.1
- Red Hat build with latest patches
Verify Power11 Optimizations
readelf --debug-dump=info /usr/edb/as18/lib/vector.so 2>/dev/null | grep -A 5 "DW_AT_producer" | head -20
Expected output:
<d> DW_AT_producer : (indirect string, offset: 0x142): GNU GIMPLE 14.2.1 20250110 (Red Hat 14.2.1-13)
-msecure-plt -mcpu=power9 -mtune=power9 -mcpu=power11 -mtune=power11 -m64
-mcpu=power9 -mtune=power9 -mcpu=power11 -mtune=power11 -mmma -mvsx -maltivec
-g -g -O3 -O3 -O2 -O3 -fno-openmp -fno-openacc -fcf-protection=none
-fno-strict-aliasing -fwrapv -fexcess-precision=standard -ffat-lto-objects
-fexceptions -fstack-protector-strong -fasynchronous-unwind-tables
-fstack-clash-protection -ftree-vectorize -fassociative-math -fno-signed-zeros
-fno-trapping-math -fPIC -fvisibility=hidden -fvisibility=hidden -fltrans
-fplugin=gcc-annobin
Key flags to verify:
-mcpu=power11: Targeting Power11 ISA-mtune=power11: Optimized for Power11 microarchitecture-mmma: Matrix-Multiply Assist enabled-mvsx: Vector-Scalar Extension enabled-maltivec: AltiVec/VMX enabled-O3: Maximum optimization level-ftree-vectorize: Auto-vectorization enabled
Check for Power-Specific Instructions
objdump -p /usr/edb/as18/lib/vector.so | grep -i "power\|cpu" | head -10
What to look for:
- Power architecture identification
- CPU-specific attributes
Optimization Flags Explained
Core Power11 Flags
-O3
Purpose: Maximum optimization level
- Enables aggressive inlining
- Loop unrolling and vectorization
- Function specialization
- Predictive commoning
- All
-O2 optimizations plus more
-mcpu=power11
Purpose: Target Power11 instruction set architecture
- Enables Power11-specific instructions
- Uses Power11 instruction scheduling
- Optimizes for Power11 pipeline
-mtune=power11
Purpose: Tune for Power11 microarchitecture
- Optimizes instruction scheduling for Power11 execution units
- Adjusts branch prediction hints
- Optimizes cache access patterns
-mmma
Purpose: Enable Matrix-Multiply Assist (MMA) instructions
- Hardware-accelerated matrix operations
- 4x4 matrix multiply-accumulate
-mvsx
Purpose: Enable Vector-Scalar Extension (VSX)
- 128-bit SIMD operations
- Floating-point vector operations
- 64 vector registers (vs 32 in AltiVec)
-maltivec
Purpose: Enable AltiVec/VMX instructions
- Original PowerPC SIMD instruction set
- 128-bit vector operations
- Integer and floating-point SIMD
Troubleshooting
Issue: Compilation fails with "unknown option -mcpu=power11"
Solution: Upgrade to GCC 14.2.1 or later
yum install -y gcc-toolset-14
scl enable gcc-toolset-14 bash
Issue: Missing MMA instructions in binary
Solution: Verify -mmma flag is present
readelf --debug-dump=info /usr/edb/as18/lib/vector.so | grep mmma
Summary
This build process creates a highly optimized pgvector extension for IBM Power11 systems:
1. GCC 14.2.1 provides latest Power11 support
2. Power11-specific flags enable advanced SIMD instructions
3. MMA instructions accelerate matrix operations critical for vector similarity
4. VSX and AltiVec provide comprehensive SIMD coverage
5. Aggressive optimizations maximize performance while maintaining correctness
The resulting binary leverages Power11's advanced vector processing capabilities for optimal pgvector performance.