⚠️ Clean-Room / Educational

This project is educational and Open Source. No code is copied from other emulators. Implementation based solely on technical documentation and permitted tests.

Fix test_build.py Runner (Root)

Date:2026-01-02 StepID:0415 State: VERIFIED

Summary

Mandatory checkpoint correctiontest_build.pywhich checks the compilation of the C++/Cython module. The script was located intests/temp/test_build.pyand it failed when executed from subdirectories due to problems ofsys.path. A robust runner was created in the root of the repository (./test_build.py) that correctly handles thesys.pathand can be run from any location. Compatibility with the original script is maintained through a wrapper that redirects to the root.

Technical Concept: sys.path and Module Resolution in Python

When Python runs a script, it adds the directory where that script is located at the beginning ofsys.path(the list of paths where Python searches for modules). If the script is run from a subdirectory, Python will try to import modules relative to that subdirectory, not to the root of the project.

Identified problem:When runningtests/temp/test_build.pydirectly, Python setssys.path[0] = tests/temp/, which prevents finding the moduleviboy_corewhich is compiled in the root of the project.

Solution:Place the main script in the root of the repository and ensure that the root directory is insys.pathbefore any import. This ensures that Python can find the compiled module regardless of where the script is run from.

Why it is critical: test_build.pyis a mandatory workflow checkpoint that verifies that the pipeline Cython→C++ build option works correctly. If this checkpoint fails, any automated flow breaks and it is impossible to move forward with confidence.

Implementation

A new script was createdtest_build.pyin the root of the repository that:

  • Dynamically calculate the root of the project usingPath(__file__).resolve().parent
  • Insert the root intosys.pathbefore any import
  • Verify the module importviboy_core
  • Run a smoke-test instantiatingPyNativeCoreand callingcore.add(2, 2)
  • Returns correct exit codes (0=OK, 1=FAIL) for pipeline integration

Components created/modified

  • test_build.py(new, root): Main Runner with robust sys.path handling
  • tests/temp/test_build.py(changed): Compatibility wrapper that redirects to the root runner usingthread

Design decisions

  • Location in root:The script must be in the root forsys.pathis configured correctly naturally.
  • Wrapper in tests/temp/:Compatibility is maintained with scripts that can call the test from subdirectories, redirecting throughthreadinstead of manipulatingsys.pathmultiple times.
  • Structured output:The script prints diagnostic information (Python version, path) and clear success/error messages to facilitate debugging.

Affected Files

  • test_build.py(new) - Main runner in root with sys.path handling
  • tests/temp/test_build.py(modified) - Converted into a wrapper that redirects to the root runner

Tests and Verification

Compilation pipeline validation and checkpoint verification:

Command executed:

python3 test_build.py

Result:

==============================================================
Compilation Test - Viboy Color Core (C++/Cython)
==============================================================

[1/3] Importing module 'viboy_core'...
    [OK] Module imported correctly
[test_build] Python: 3.12.3
[test_build] sys.path[0]: /media/fabini/8CD1-4C30/ViboyColor

[2/3] Creating an instance of PyNativeCore...
    [OK] Instance created successfully

[3/3] Running test: core.add(2, 2)...
    [OK] Result: 4

==============================================================
[SUCCESS] The build pipeline works correctly
==============================================================

The C++/Cython core is ready for Phase 2.

Exit code:0 (success)

Compiled C++ module validation:

The test verifies that the moduleviboy_corecompiled from C++/Cython can:

  • Import correctly in Python
  • Instantiate (PyNativeCore())
  • Execute C++ code through the Cython wrapper (core.add(2, 2) == 4)

Exit codes:

  • Build:0 (build successful)
  • test_build.py:0 (checkpoint OK)
  • pytest:1 (10 failed, 13 passed - pre-existing tests, not related to this step)

Sources consulted

  • Python Documentation:sys.path- Module search mechanism
  • Python Documentation:pathlib.Path- Cross-platform route manipulation

Educational Integrity

What I Understand Now

  • sys.path and module resolution:Python adds the directory of the executed script to sys.path[0], which can cause problems if the module is in another directory (such as the project root).
  • Absolute vs relative path:WearPath(__file__).resolve().parentcalculates the absolute location of the script regardless of the current working directory.
  • Pipeline plumbing:Infrastructure scripts like test_build.py are critical to maintaining project health and must be robust and predictable.

What remains to be confirmed

  • N/A - This step is for infrastructure, not emulation.

Hypotheses and Assumptions

We assume that the moduleviboy_corealways compiles in the root of the project (which is true according tosetup.pywhat does he usebuild_ext --inplace).

Next Steps

  • [ ] Investigate and fix the 10 failing pytest tests (mainly related to counting M-Cycles on CPU)
  • [ ] Continue with the development flow now that the checkpoint is operational