autobahn.nvx._compile_args¶

Centralized compiler flag selection for NVX (Native Vector Extensions) builds.

This module determines appropriate architecture-specific optimization flags for building native C extensions using CFFI. It balances portability and performance based on the build context.

Strategy¶

By default - for every build context (PyPI wheels, local source installs, and cross-compilation) - a safe, portable baseline architecture is used. This keeps the resulting binaries runnable on a wide range of CPUs without SIGILL (Illegal Instruction) crashes, and never hands a cross-compilation toolchain the host-only -march=native flag (which it rejects).

Maximum-performance -march=native code generation is opt-in via AUTOBAHN_ARCH_TARGET=native; use it only when the build host is also the run host (e.g. Gentoo/Arch packages, dedicated single-machine deployments).

Architecture Baselines¶

x86-64 (portable baseline):: -march=x86-64-v2 (microarchitecture level 2, 2009+) Includes: SSE4.2, POPCNT, SSSE3, SSE4.1 Compatible with: Intel Nehalem+, AMD Bulldozer+ (2009+) Coverage: ~99% of x86-64 CPUs from 2010 onwards
ARM64 (portable baseline):: -march=armv8-a (baseline ARMv8-A architecture) Compatible with: Raspberry Pi 4/5, AWS Graviton, Apple M1/M2, etc. Coverage: All 64-bit ARM CPUs

Environment Variables¶

AUTOBAHN_ARCH_TARGETstr, optional

User/distro override for architecture target: - “native” : Force -march=native (maximum performance, build host only;

unsafe for distributed wheels and cross-compilation)

“safe” : Force portable baseline (explicit; same as the default)
Not set : Portable baseline (the safe default; works for cross-compilation)

AUTOBAHN_WHEEL_BUILDstr, optional

Explicit marker for wheel builds (“true” or “1”) When set, forces portable baseline regardless of auto-detection

CIstr, optional

Standard CI environment variable. When “true” or “1”, assumes wheel build.

CIBUILDWHEELstr, optional

Set by cibuildwheel. Indicates wheel build for distribution.

AUDITWHEEL_PLATstr, optional

Set by auditwheel/manylinux builds. Indicates wheel build.

Examples

GitHub Actions building wheels (default):

>>> # Default is the portable baseline
>>> get_compile_args()
['-std=c99', '-Wall', '-Wno-strict-prototypes', '-O3', '-march=x86-64-v2']

User installing from source (default):

>>> # Default is the portable baseline (safe for cross-compilation too)
>>> get_compile_args()
['-std=c99', '-Wall', '-Wno-strict-prototypes', '-O3', '-march=x86-64-v2']

Opting in to -march=native (build host == run host):

>>> import os
>>> os.environ['AUTOBAHN_ARCH_TARGET'] = 'native'
>>> get_compile_args()
['-std=c99', '-Wall', '-Wno-strict-prototypes', '-O3', '-march=native']

Gentoo building package:

>>> # Gentoo wants -march=native for optimized binaries
>>> import os
>>> os.environ['AUTOBAHN_ARCH_TARGET'] = 'native'
>>> get_compile_args()
['-std=c99', '-Wall', '-Wno-strict-prototypes', '-O3', '-march=native']

Debian building package:

>>> # Debian wants portable binaries for all users
>>> import os
>>> os.environ['AUTOBAHN_ARCH_TARGET'] = 'safe'
>>> get_compile_args()
['-std=c99', '-Wall', '-Wno-strict-prototypes', '-O3', '-march=x86-64-v2']

Notes

This module is used by all NVX components: - autobahn.nvx._xormasker (WebSocket frame XOR masking) - autobahn.nvx._utf8validator (WebSocket UTF-8 validation)

Functions¶

`_get_safe_march_flag`(machine)	Returns safe -march flag for portable binaries on the given machine architecture.
`_get_target_machine`()	Return the target machine architecture for the build.
`get_compile_args`()	Returns appropriate compiler arguments for building NVX native extensions.
`is_building_wheel`()	Detect if we're building a wheel for distribution vs. a local source install.

Module Contents¶

_get_safe_march_flag(machine)[source]¶

Returns safe -march flag for portable binaries on the given machine architecture.

Parameters:: machine (str) – Machine architecture from platform.machine().lower()
Returns:: Safe -march flag for the architecture, or None for unknown architectures.
Return type:: str or None

_get_target_machine()[source]¶

Return the target machine architecture for the build.

Uses sysconfig.get_platform() rather than platform.machine() so that the correct architecture is detected when cross-compiling (e.g. Buildroot/Yocto building aarch64 on an x86-64 host): platform.machine() reports the build host (uname), whereas sysconfig reflects the interpreter’s configured target platform. Falls back to platform.machine() when no architecture token can be derived.

(Target-detection approach contributed in PR #1835 by @jameshilliard.)

Returns:: Lower-cased target architecture token, e.g. “x86_64”, “aarch64”, “arm64”.
Return type:: str

get_compile_args()[source]¶

Returns appropriate compiler arguments for building NVX native extensions.

This function determines the optimal compiler flags based on: - Target platform (Windows, Linux, macOS, etc.) - Target architecture (x86-64, ARM64, etc.) - Build context (wheel distribution vs. local source install) - User/distro overrides via environment variables

Returns:: Compiler arguments suitable for current build context. For MSVC: [‘/O2’, ‘/W3’] For GCC/Clang: [‘-std=c99’, ‘-Wall’, ‘-O3’, ‘-march=…’]
Return type:: list of str

Examples

>>> args = get_compile_args()
>>> # Use with CFFI:
>>> ffi.set_source("_nvx_module", c_source, extra_compile_args=args)

is_building_wheel()[source]¶

Detect if we’re building a wheel for distribution vs. a local source install.

Note

As of #1834 the default architecture target is the portable baseline for every build context (wheels, local source installs, cross-compilation), so this helper no longer influences get_compile_args(). It is retained for backward compatibility and for external callers/tooling.

Returns:: True if building a wheel (need portability), False if building locally.
Return type:: bool