Repository navigation
installer: refuse x86_64 builds on CPUs without AVX2/BMI2/FMA, document the floor - #2178
Merged
Merged
Conversation
…nt the floor Motivation: xerj-org#2161 (field report xerj-org#2158). On an Intel Core i3-3110M (Ivy Bridge, x86-64-v2) xerj.exe v1.0.0-rc.98 dies at launch with STATUS_ILLEGAL_INSTRUCTION (0xc000001d) and indexes nothing. The installer had downloaded, verified and installed a binary that could not run on that machine, and nothing told the user why. Root cause: engine/.cargo/config.toml pins every x86_64 target to `-C target-cpu=x86-64-v3`, so release binaries execute AVX2/BMI2/FMA unconditionally. Pre-Haswell Intel, pre-Excavator AMD, some Atom/Celeron/Pentium parts and VMs that hide the flags cannot run them, and neither installer nor documentation said so (the install page listed "x86_64 with AVX2" without the consequence; the README said nothing). Fix, installer side (the issue's third option; lowering the baseline or shipping a -v2 build is a separate maintainer decision and this change does not pre-empt it): landing/get — after the OS/CPU detection and before anything is downloaded, x86_64 hosts are checked for the x86-64-v3 feature set. Linux (and the /proc emulation of Git Bash, MSYS and Cygwin) reads the `flags` line of /proc/cpuinfo (avx avx2 bmi1 bmi2 f16c fma abm movbe xsave — the kernel's names, LZCNT is `abm`); macOS asks hw.optional.{avx1_0,avx2_0,bmi1,bmi2,f16c,fma}. A missing feature stops the installer with the list of what is missing, the reason, the build-from-source command and the escape hatch. Only positive evidence fails the check: no /proc/cpuinfo, no `flags` line or no sysctl answer skips it rather than refusing. XERJ_SKIP_CPU_CHECK=1 bypasses it. On macOS an x86_64 shell on Apple Silicon (Rosetta 2, detected with sysctl.proc_translated as rustup-init does) now installs the native arm64 build instead of an x86_64 one that would run translated and, before macOS 15, without AVX2. landing/get.ps1 — same check for x64. PowerShell 7+ asks System.Runtime.Intrinsics.X86.{Avx,Avx2,Bmi1,Bmi2,Fma,Lzcnt}::IsSupported (CPUID-backed, independent of the OS build). Windows PowerShell 5.1 has no intrinsics API, so it calls kernel32!IsProcessorFeaturePresent with PF_AVX2_INSTRUCTIONS_AVAILABLE (40); that constant only exists since Windows 10 version 2004 (build 19041) and older builds answer 0 whatever the hardware, so the check is skipped below that build. Any exception while probing skips the check. $env:XERJ_SKIP_CPU_CHECK=1 bypasses it. Docs: README (install paragraph and a build-from-source note with `RUSTFLAGS="-C target-cpu=x86-64-v2"`, which overrides the cargo config), docs/install.html (system requirements and the override list) and llms.txt (installer sentence) now state the floor and what to do on an older CPU. Evidence: landing/get run under busybox ash (alpine:3.20) and dash (debian:bookworm-slim) with /proc/cpuinfo bind-mounted to a copy of this machine's cpuinfo stripped of avx2/bmi2/fma: refuses with "this CPU lacks avx2 bmi2 fma", exit 1, before any network access; with XERJ_SKIP_CPU_CHECK=1, with a cpuinfo that has no `flags` line, and with the real cpuinfo it proceeds to the download. macOS paths run with shimmed uname/sysctl: a translated shell installs aarch64-apple-darwin, an Ivy Bridge Mac refuses naming avx2_0 bmi1 bmi2 fma, a Haswell+ Mac proceeds. landing/get.ps1 parsed by System.Management.Automation.Language.Parser and run under pwsh 7.4.2: passes on this CPU, refuses when every intrinsics class is forced to unsupported, proceeds with the override, and does not probe at all on ARM64. The unmodified end-to-end install of v1.0.0-rc.98 still works on this machine. shellcheck -s sh -S warning is clean; .github/scripts/installer-lint.sh and the scripts/seo gates pass. An AI coding agent (Claude Code) wrote this change under my direction; I reviewed the diff and the test results.
Owner
|
Xerj Merger made the fix: both installers ( |
This was referenced Oct 23, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes the installer/docs part of #2161 (field report #2158). It implements the issue's third option: check the CPU before downloading, say why, and document the requirement. It does not change the build baseline, so lowering it to
x86-64-v2or shipping a-v2build stays a separate decision and this change does not get in its way.What was wrong
Every x86_64 release target is built with
-C target-cpu=x86-64-v3(engine/.cargo/config.toml). On a CPU without AVX2/BMI2/FMA the binary dies at launch (STATUS_ILLEGAL_INSTRUCTIONon Windows,Illegal instructionelsewhere) and prints nothing. Both installers downloaded, verified and installed such a binary without a word, and neither the README nor the install page said there was a floor.What this does
landing/get: after OS/CPU detection and before any download, x86_64 hosts are checked for the x86-64-v3 feature set. Linux (and Git Bash / MSYS / Cygwin, whose/procemulation has the same file) reads theflagsline of/proc/cpuinfo; macOS askshw.optional.{avx1_0,avx2_0,bmi1,bmi2,f16c,fma}. A missing feature stops the installer with the list of what is missing, the reason, the build-from-source command and the escape hatch (XERJ_SKIP_CPU_CHECK=1). Only positive evidence refuses: no/proc/cpuinfo, noflagsline or no sysctl answer skips the check instead.Also on macOS: an x86_64 shell on Apple Silicon (Rosetta 2,
sysctl.proc_translated, the same correction rustup-init makes) now installs the native arm64 build instead of an x86_64 one that would run translated, and before macOS 15 without AVX2.landing/get.ps1: same check for x64. PowerShell 7+ usesSystem.Runtime.Intrinsics.X86.*::IsSupported(CPUID-backed). Windows PowerShell 5.1 has no intrinsics API, so it callskernel32!IsProcessorFeaturePresent(PF_AVX2_INSTRUCTIONS_AVAILABLE = 40); per Microsoft's docs that constant exists since Windows 10 version 2004 (build 19041) and older builds answer 0 whatever the hardware, so 8000 the check is skipped below that build rather than refusing good hardware. Any exception while probing skips the check.$env:XERJ_SKIP_CPU_CHECK=1bypasses it.RUSTFLAGS="-C target-cpu=x86-64-v2", which overrides the cargo config),docs/install.html(system requirements and the override list) andllms.txt(installer sentence).The refusal on a machine like the one in #2158 reads:
Verified
landing/getunder busybox ash (alpine:3.20) and dash (debian:bookworm-slim),/proc/cpuinfobind-mounted to a copy of this machine's cpuinfo withavx2,bmi2andfmaremoved: refuses withthis CPU lacks avx2 bmi2 fma, exit 1, before any network access. WithXERJ_SKIP_CPU_CHECK=1, with a cpuinfo that has noflagsline, and with the real cpuinfo, it proceeds to the download.uname/sysctl: a translated shell installsaarch64-apple-darwinwith the note; an Ivy Bridge Mac (avx2_0/bmi1/bmi2/fma= 0) refuses naming those four; a Haswell+ Mac proceeds.landing/get.ps1parsed withSystem.Management.Automation.Language.Parser(asinstaller-lint.shdoes) and run under pwsh 7.4.2 (mcr.microsoft.com/powershell): passes on this CPU and stops at the expected 404 for a fake version; refuses when every intrinsics class is forced to unsupported; proceeds with the override; does not probe at all when the machine architecture is ARM64.landing/geton this machine: installs v1.0.0-rc.98,xerj --versionanswers.shellcheck -s sh -S warning landing/getclean (koalaman/shellcheck:stable);bash .github/scripts/installer-lint.shpasses;build_articles,fix_heads,fix_links,mk_og_card,gen_sitemap--check,seo_lint.pyand the threescripts/seo/test_*.pypass.RUSTFLAGS="-C target-cpu=x86-64-v2" cargo check -p xerj-serverfinishes (2 min 41 s, exit 0), so the env override is accepted on top ofengine/.cargo/config.tomland nothing in the tree requires the v3 features at compile time (no#[cfg(target_feature)]or#[target_feature]inengine/crates). Not a full release build, not run on a v2 CPU.Assumed, not verified
Add-TypeP/Invoke ofIsProcessorFeaturePresent) was not run: no Windows machine here. It is parsed, wrapped intry/catchso a failure skips the check, and gated on build ≥ 19041 per Microsoft's documentation of the constant. What would falsify it: a 5.1 session on an AVX2 machine with build ≥ 19041 where the call returns 0.hw.optional.*key names come from Apple's sysctl list as used by cpu_features and MacPorts tickets, andsysctl.proc_translatedfrom Apple's Rosetta documentation. What would falsify it: an Intel Mac where one of the six keys answers 0 on hardware that has the feature./proc/cpuinfocarries aflagsline with the kernel's names; if it does not, the check is skipped there, not wrong.Not run: the Rust test suite, nothing under
engine/changes.Provenance
An AI coding agent (Claude Code) wrote this change and the verification script, under my direction; I reviewed the diff and the results. No
Co-Authored-Bytrailer, perAGENTS.md.