8000 installer: refuse x86_64 builds on CPUs without AVX2/BMI2/FMA, document the floor by samuelmbabhazi · Pull Request #2178 · xerj-org/xerj · GitHub
[go: up one dir, main page]

Skip to content

installer: refuse x86_64 builds on CPUs without AVX2/BMI2/FMA, document the floor - #2178

Merged
xerj-org merged 1 commit into
xerj-org:mainfrom
samuelmbabhazi:fix/installer-cpu-check
Oct 22, 2026
Merged

xerj-org merged 1 commit into
xerj-org:mainfrom
samuelmbabhazi:fix/installer-cpu-check

Conversation

@samuelmbabhazi
@samuelmbabhazi samuelmbabhazi commented Oct 22, 2026 •
Copy link
Copy Markdown
Contributor

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-v2 or shipping a -v2 build 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_INSTRUCTION on Windows, Illegal instruction elsewhere) 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 /proc emulation has the same file) reads the flags line of /proc/cpuinfo; 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 (XERJ_SKIP_CPU_CHECK=1). Only positive evidence refuses: no /proc/cpuinfo, no flags line 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+ uses System.Runtime.Intrinsics.X86.*::IsSupported (CPUID-backed). Windows PowerShell 5.1 has no intrinsics API, so it calls kernel32!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=1 bypasses it.
  • Docs: README (install paragraph, plus 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).

The refusal on a machine like the one in #2158 reads:

error: this CPU lacks avx2 bmi2 fma — the x86_64 release binaries are built for x86-64-v3
       (AVX2/BMI2/FMA: Intel Haswell 2013+, AMD Excavator/Zen+) and crash at launch with
       'Illegal instruction' without them (https://github.com/xerj-org/xerj/issues/2161).
       Build for this CPU instead: RUSTFLAGS='-C target-cpu=x86-64-v2' cargo build --release -p xerj-server
         (https://github.com/xerj-org/xerj#build-from-source)
       To install the prebuilt binary anyway (e.g. a sandbox hides flags the hardware has):
         XERJ_SKIP_CPU_CHECK=1

Verified

  • landing/get under busybox ash (alpine:3.20) and dash (debian:bookworm-slim), /proc/cpuinfo bind-mounted to a copy of this machine's cpuinfo with avx2, bmi2 and fma removed: 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 code paths with shimmed uname/sysctl: a translated shell installs aarch64-apple-darwin with the note; an Ivy Bridge Mac (avx2_0/bmi1/bmi2/fma = 0) refuses naming those four; a Haswell+ Mac proceeds.
  • landing/get.ps1 parsed with System.Management.Automation.Language.Parser (as installer-lint.sh does) 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.
  • Unmodified end-to-end run of the new landing/get on this machine: installs v1.0.0-rc.98, xerj --version answers.
  • shellcheck -s sh -S warning landing/get clean (koalaman/shellcheck:stable); bash .github/scripts/installer-lint.sh passes; build_articles, fix_heads, fix_links, mk_og_card, gen_sitemap --check, seo_lint.py and the three scripts/seo/test_*.py pass.
  • The build-from-source advice: RUSTFLAGS="-C target-cpu=x86-64-v2" cargo check -p xerj-server finishes (2 min 41 s, exit 0), so the env override is accepted on top of engine/.cargo/config.toml and nothing in the tree requires the v3 features at compile time (no #[cfg(target_feature)] or #[target_feature] in engine/crates). Not a full release build, not run on a v2 CPU.

Assumed, not verified

  • The Windows PowerShell 5.1 branch (Add-Type P/Invoke of IsProcessorFeaturePresent) was not run: no Windows machine here. It is parsed, wrapped in try/catch so 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.
  • The macOS branch was run against shims, not a Mac: the hw.optional.* key names come from Apple's sysctl list as used by cpu_features and MacPorts tickets, and sysctl.proc_translated from 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.
  • Cygwin/MSYS /proc/cpuinfo carries a flags line 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-By trailer, per AGENTS.md.

…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.
@cla-bot cla-bot Bot added the cla-signed label Oct 22, 2026
@xerj-org
xerj-org merged commit c46d394 into xerj-org:main Oct 22, 2026
24 checks passed
@xerj-org
Copy link
Copy Markdown
Owner

Xerj Merger made the fix: both installers (landing/get, landing/get.ps1) now check x86_64 CPUs for the x86-64-v3 feature set (AVX2/BMI2/FMA) before downloading and refuse with the reason, the build-from-source command and an XERJ_SKIP_CPU_CHECK=1 escape hatch; on Apple Silicon under Rosetta the native arm64 build is installed. README, install page and llms.txt document the CPU floor. Diff reviewed, all CI green. #2161 stays open for the build-baseline decision. Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

0