-
-
Notifications
You must be signed in to change notification settings - Fork 2
Build Guide
whisprer edited this page Aug 4, 2025
·
1 revision
Get the Universal RNG Library running in under 5 minutes with optimal performance settings for your platform.
- C++17 compatible compiler (GCC 7+, Clang 5+, MSVC 2019+)
- CMake 3.14+ for build system management
- Git for repository access
- Platform-specific SIMD support (AVX2 recommended)
git clone [repository-url] && cd universal-rng
mkdir build && cd build
cmake -S .. -B . -DCMAKE_BUILD_TYPE=Release -DENABLE_AVX2=ON
cmake --build . --config Release -j$(nproc)
./rng_benchmark # Verify installation# Install dependencies via vcpkg (optional)
vcpkg install gtest benchmark
# Configure with MSVC
cmake -S . -B build -G "Visual Studio 16 2019" -A x64
cmake --build build --config Release
# Run tests
.\build\Release\rng_selftest.exeMSVC Optimization Flags:
# CMakeLists.txt additions for maximum performance
if(MSVC)
target_compile_options(universal_rng PRIVATE
/arch:AVX2 # Enable AVX2 instructions
/O2 # Maximum optimization
/Ob2 # Aggressive inlining
/DNDEBUG # Disable assertions
)
endif()# Install MinGW64 toolchain
pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake
# Build with GCC-style flags
cmake -S . -B build -G "MinGW Makefiles"
cmake --build build -j8# Install dependencies
sudo apt update
sudo apt install build-essential cmake ninja-build
# Optional: Install performance analysis tools
sudo apt install perf linux-tools-generic
# Build with maximum optimization
cmake -S . -B build -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_CXX_FLAGS="-march=native -O3 -funroll-loops"
ninja -C build# Install development tools
sudo dnf groupinstall "Development Tools"
sudo dnf install cmake ninja-build
# Build process identical to Ubuntu# Install Xcode tools
xcode-select --install
# Install Homebrew dependencies
brew install cmake ninja
# Build (AVX2 support varies by Mac model)
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
ninja -C build# Enable specific SIMD instruction sets
-DENABLE_AVX2=ON # AVX2 support (default: auto-detect)
-DENABLE_AVX512=OFF # AVX-512 support (experimental)
-DENABLE_NEON=ON # ARM NEON support (ARM platforms)
-DFORCE_SCALAR=OFF # Disable all SIMD (debugging)# Build type optimization
-DCMAKE_BUILD_TYPE=Release # Maximum optimization
-DCMAKE_BUILD_TYPE=RelWithDebInfo # Optimized + debug symbols
-DCMAKE_BUILD_TYPE=Debug # Development/debugging
# Advanced performance flags
-DENABLE_LTO=ON # Link-time optimization
-DENABLE_PGO=ON # Profile-guided optimization
-DBENCHMARK_MODE=ON # Benchmark-specific optimizations# Library components
-DBUILD_SHARED_LIBS=ON # Build as shared library (.dll/.so)
-DBUILD_TESTING=ON # Include unit tests
-DBUILD_BENCHMARKS=ON # Include performance benchmarks
-DBUILD_C_API=ON # C language bindings
-DBUILD_GPU_SUPPORT=OFF # OpenCL GPU acceleration (experimental)set(CMAKE_CXX_FLAGS_RELEASE
"-O3 -march=native -mtune=native -funroll-loops -ffast-math -flto -DNDEBUG")set(CMAKE_CXX_FLAGS_RELEASE
"-O3 -march=native -mtune=native -funroll-loops -ffast-math -flto -DNDEBUG")set(CMAKE_CXX_FLAGS_RELEASE
"/O2 /Ob2 /arch:AVX2 /DNDEBUG /GL")
set(CMAKE_EXE_LINKER_FLAGS_RELEASE "/LTCG")# For production use - maximum speed, minimal size
cmake -S . -B build-performance \
-DCMAKE_BUILD_TYPE=Release \
-DENABLE_AVX2=ON \
-DENABLE_LTO=ON \
-DBUILD_SHARED_LIBS=OFF \
-DCMAKE_CXX_FLAGS="-O3 -march=native -DNDEBUG -funroll-loops" \
-DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON
cmake --build build-performance -j$(nproc)# For development - fast compilation, good debugging
cmake -S . -B build-dev \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DBUILD_TESTING=ON \
-DBUILD_BENCHMARKS=ON \
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON # For IDE integration
cmake --build build-dev -j$(nproc)# For performance analysis and optimization work
cmake -S . -B build-profile \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DBENCHMARK_MODE=ON \
-DENABLE_PROFILING=ON \
-DCMAKE_CXX_FLAGS="-O2 -g -fno-omit-frame-pointer"
cmake --build build-profile -j$(nproc)Problem: CMake fails to detect AVX2 support
# Check CPU capabilities
cat /proc/cpuinfo | grep avx2 # Linux
sysctl machdep.cpu.features # macOS
# Force AVX2 if supported but not detected
cmake -DENABLE_AVX2=ON -DFORCE_AVX2=ONProblem: C++17 features not available
# Check compiler version
gcc --version
clang --version
# Specify modern compiler explicitly
cmake -DCMAKE_CXX_COMPILER=g++-9Problem: Illegal instruction crashes at runtime
# Verify CPU support matches build flags
./rng_selftest --simd-test
# Build with runtime detection instead of compile-time
cmake -DRUNTIME_SIMD_DETECTION=ONProblem: LTO causes build failures or crashes
# Disable LTO for debugging
cmake -DENABLE_LTO=OFF
# Alternative: Use partial LTO
cmake -DCMAKE_INTERPROCEDURAL_OPTIMIZATION=OFF# See exact compiler commands
cmake --build build --verbose
# Or with make
make VERBOSE=1
# Or with ninja
ninja -v# See all CMake variables
cmake -S . -B build -LH
# Check feature detection results
cmake -S . -B build --debug-find# Run comprehensive benchmark suite
./rng_benchmark --benchmark_filter=".*" --benchmark_format=console
# Quick performance check
./rng_benchmark --benchmark_filter="AVX2.*64bit" --benchmark_min_time=1
# Compare against reference implementation
./rng_benchmark --reference_comparison=true# Run all unit tests
./rng_selftest
# Run statistical quality tests (if available)
./rng_statistical_test --algorithm=all --samples=1000000
# Cross-platform compatibility test
./rng_platform_test# Install library
cmake --install build --prefix=/usr/local
# Test installed library
pkg-config --cflags --libs universal-rng# Install cross-compiler
sudo apt install gcc-aarch64-linux-gnu
# Configure for ARM64
cmake -S . -B build-arm64 \
-DCMAKE_SYSTEM_NAME=Linux \
-DCMAKE_SYSTEM_PROCESSOR=aarch64 \
-DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \
-DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \
-DENABLE_NEON=ON# Install MinGW cross-compiler
sudo apt install mingw-w64
# Configure for Windows
cmake -S . -B build-windows \
-DCMAKE_SYSTEM_NAME=Windows \
-DCMAKE_C_COMPILER=x86_64-w64-mingw32-gcc \
-DCMAKE_CXX_COMPILER=x86_64-w64-mingw32-g++# Use Intel C++ Compiler (if available)
cmake -S . -B build-intel \
-DCMAKE_CXX_COMPILER=icpc \
-DCMAKE_CXX_FLAGS="-O3 -xHost -ipo"Before considering your build complete:
- Compilation successful with zero warnings
- All tests pass (
./rng_selftest) - Benchmark runs and shows expected performance ratios
- SIMD detection reports correct CPU capabilities
- Installation works (if building for deployment)
- Performance meets targets (see Performance Analysis wiki)
After successful build:
- Run benchmarks to verify your performance expectations
- Explore the API with the provided examples
- Integrate into your project using the installation
- Report performance results to help improve the library
Build guide optimized for maximum performance across all supported platforms | Updated: August 2025
There is currently data lost off the bottom off the page - a search party needs to be sent in to rescue!
PLEASE DO BEAR IN CONSTANT MIND ABOVE ALL ELSE: CURRENT STATE OF DEVELOPMENT THE C++ STD LIBRARY EMPLOYING MERSENNE TWISTER STILL OUTPERFORMS SINGLE CALCULATION OPERATIONS FOR NON-SIMD BOOSTED COMPUTERS. THESE LIBRARIES FULLY REQUIRE AT LEAST AVX2 MINIMUM TO BENEFIT OVER THE STD GENERATION METHODS WHEN CONSIDERING SINGLE NUMBER GENERATION TASKS.