Skip to content

validation.md

Latest commit

 

History

History
56 lines (40 loc) · 3.63 KB

validation.md

File metadata and controls

56 lines (40 loc) · 3.63 KB
Raw

Build and run

cmake -S CPP/SimpleFPEWrapper -B build-sfpew -G Ninja \
  -DBUILD_TESTING=ON -DSFPEW_LTO=OFF
cmake --build build-sfpew
ctest --test-dir build-sfpew --output-on-failure

The rendering smoke tests create an EGL ES 3 pbuffer/surfaceless context and load the wrapper through dlopen plus eglGetProcAddress. This validates the real interposition route instead of calling project internals directly. A machine without a usable EGL/GLES context skips those tests with code 77.

Test groups

Group Examples What it protects
ABI/lifecycle smoke_dlopen, smoke_error, smoke_list_* Safe load without a context, error handling, display-list semantics.
Draw/state isolation smoke_render, smoke_mixed_pipeline, smoke_vbo_surface, smoke_element_binding_survives, smoke_arraybuffer_heal Fixed-function rendering beside user programs and application VAOs/buffers.
Legacy geometry smoke_list_immediate, smoke_immediate_merge, smoke_ffp_vbo_arrays, smoke_multidraw_native Immediate runs, batching, client/VBO arrays and draw classification.
User shaders smoke_translator, smoke_userobject_*, smoke_userprog_*, smoke_uniform_cache GLSL translation, compatibility uniforms and selective legacy attributes.
Presentation/object lifetime smoke_swap_flushes_batch, smoke_attrib_retire, smoke_buffer_name_reuse Frame-boundary flushing and safe private-object name bookkeeping.
Shader regression corpus piglit.* from tests/piglit GLSL 1.10/1.20 execution and linker behavior through the wrapper.

tests/piglit/KNOWN_DEVIATIONS.txt marks known deviations as CTest WILL_FAIL; a new pass is deliberately visible so the list can be reviewed rather than silently ignored.

Static contract tests

Two CTest checks keep documentation-adjacent source inventories honest:

python3 CPP/SimpleFPEWrapper/tools/gen_api_manifest.py CPP/SimpleFPEWrapper \
  CPP/SimpleFPEWrapper/docs
diff -u CPP/SimpleFPEWrapper/docs/api-manifest.md \
  Web/SimpleFPEWrapper-docs/api/api-manifest.md

python3 CPP/SimpleFPEWrapper/tools/check_backend_profile.py CPP/SimpleFPEWrapper \
  --write CPP/SimpleFPEWrapper/docs/backend-profile.json

The build normally runs comparison checks, not these write commands. Regenerate only after an intentional resolver or backend-table change, copy the reviewed API snapshot into this documentation repository, regenerate the Docsify reference with python3 tools/sync-api-reference.py, and commit all three artifacts together. This keeps the public resolver reference independent from a source checkout while preserving its provenance.

Benchmarking

Enable the optional benchmark registration with -DSFPEW_BENCH=ON, then run:

ctest --test-dir build-sfpew -L bench -V

tests/bench_fpe.c measures CPU overhead for immediate mode, display lists, client arrays, indexed draws, matrix/query paths, shader translation and program behavior. tools/glbench.c and tools/glbench-compare.sh support comparison against another GL 1.x-exporting library. Timing results are diagnostics, not correctness gates.

Failure triage

  1. Record the current EGL backend/version and whether the host used SFPEW's resolver path.
  2. Reduce to a smoke test category: resolver/lifecycle, fixed-function state, array source, generated shader, user shader, or presentation ordering.
  3. For shader failures, set SFPEW_DUMP_SHADERS and, if needed, SFPEW_DEBUG_PRE to preserve transformed input and diagnostics.
  4. Check api_manifest for a name-resolution expectation and backend_profile for pointer-safety expectations before treating a driver error as a renderer bug.