ReqIF2Excel — build and deploy

Project page: https://cosmindxu.github.io/reqif2excel/

The short version

Build once on any single Windows PC, then hand out ReqIF2Excel.exe. The people who use it install nothing: no Python, no pip, no admin rights. The exe carries the interpreter, openpyxl, Pillow and tkinter inside itself.

Building the .exe (Windows)

build\build.bat            REM build only
build\build.bat test       REM run the sample conversion first, then build

The script finds a working Python (rejecting the Microsoft Store alias stubs), creates an isolated .buildenv, installs the dependencies, freezes build\reqif2excel.spec, and leaves the result in dist\:

dist\ReqIF2Excel.exe
dist\reqif2excel_config.json

Requirements: Python 3.12 on the build PC. The bundled wheels include Pillow, which is compiled, so the wheel set is locked to CPython 3.12 (pillow-…-cp312-cp312-win_amd64.whl). build.bat prefers py -3.12, and warns clearly if the Python it found is a different version, because an offline install cannot succeed there. With another Python version, refresh build\wheels\ first (see below).

No internet on the build PC

Nothing to do: build\wheels\ already contains every wheel, and build.bat installs with --no-index when it finds them. See build\OFFLINE_BUILD.txt.

To refresh the wheels after changing build\requirements.txt:

py -3.12 -m pip wheel -r build\requirements.txt -w build\wheels     REM on Windows
PY=python3 bash build/download_wheels.sh                            REM from Linux/macOS

The Linux script cross-downloads win_amd64 / cp312 wheels and explicitly adds pefile and pywin32-ctypes (pip’s --platform skips those two PyInstaller dependencies, and an offline build fails without them). It verifies the set resolves offline before finishing.

Build on a local disk

Do not build inside a synced folder (OneDrive, Box, SharePoint): the sync agent locks files while the virtual environment is created and the build dies with [Errno 13] Permission denied: ...\.buildenv\Scripts\python.exe. Copy the project to C:\Temp\ReqIF2Excel, build there, and take only the exe back.

The Linux binary

bash build/build_linux.sh          # needs uv and binutils; result in dist-linux/

The script builds with a portable CPython (python-build-standalone, installed by uv) and manylinux wheels, so the binary runs on glibc 2.27 or newer (Ubuntu 18.04+, Debian 10+, RHEL/Rocky/Alma 8+, Fedora 28+) instead of only on distributions as new as the build machine. It then measures that floor over every bundled library and smoke-tests the result, rather than trusting PyInstaller’s “Build complete”: the first attempt reported success and produced a binary that could not load Tcl/Tk. It carries its own Tcl/Tk, so the window needs nothing but a running display.

Cross-compiling is not possible

PyInstaller cannot build a Windows exe from Linux. On Linux you can still validate the spec — it produces a Linux binary that proves every import resolves:

pyinstaller build/reqif2excel.spec --noconfirm --clean --distpath /tmp/d --workpath /tmp/w
/tmp/d/ReqIF2Excel sample_data/doors_classic_like.reqifz --out /tmp/check.xlsx

Deploying

1. Copy ReqIF2Excel.exe (and, if you want to preset the options, reqif2excel_config.json) into a writable folder: the Desktop, a share, C:\Tools\ReqIF2Excel. A read-only Program Files install also works, but the app cannot then create its options file.
2. Double-click. The first run creates reqif2excel_config.json next to the exe if it is missing.
3. The exe is unsigned, so SmartScreen may warn: More info → Run anyway, or ask IT to whitelist it.

The exe also works from a script or the command line, with the same options as the Python version:

ReqIF2Excel.exe C:\exports\module.reqifz --out C:\reports\module.xlsx --strict

Because a windowed executable has no console, that run writes its log to ReqIF2Excel_last_run.log next to the workbook. The exit code is still 0 / 1 / 2.

Running from source instead

python -m pip install openpyxl pillow
python reqif2excel_gui.py            REM the window
python reqif2excel.py file.reqifz    REM the command line

run_gui.bat and run_cli.bat do the same on Windows and find their own Python.

Tests before a release

python generate_sample_data.py
python -m pytest tests -q                   REM 74 checks
xvfb-run -a python tests/gui_smoke.py       REM Linux; on Windows just run the GUI

Publishing a release

Binaries are published on the project’s GitHub Releases page, one archive per platform plus a checksum file:

Tag the commit the binaries were built from, and check the Windows exe against it before publishing: the version it reports (--version, the About box) must match.

What to ship

A dated zip of the whole project: the sources, build/ including build/wheels/, docs/ including docs/pdf/, sample_data/, the launchers and this file. Leave out .buildenv/, dist/, __pycache__/ and any personal settings file.