18.6.4. Common Scenarios - 5.2 English - 57404

Build Issues

1. Python3 not found:

   Error: Could NOT find Python3 (missing: Python3_INCLUDE_DIRS Python3_LIBRARIES)

   Cause: Python3 or python3-devel package not installed, or older CMake (3.22-3.24) unable to find python3 library.

   Solution:

   # Ubuntu/Debian
   $ sudo apt-get install python3 python3-dev
   
   # Fedora/RHEL/CentOS
   $ sudo dnf install python3 python3-devel
   

   Or for older CMake:

   $ cmake -B build \
         -DPYTHON_LIBRARIES=/path/to/libpython.so \
         -DPYTHON_INCLUDE_PATH=/path/to/include/python3.x \
         -DPYTHON_EXECUTABLE=/usr/bin/python3
   

2. Python-related build failures:

   Error: Build fails with missing symbols (-ldl, -lutil)

   Cause: Older Python versions can’t find standard libraries

   Solution:

   $ cmake -B build -DCMAKE_CXX_STANDARD_LIBRARIES="-ldl -lutil"
   

3. Missing type_traits errors:

   Error: Errors related to types and type_traits

   Cause: Can’t link to libstdc++ automatically on older systems

   Solution:

   $ cmake -B build -DCMAKE_CXX_STANDARD_LIBRARIES="-lstdc++"
   

4. Missing pthread symbols:

   Error: Undefined reference to pthread functions

   Cause: glibc < 2.34 has libpthread as separate library

   Solution:

   $ cmake -B build -DCMAKE_CXX_STANDARD_LIBRARIES="-lpthread"
   

   Note: Applies to GCC 10 and earlier, or systems with glibc < 2.34

Linking Issues

1. Missing symbols from aoclutils:

   Error: Undefined reference to au_* or Au::* symbols

   Cause: Library not in library search path

   Solution:

   # Linux
   $ export LD_LIBRARY_PATH=/path/to/lib:$LD_LIBRARY_PATH
   
   # Windows
   > set PATH=C:\path\to\bin;%PATH%
   

2. Static library linking issues:

   Cause: Forgot to link libstdc++ with static library

   Solution:

   $ gcc myapp.c -L/path/to/lib -l:libaoclutils.a -lstdc++
   

Runtime Issues

1. CPU not detected / returns false:

   Cause: Library only supports AMD Zen CPUs

   Solution: This is expected behavior on non-AMD or pre-Zen CPUs. Check isAMD() first, then check Zen family.

2. Thread pinning fails:

   Cause: Insufficient permissions

   Solution: May need CAP_SYS_NICE capability on Linux, or run with appropriate permissions

3. Library not found at runtime:

   Cause: Dynamic library not in search path

   Solution:

   # Temporary (Linux)
   $ export LD_LIBRARY_PATH=/path/to/lib:$LD_LIBRARY_PATH
   
   # Permanent (Linux)
   $ echo "/path/to/lib" | sudo tee /etc/ld.so.conf.d/aocl-utils.conf
   $ sudo ldconfig
   

Testing Issues

1. Tests fail to run:

   Cause: QEMU not installed (Linux)

   Solution:

   # Ubuntu
   $ sudo apt-get install qemu-user
   
   # Fedora/RHEL/CentOS
   $ sudo dnf install qemu-user
   

   Note: Do a clean build after installing QEMU

2. Cpuid test failures:

   Cause: Python not installed

   Solution: Install Python 3.9-3.13

Integration Issues

1. Compiler mismatch warnings/errors:

   Cause: Different compilers used for library and application

   Solution: Use same compiler for both (check with gcc --version)

2. Header not found:

   Cause: Include path not set correctly

   Solution: Verify -I flag points to correct include directory

3. Version compatibility:

   Issue: Old ALCI APIs deprecated

   Solution: Migrate to new APIs or enable with AU_ENABLE_OLD_API=ON. Check version.txt in repository.