Error building wheel for mini-racer 13.2 on FreeBSD 13.3

[35gh]

Build of mini-racer fails with the following error:

>pip install mini-racer
Collecting mini-racer
  Using cached mini_racer-0.13.2.tar.gz (38 kB)
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Preparing metadata (pyproject.toml) ... done
Building wheels for collected packages: mini-racer
  Building wheel for mini-racer (pyproject.toml) ... error
  error: subprocess-exited-with-error
  
  × Building wheel for mini-racer (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [37 lines of output]
      running bdist_wheel
      Traceback (most recent call last):
        File "/usr/local/lib/python3.11/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 353, in <module>
          main()
        File "/usr/local/lib/python3.11/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 335, in main
          json_out['return_val'] = hook(**hook_input['kwargs'])
                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/usr/local/lib/python3.11/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 251, in build_wheel
          return _build_backend().build_wheel(wheel_directory, config_settings,
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-3e7k2wxh/overlay/lib/python3.11/site-packages/setuptools/build_meta.py", line 435, in build_wheel
          return _build(['bdist_wheel', '--dist-info-dir', str(metadata_directory)])
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-3e7k2wxh/overlay/lib/python3.11/site-packages/setuptools/build_meta.py", line 423, in _build
          return self._build_with_temp_dir(
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-3e7k2wxh/overlay/lib/python3.11/site-packages/setuptools/build_meta.py", line 404, in _build_with_temp_dir
          self.run_setup()
        File "/tmp/pip-build-env-3e7k2wxh/overlay/lib/python3.11/site-packages/setuptools/build_meta.py", line 317, in run_setup
          exec(code, locals())
        File "<string>", line 94, in <module>
        File "/tmp/pip-build-env-3e7k2wxh/overlay/lib/python3.11/site-packages/setuptools/__init__.py", line 115, in setup
          return distutils.core.setup(**attrs)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-3e7k2wxh/overlay/lib/python3.11/site-packages/setuptools/_distutils/core.py", line 186, in setup
          return run_commands(dist)
                 ^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-3e7k2wxh/overlay/lib/python3.11/site-packages/setuptools/_distutils/core.py", line 202, in run_commands
          dist.run_commands()
        File "/tmp/pip-build-env-3e7k2wxh/overlay/lib/python3.11/site-packages/setuptools/_distutils/dist.py", line 1002, in run_commands
          self.run_command(cmd)
        File "/tmp/pip-build-env-3e7k2wxh/overlay/lib/python3.11/site-packages/setuptools/dist.py", line 1102, in run_command
          super().run_command(command)
        File "/tmp/pip-build-env-3e7k2wxh/overlay/lib/python3.11/site-packages/setuptools/_distutils/dist.py", line 1021, in run_command
          cmd_obj.run()
        File "<string>", line 68, in run
      RuntimeError: Run `just build-dll` before building a PyMiniRacer wheel.
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for mini-racer
Failed to build mini-racer
ERROR: Could not build wheels for mini-racer, which is required to install pyproject.toml-based projects

OS:

>uname -a
FreeBSD pyload 13.3-RELEASE-p4 FreeBSD 13.3-RELEASE-p4 n257491-41f6a830f8e TRUENAS amd64

Pip environment:

>pip debug --verbose
WARNING: This command is only meant for debugging. Do not use this with automation for parsing and getting these details, since the output and options of this command may change without notice.
pip version: pip 23.3.2 from /usr/local/lib/python3.11/site-packages/pip (python 3.11)
sys.version: 3.11.14 (main, Dec 20 2025, 01:24:55) [Clang 19.1.7 (https://github.com/llvm/llvm-project.git llvmorg-19.1.7-0-gcd7080
sys.executable: /usr/local/bin/python3.11
sys.getdefaultencoding: utf-8
sys.getfilesystemencoding: utf-8
locale.getpreferredencoding: UTF-8
sys.platform: freebsd13
sys.implementation:
  name: cpython
'cert' config value: Not specified
REQUESTS_CA_BUNDLE: None
CURL_CA_BUNDLE: None
pip._vendor.certifi.where(): /usr/local/lib/python3.11/site-packages/pip/_vendor/certifi/cacert.pem
pip._vendor.DEBUNDLED: False
vendored library versions:
  CacheControl==0.13.1
  colorama==0.4.6
  distlib==0.3.6
  distro==1.8.0
  msgpack==1.0.5
  packaging==21.3
  platformdirs==3.8.1
  pyparsing==3.1.0
  pyproject-hooks==1.0.0
  requests==2.31.0
  certifi==2023.07.22
  chardet==5.1.0
  idna==3.4
  urllib3==1.26.17
  rich==13.4.2 (Unable to locate actual module version, using vendor.txt specified version)
  pygments==2.15.1
  typing_extensions==4.7.1 (Unable to locate actual module version, using vendor.txt specified version)
  resolvelib==1.0.1
  setuptools==68.0.0 (Unable to locate actual module version, using vendor.txt specified version)
  six==1.16.0
  tenacity==8.2.2 (Unable to locate actual module version, using vendor.txt specified version)
  tomli==2.0.1
  truststore==0.8.0
  webencodings==0.5.1 (Unable to locate actual module version, using vendor.txt specified version)
Compatible tags: 39
  cp311-cp311-freebsd_13_3_release_p4_amd64
  cp311-abi3-freebsd_13_3_release_p4_amd64
  cp311-none-freebsd_13_3_release_p4_amd64
  cp310-abi3-freebsd_13_3_release_p4_amd64
  cp39-abi3-freebsd_13_3_release_p4_amd64
  cp38-abi3-freebsd_13_3_release_p4_amd64
  cp37-abi3-freebsd_13_3_release_p4_amd64
  cp36-abi3-freebsd_13_3_release_p4_amd64
  cp35-abi3-freebsd_13_3_release_p4_amd64
  cp34-abi3-freebsd_13_3_release_p4_amd64
  cp33-abi3-freebsd_13_3_release_p4_amd64
  cp32-abi3-freebsd_13_3_release_p4_amd64
  py311-none-freebsd_13_3_release_p4_amd64
  py3-none-freebsd_13_3_release_p4_amd64
  py310-none-freebsd_13_3_release_p4_amd64
  py39-none-freebsd_13_3_release_p4_amd64
  py38-none-freebsd_13_3_release_p4_amd64
  py37-none-freebsd_13_3_release_p4_amd64
  py36-none-freebsd_13_3_release_p4_amd64
  py35-none-freebsd_13_3_release_p4_amd64
  py34-none-freebsd_13_3_release_p4_amd64
  py33-none-freebsd_13_3_release_p4_amd64
  py32-none-freebsd_13_3_release_p4_amd64
  py31-none-freebsd_13_3_release_p4_amd64
  py30-none-freebsd_13_3_release_p4_amd64
  cp311-none-any
  py311-none-any
  py3-none-any
  py310-none-any
  py39-none-any
  py38-none-any
  py37-none-any
  py36-none-any
  py35-none-any
  py34-none-any
  py33-none-any
  py32-none-any
  py31-none-any
  py30-none-any

[bpcreech]

Hi!

FreeBSD is not a supported platform at this time.

If you're interested in it, I'd accept a pull request!

Some thoughts here:

FreeBSD is not a supported build target for v8 itself. This spells trouble since the v8 build process is very complex, involving multiple compilers, including compilers-of-compilers, many repos dynamically downloaded, and many low-level guards and gates to add memory safety. The v8 ecosystem moves continually without regard for unsupported platforms, so there will be a maintenance burden here.

There is, however, a maintained v8 port for FreeBSD! It lives here. You can sort of tell by the number of patches how complex it is to get working.

Building v8 can take multiple hours and requires many system dependencies—not the experience you typically expect when you pip install a Python package. So the general strategy for PyMiniRacer is to make pre-compiled wheels.

In theory one could add FreeBSD support to PyMiniRacer by pulling in the FreeBSD port build instructions (e.g., just download the port source and run the Makefile from the PyMiniRacer build, which would apply all the patches needed to make it work, etc). We could do this within the PyMiniRacer GitHub actions (i.e., in build.yml)... maybe with this FreeBSD actions helper?

That path could benefit from continued maintenance from the FreeBSD v8 port maintainers—as v8 inevitably shifts and breaks FreeBSD, someone toils away at debugging and patching the problem, and PyMiniRacer gets that fix eventually for free? Of course it would result in FreeBSD needing its own v8 version pin which is probably behind other platforms, and even if the FreeBSD port does most of the heavy lifting for us, I'm sure the build system on the PyMiniRacer side would be complex, fragile, and need continual maintenance.

Alternatively, maybe one could just pull the v8 binary from the FreeBSD port project—don't build v8 ourselves. That could dramatically reduce the complexity of the build. However, we currently lean on v8's own build system to build the PyMiniRacer frontend (which layers a simple C ABI atop the complex and ever-changing V8 C++ API). If we ditch the v8 build for FreeBSD, and just pull in a pre-built v8 binary, we would gain the new job of setting up a C++ build system, including C++ build dependencies, and aligning compiler flags so we actually meet v8's somewhat esoteric C++ ABI. This part, though, could be useful for other platforms, there's no reason for an independent C++ frontend builder for PyMiniRacer to be specific to FreeBSD... it just doesn't exist yet.

[bpcreech]

Another note, I just saw from the FreeBSD v8 port:

PORTVERSION=	10.4.132.20

That's a few years out of date now. Which I know from experience means all of those patches in the FreeBSD port are obsolete, and will need a redo if anyone wants a newer v8 in FreeBSD. :(

EDIT: that's also so old (by v8 standards) that it is now incompatible with the PyMiniRacer C++ frontend (because v8 has made multiple API-breaking chances over the last few years), so even using that old version with PyMiniRacer would require some #ifdefs to PyMiniRacer itself.

[35gh]

Thank you for the feedback and detailed analysis.

Well, I guess it's a dead end... I needed it to run in a Truenas Core jail (FreeBSD 13.3-based) which is now deprecated and unmaintained. So I'll anyway need sooner than later to move to Truenas Scale (Debian-based).