18.5. Porting and Integration - 5.2 English - 57404

AOCL-Utils provides utility services to applications and other AOCL libraries. The library supports both C and C++ interfaces and is cross-platform (Linux and Windows).

CMake Integration

In your CMakeLists.txt file:

# Set include directories
target_include_directories(my_app PRIVATE
    /path/to/aocl-utils/include
)

# Link library
target_link_libraries(my_app PRIVATE
    /path/to/aocl-utils/lib/libaoclutils.so  # or .a for static
)

Alternative using find_library:

find_library(AOCL_UTILS_LIB
    NAMES aoclutils
    PATHS /path/to/aocl-utils/lib
)
target_link_libraries(my_app PRIVATE ${AOCL_UTILS_LIB})

Makefile Integration

In the compiler flags of your Makefile:

CFLAGS += -I/path/to/aocl-utils/include
LDFLAGS += -L/path/to/aocl-utils/lib -laoclutils

# For static library, also link stdc++
LDFLAGS += -L/path/to/aocl-utils/lib -l:libaoclutils.a -lstdc++

Example Makefile:

CC = gcc
CFLAGS = -std=gnu11 -I/path/to/include
LDFLAGS = -L/path/to/lib -laoclutils

my_app: my_app.c
    $(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)

Command-Line Integration

See the Usage section for detailed command-line integration examples.

Important Integration Notes:

1. Compiler Compatibility: Use the same compiler for AOCL-Utils and your application. Mixing compilers can cause ABI incompatibilities.

2. Static vs Dynamic Linking:

   • Dynamic (recommended for development): Link against libaoclutils.so (Linux) or libaoclutils.lib (Windows). Ensure library is in LD_LIBRARY_PATH (Linux) or PATH (Windows).

   • Static: Link against libaoclutils.a (Linux) or libaoclutils_static.lib (Windows). You must also link libstdc++: -lstdc++. Larger binary but no runtime dependencies.

3. Header Organization:

   • C++ headers: include/Au/

   • C headers: include/Capi/

   • Deprecated headers: include/Bcl/alci/ (avoid in new code)

4. Module Selection: Use libaoclutils (combined library with au_core + au_cpuid) unless you have specific size constraints.

5. Backward Compatibility: Old ALCI APIs deprecated since 4.2. Enable with AU_ENABLE_OLD_API=ON if needed. Migrate to new APIs (Au::X86Cpu, au_cpuid_*) for future compatibility.

Integration Best Practices:

• Start with dynamic linking for faster development iteration

• Initialize CPU detection once at application startup

• Pin threads after thread pool creation, before heavy computation

• Use logger for diagnostics during development, reduce verbosity in production

• Test on target AMD Zen hardware for accurate CPU detection

Refer to the SDK/Examples folder in the repository for integration examples and out-of-tree compilation details.