Skip to content

troubleshooting.md

Latest commit

 

History

History
189 lines (135 loc) · 3.66 KB

troubleshooting.md

File metadata and controls

189 lines (135 loc) · 3.66 KB

Troubleshooting Guide

This guide helps you resolve common issues when building, running, or profiling the C++ High Performance Guide examples.

Build Failures

CMake Cannot Find Compiler

Symptom:

CMake Error: Could not find a package configuration file provided by "compiler"

Solution:

  1. Verify compiler installation:
g++ --version  # Should show GCC 11+ or Clang 14+
  1. If not found, install:
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install build-essential g++-11

# Fedora/RHEL
sudo dnf install gcc-c++ gcc

# macOS with Homebrew
brew install gcc
  1. If multiple compilers are installed, specify explicitly:
export CC=gcc-11
export CXX=g++-11
cmake --preset=release --fresh

Link Errors with Threads

Symptom:

undefined reference to `pthread_create'

Solution:

  1. Install pthread development files:
sudo apt-get install libpthread-stubs0-dev
  1. Reconfigure with fresh cache:
cmake --preset=release --fresh

Sanitizer Link Errors

Symptom:

/usr/bin/ld: cannot find -lasan

Solution:

Install sanitizer libraries:

# Ubuntu/Debian
sudo apt-get install libasan6 libtsan0 libubsan1

# Fedora
sudo dnf install libasan libtsan libubsan

Note: ASan and TSan are mutually exclusive. Don't use them together.

Runtime Issues

Permission Denied with perf

Symptom:

Error:
Access to performance monitoring and observability operations is limited.

Solutions:

Option 1: Run with sudo (not recommended for regular use)

sudo perf record -g ./benchmark

Option 2: Adjust kernel parameter (temporary)

# Allow users to use perf
echo 1 | sudo tee /proc/sys/kernel/perf_event_paranoid

# Make permanent
echo 'kernel.perf_event_paranoid = 1' | sudo tee /etc/sysctl.d/99-perf.conf
sudo sysctl --system

Option 3: Add user to perf group (recommended)

sudo groupadd perf_users
sudo usermod -a -G perf_users $USER
# Log out and back in

Benchmark Results Too Slow

Symptom: Benchmark results are 10x or more slower than expected.

Diagnosis Steps:

  1. Check build type:
# Should see -O3 for Release
cmake --build build/release --verbose | grep -- -O
  1. Check CPU governor:
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
# Should be "performance", not "powersave"
  1. Set to performance mode:
sudo apt-get install linux-tools-common
sudo cpupower frequency-set --governor performance

Platform-Specific Issues

macOS: perf Not Available

Explanation: macOS doesn't have the Linux perf tool.

Alternatives:

  • Use Instruments (GUI tool from Xcode)
  • Use sample command-line tool
  • Run profiling in Docker/Linux VM

Windows: Build Issues

Explanation: Windows support is best-effort.

Recommendations:

  1. Use WSL2 for full Linux compatibility
  2. Or use Visual Studio 2022 with C++20 support
  3. Some examples (OpenMP, perf) may not work on native Windows

Getting Help

If your issue isn't resolved here:

  1. Search existing issues: GitHub Issues
  2. Check discussions: GitHub Discussions
  3. Create a new issue with:
    • Your OS and version
    • Compiler version (g++ --version)
    • CMake version (cmake --version)
    • Full error message
    • Steps to reproduce

Related Documentation