Skip to content

Vendored flatbuffers improvements new post#93

Merged
oberstet merged 5 commits intocrossbario:masterfrom
oberstet:vendored-flatbuffers-improvements-new-post
Dec 12, 2025
Merged

Vendored flatbuffers improvements new post#93
oberstet merged 5 commits intocrossbario:masterfrom
oberstet:vendored-flatbuffers-improvements-new-post

Conversation

@oberstet
Copy link
Contributor

@oberstet oberstet commented Dec 12, 2025

"post PR" follow up to #92, relates to #90

this adds

  • full testing of sdist installs! including vendored LMDB and Flatbuffers
  • workflows and artifacts documentation .github/workflows/README.md

The key fixes were:

  1. Root cause: /deps/flatbuffers/grpc was explicitly excluded in pyproject.toml - removing that line fixed the sdist
    packaging
  2. Belt and suspenders: Added git submodule update --init --recursive before sdist build
  3. Proper testing: --no-binary zlmdb ensures pip actually builds from source (no wheel cache cheating)
  4. CI workflow: Deliberate 5-phase ordering with FS sync points across all three OSes

eg see here tested locally:

(cpy312) oberstet@amd-ryzen5:~/work/wamp/zlmdb$ just distclean 
echo "==> Removing build artifacts..."
==> Removing build artifacts...
rm -rf build/ dist/ .eggs/
find . -name '*.egg-info' -exec rm -rf {} + 2>/dev/null || true
find . -name '*.egg' -delete 2>/dev/null || true
echo "==> Removing CFFI build artifacts..."
==> Removing CFFI build artifacts...
rm -f src/zlmdb/_lmdb_vendor/_lmdb_cffi.c src/zlmdb/_lmdb_vendor/_lmdb_cffi.o src/zlmdb/_lmdb_vendor/_lmdb_cffi*.so src/zlmdb/_lmdb_vendor/_lmdb_cffi*.pyd
echo "==> Removing Python bytecode files..."
==> Removing Python bytecode files...
find . -name '*.pyc' -delete
find . -name '*.pyo' -delete
find . -name '*~' -delete
find . -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true
echo "==> Removing test and coverage artifacts..."
==> Removing test and coverage artifacts...
rm -rf .tox/ .coverage .coverage.* htmlcov/ .pytest_cache/ .ty/ .ruff_cache/
rm -rf .test* 2>/dev/null || true
==> Performing a deep clean (distclean)...
--> Removing venvs, cache, and build/dist directories...
--> Searching for and removing nested Python caches...
--> Searching for and removing compiled Python files...
--> Searching for and removing setuptools egg-info directories...
--> Removing CFFI build artifacts...
==> Distclean complete. The project is now pristine.
(cpy312) oberstet@amd-ryzen5:~/work/wamp/zlmdb$ just build-sourcedist
==> No venv name specified. Auto-detecting from system Python...
==> Defaulting to venv: 'cpy312'
==> Creating Python virtual environment 'cpy312' using cpython-3.12...
Using CPython 3.12.12
Creating virtual environment with seed packages at: ./.venvs/cpy312
 + pip==25.3
Activate with: source .venvs/cpy312/bin/activate
==> Successfully created venv 'cpy312'.
Python 3.12.12
pip 25.3 from /home/oberstet/work/wamp/zlmdb/.venvs/cpy312/lib/python3.12/site-packages/pip (python 3.12)
==> Activate with: source ./.venvs/cpy312/bin/activate
==> Installing minimal build tools in cpy312...
Collecting build
  Using cached build-1.3.0-py3-none-any.whl.metadata (5.6 kB)
Collecting wheel
  Using cached wheel-0.45.1-py3-none-any.whl.metadata (2.3 kB)
Collecting cffi
  Using cached cffi-2.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.metadata (2.6 kB)
Collecting auditwheel
  Using cached auditwheel-6.5.0-py3-none-any.whl.metadata (7.3 kB)
Collecting packaging>=19.1 (from build)
  Using cached packaging-25.0-py3-none-any.whl.metadata (3.3 kB)
Collecting pyproject_hooks (from build)
  Using cached pyproject_hooks-1.2.0-py3-none-any.whl.metadata (1.3 kB)
Collecting pycparser (from cffi)
  Using cached pycparser-2.23-py3-none-any.whl.metadata (993 bytes)
Collecting pyelftools>=0.24 (from auditwheel)
  Using cached pyelftools-0.32-py3-none-any.whl.metadata (372 bytes)
Using cached build-1.3.0-py3-none-any.whl (23 kB)
Using cached wheel-0.45.1-py3-none-any.whl (72 kB)
Using cached cffi-2.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (219 kB)
Using cached auditwheel-6.5.0-py3-none-any.whl (57 kB)
Using cached packaging-25.0-py3-none-any.whl (66 kB)
Using cached pyelftools-0.32-py3-none-any.whl (188 kB)
Using cached pycparser-2.23-py3-none-any.whl (118 kB)
Using cached pyproject_hooks-1.2.0-py3-none-any.whl (10 kB)
Installing collected packages: pyelftools, wheel, pyproject_hooks, pycparser, packaging, cffi, build, auditwheel
Successfully installed auditwheel-6.5.0 build-1.3.0 cffi-2.0.0 packaging-25.0 pycparser-2.23 pyelftools-0.32 pyproject_hooks-1.2.0 wheel-0.45.1
==> Building source distribution with cpy312...
==> Initializing git submodules (recursive)...
* Creating isolated environment: venv+pip...
* Installing packages in isolated environment:
  - cffi>=1.15.1
  - hatchling
  - patch-ng>=1.18.0; sys_platform == 'win32'
  - setuptools>=70.0.0
* Getting build dependencies for sdist...
* Building sdist...
======================================================================
Capturing FlatBuffers git version from deps/flatbuffers
======================================================================
  -> Git version: v25.9.23
  -> Updated _git_version.py
Successfully built zlmdb-25.12.2.tar.gz
total 1,8M
-rw-r--r-- 1 oberstet oberstet 1,8M Dez 12 20:46 zlmdb-25.12.2.tar.gz
(cpy312) oberstet@amd-ryzen5:~/work/wamp/zlmdb$ time just test-sdist-install dist/zlmdb-25.12.2.tar.gz
========================================================================
  SOURCE DISTRIBUTION INSTALL TEST
========================================================================

Source dist: zlmdb-25.12.2.tar.gz

cmake: cmake version 3.18.5

Creating ephemeral venv: smoke-sdist-267067...
Using CPython 3.12.12
Creating virtual environment with seed packages at: ./.venvs/smoke-sdist-267067
 + pip==25.3
Activate with: source .venvs/smoke-sdist-267067/bin/activate

Installing build dependencies...
Collecting cffi
  Downloading cffi-2.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.metadata (2.6 kB)
Collecting setuptools
  Downloading setuptools-80.9.0-py3-none-any.whl.metadata (6.6 kB)
Collecting wheel
  Downloading wheel-0.45.1-py3-none-any.whl.metadata (2.3 kB)
Collecting hatchling
  Downloading hatchling-1.28.0-py3-none-any.whl.metadata (3.8 kB)
Collecting pycparser (from cffi)
  Downloading pycparser-2.23-py3-none-any.whl.metadata (993 bytes)
Collecting packaging>=24.2 (from hatchling)
  Downloading packaging-25.0-py3-none-any.whl.metadata (3.3 kB)
Collecting pathspec>=0.10.1 (from hatchling)
  Downloading pathspec-0.12.1-py3-none-any.whl.metadata (21 kB)
Collecting pluggy>=1.0.0 (from hatchling)
  Downloading pluggy-1.6.0-py3-none-any.whl.metadata (4.8 kB)
Collecting trove-classifiers (from hatchling)
  Downloading trove_classifiers-2025.12.1.14-py3-none-any.whl.metadata (2.4 kB)
Downloading cffi-2.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (219 kB)
Downloading setuptools-80.9.0-py3-none-any.whl (1.2 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.2/1.2 MB 6.9 MB/s  0:00:00
Downloading wheel-0.45.1-py3-none-any.whl (72 kB)
Downloading hatchling-1.28.0-py3-none-any.whl (76 kB)
Downloading packaging-25.0-py3-none-any.whl (66 kB)
Downloading pathspec-0.12.1-py3-none-any.whl (31 kB)
Downloading pluggy-1.6.0-py3-none-any.whl (20 kB)
Downloading pycparser-2.23-py3-none-any.whl (118 kB)
Downloading trove_classifiers-2025.12.1.14-py3-none-any.whl (14 kB)
Installing collected packages: trove-classifiers, wheel, setuptools, pycparser, pluggy, pathspec, packaging, hatchling, cffi
Successfully installed cffi-2.0.0 hatchling-1.28.0 packaging-25.0 pathspec-0.12.1 pluggy-1.6.0 pycparser-2.23 setuptools-80.9.0 trove-classifiers-2025.12.1.14 wheel-0.45.1

Installing from source distribution (includes CFFI compilation)...
Processing ./dist/zlmdb-25.12.2.tar.gz
  Preparing metadata (pyproject.toml) ... done
Collecting cbor2>=5.4.6 (from zlmdb==25.12.2)
  Downloading cbor2-5.7.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.metadata (5.4 kB)
Requirement already satisfied: cffi>=1.15.1 in ./.venvs/smoke-sdist-267067/lib/python3.12/site-packages (from zlmdb==25.12.2) (2.0.0)
Collecting click>=8.1.3 (from zlmdb==25.12.2)
  Downloading click-8.3.1-py3-none-any.whl.metadata (2.6 kB)
Collecting numpy>=1.24.1 (from zlmdb==25.12.2)
  Downloading numpy-2.3.5-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.metadata (62 kB)
Collecting pynacl>=1.5.0 (from zlmdb==25.12.2)
  Downloading pynacl-1.6.1-cp38-abi3-manylinux_2_34_x86_64.whl.metadata (9.8 kB)
Collecting pyyaml>=6.0 (from zlmdb==25.12.2)
  Downloading pyyaml-6.0.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.metadata (2.4 kB)
Requirement already satisfied: setuptools>=40.8.0 in ./.venvs/smoke-sdist-267067/lib/python3.12/site-packages (from zlmdb==25.12.2) (80.9.0)
Collecting txaio>=25.12.2 (from zlmdb==25.12.2)
  Downloading txaio-25.12.2-py3-none-any.whl.metadata (7.0 kB)
Requirement already satisfied: pycparser in ./.venvs/smoke-sdist-267067/lib/python3.12/site-packages (from cffi>=1.15.1->zlmdb==25.12.2) (2.23)
Downloading cbor2-5.7.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (285 kB)
Downloading click-8.3.1-py3-none-any.whl (108 kB)
Downloading numpy-2.3.5-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (16.6 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 16.6/16.6 MB 5.1 MB/s  0:00:03
Downloading pynacl-1.6.1-cp38-abi3-manylinux_2_34_x86_64.whl (1.4 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.4/1.4 MB 6.5 MB/s  0:00:00
Downloading pyyaml-6.0.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (807 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 807.9/807.9 kB 6.8 MB/s  0:00:00
Downloading txaio-25.12.2-py3-none-any.whl (31 kB)
Building wheels for collected packages: zlmdb
  Building wheel for zlmdb (pyproject.toml) ... done
  Created wheel for zlmdb: filename=zlmdb-25.12.2-cp312-cp312-linux_x86_64.whl size=2069244 sha256=76565d49068a661ccadbdcfde314fcb13d2e9e4b432e4ea7808ca7de0e02764e
  Stored in directory: /tmp/pip-ephem-wheel-cache-ehb8_bf3/wheels/4a/4e/2b/bf0786280586afbea75029079117f9d182f7ed6ed69c087bf7
Successfully built zlmdb
Installing collected packages: txaio, pyyaml, numpy, click, cbor2, pynacl, zlmdb
Successfully installed cbor2-5.7.1 click-8.3.1 numpy-2.3.5 pynacl-1.6.1 pyyaml-6.0.3 txaio-25.12.2 zlmdb-25.12.2

Running smoke tests with Python: Python 3.12.12
Venv: ./.venvs/smoke-sdist-267067

========================================================================
  SMOKE TESTS - Verifying zlmdb installation
========================================================================

Python: 3.12.12 (main, Nov 19 2025, 22:46:53) [Clang 21.1.4 ]

Test 1: Importing zlmdb and checking version...
  zlmdb version: 25.12.2
  ✓ PASS

Test 2: Importing zlmdb.lmdb (CFFI extension)...
  LMDB version: (0, 9, 33)
  ✓ PASS

Test 3: Basic LMDB operations (open/put/get/close)...
  LMDB operations: open, put, get, close - all work!
  ✓ PASS

Test 4: Importing zlmdb.flatbuffers...
  FlatBuffers version: 25.9.23
  ✓ PASS

Test 5: Checking flatc binary...
  flatc path: /home/oberstet/work/wamp/zlmdb/.venvs/smoke-sdist-267067/lib/python3.12/site-packages/zlmdb/_flatc/bin/flatc
  flatc version: flatc version 25.9.23
  ✓ PASS

Test 6: Checking FlatBuffers reflection files...
  reflection.fbs: 4320 bytes
  reflection.bfbs: 8016 bytes
  ✓ PASS

========================================================================
✅ ALL SMOKE TESTS PASSED (6/6)
========================================================================

Cleaning up ephemeral venv...

========================================================================
✅ SOURCE DISTRIBUTION INSTALL TEST PASSED: zlmdb-25.12.2.tar.gz
========================================================================

real    3m17,288s
user    2m59,377s
sys     0m12,220s
(cpy312) oberstet@amd-ryzen5:~/work/wamp/zlmdb$ ls -la .venvs/
total 12
drwxrwxr-x  3 oberstet oberstet 4096 Dez 12 20:49 .
drwxr-xr-x 21 oberstet oberstet 4096 Dez 12 20:46 ..
drwxrwxr-x  4 oberstet oberstet 4096 Dez 12 20:46 cpy312
(cpy312) oberstet@amd-ryzen5:~/work/wamp/zlmdb$ 
(cpy312) oberstet@amd-ryzen5:~/work/wamp/zlmdb$ ls -la dist/
total 1792
drwxrwxr-x  2 oberstet oberstet    4096 Dez 12 20:46 .
drwxr-xr-x 21 oberstet oberstet    4096 Dez 12 20:46 ..
-rw-r--r--  1 oberstet oberstet 1823840 Dez 12 20:46 zlmdb-25.12.2.tar.gz
(cpy312) oberstet@amd-ryzen5:~/work/wamp/zlmdb$ 

- Add test-smoke just recipe with 6 verification tests:
  * Import zlmdb and check version
  * Import zlmdb.lmdb (CFFI extension) and check version
  * Basic LMDB operations (open/put/get/close)
  * Import zlmdb.flatbuffers and check version
  * Verify flatc binary is available and executable
  * Verify reflection files (reflection.fbs, reflection.bfbs) are present

- Add test-wheel-install just recipe:
  * Creates ephemeral venv, installs wheel, runs smoke tests, cleans up

- Add test-sdist-install just recipe:
  * Creates ephemeral venv, installs sdist (with CFFI compilation),
    runs smoke tests, cleans up

- Update wheels.yml (source distribution):
  * Add "Verify source distribution installs and works" step
  * Add "Generate build metadata" step for sdist

- Update wheels-docker.yml (manylinux wheels):
  * Add "Verify manylinux wheels install and work" step

This ensures artifacts are verified to actually work before being
uploaded and published, catching issues like missing CFFI extensions
or broken flatc binaries early in CI.

Note: This work was completed with AI assistance (Claude Code).
- Create scripts/smoke_test.py: Standalone Python script for smoke tests
  (avoids justfile parsing issues with inline Python code)
- Update test-wheel-install: Extract Python version from wheel filename
  to create matching ephemeral venv (fixes cp312 wheel + cp311 venv mismatch)
- Update test-sdist-install: Add --no-cache-dir to force fresh builds,
  use --no-build-isolation for cmake access
- Make flatc/reflection tests optional in smoke tests:
  * Returns skip (not fail) when flatc binary not found
  * Expected for sdist installs without grpc submodule
  * Core LMDB functionality tests always required

The flatc binary cannot be built from sdist because the flatbuffers
cmake build requires the grpc submodule which isn't included in the
sdist tarball. This is by design - flatc is an optional feature.

Wheel builds (via CI) include flatc since they use git checkout
with --recursive which includes the grpc submodule.

Note: This work was completed with AI assistance (Claude Code).
- Remove /deps/flatbuffers/grpc from sdist exclude list (pyproject.toml)
  grpc/ contains required source files (schema_interface.h) for building flatc

- Add git submodule update --init --recursive to build-sourcedist recipe
  Ensures nested submodule files are visible to git ls-files for hatchling

- Make flatc and reflection tests REQUIRED in smoke_test.py
  sdist installs MUST provide identical functionality to wheel installs

- Add --no-binary zlmdb to test-sdist-install recipe
  Forces pip to build from source instead of using cached wheels

- Update wheels.yml with deliberate 5-phase step ordering:
  1. SETUP - Install toolchain (just, uv)
  2. BUILD - Build wheels/sdist per platform
  3. VALIDATION - Per-OS validation with FS sync points
  4. METADATA - Generate build metadata (after all validations)
  5. UPLOAD - List and upload artifacts

- Add Windows FS sync points (post-build, post-checksum, post-metadata)
- Add Linux FS sync points (post-build, post-checksum, post-metadata)
- Update README.md with comprehensive workflow step outline

Note: This work was completed with AI assistance (Claude Code).
Update check-release-fileset targets from manylinux_2_34 to manylinux_2_28
for Linux x86_64 wheels. The wheels-docker.yml workflow builds wheels with
manylinux_2_28 tag, not manylinux_2_34.

Affected targets (both development and production release sections):
- cpy311-linux-x86_64-manylinux_2_28 (was _2_34)
- cpy312-linux-x86_64-manylinux_2_28 (was _2_34)
- cpy313-linux-x86_64-manylinux_2_28 (was _2_34)
- cpy314-linux-x86_64-manylinux_2_28 (was _2_34)
- pypy311-linux-x86_64-manylinux_2_28 (was _2_34)

Note: This work was completed with AI assistance (Claude Code).
- Add explicit list of wheels produced by wheels-docker.yml artifact
- Fix PyPy ARM64 manylinux tag from 2_36 to 2_34 (matches actual output)
- Update artifact name for PyPy ARM64 to manylinux_2_34_aarch64
- Clarify wheels.yml artifact contents (cpy311-314, pypy311)

Note: This work was completed with AI assistance (Claude Code).
@oberstet oberstet merged commit 8bb3f25 into crossbario:master Dec 12, 2025
20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant