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¶

For WHEEL BUILDS (distribution via PyPI):: Use safe, portable baseline architectures to ensure wheels work on a wide range of CPUs without causing SIGILL (Illegal Instruction) crashes.
For SOURCE BUILDS (local installation):: Use -march=native to generate optimal code for the specific CPU where the build is happening, maximizing performance.

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, may break portability) - “safe” : Force portable baseline (ensures compatibility) - Not set : Auto-detect based on build context (recommended)
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:

>>> # Automatically detects CI=true, uses -march=x86-64-v2
>>> get_compile_args()
['-std=c99', '-Wall', '-Wno-strict-prototypes', '-O3', '-march=x86-64-v2']

User installing from source:

>>> # Detects local build, uses -march=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_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_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.

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