Known Issue: Static Libraries and Target Offload

Known Issue: Static Libraries and Target Offload

The following issue affects the Linux* LLVM-based compiler in the Intel® oneAPI Base Tookit and the Intel® oneAPI HPC Toolkit (dpcpp, icx, icpx, and ifx) using static libraries containing offload kernels.

Large applications often are decomposed into component static libraries.  The component libraries are linked, with application object files to form the final executable.  The compiler and linker typically use the -L option to add directories to the library search path and the -l option to specify, in an abbreviated notation, which libraries to link.

For example, an application that builds static library archives libfoo.a or libbar.a and stores them in /path/to/libs would normally link them to the main a program, prog, with

ifx -o prog obj1.o obj2.o -L /path/to/libs -lfoo -lbar
icx -o prog obj1.o obj2.o -L /path/to/libs -lfoo -lbar
dpcpp -o prog obj1.o obj2.o -L /path/to/libs -lfoo -lbar

With this command line the linker will link in object files in the archives libfoo.a or libbar.a that satisfy undefined symbols from previously linked objects on the command line.

Due to a bug, the oneAPI compilers do not support linking library archives using the -l option for libraries that contain target offload code (i.e., offload code for GPU or FPGA).  Instead of using the -l option, the linking command line must specify the full path to the archive (file ending in .a).  Furthermore, the developer must guarantee that all required objects will be linked even if the libraries specified with the -l option were omitted from the command line.  The simplest way to do this is to force linking of the whole archive.

In the above example, assume libbar.a has target offload code, the command line to link could change to

icx -o prog obj1.o obj2.o -L /path/to/libs -lfoo -Wl,--whole-archive /path/to/libs/libbar.a -Wl,--no-whole-archive

Note that the -Wl,--no-whole-archive option is required after the user library even though no additional libraries are listed, because the compiler passes additional libraries to the linker, and not disabling whole-archive mode causes multiply defined symbols for the compiler-specified libraries.

Some library archives contain many routines to support a variety of applications.  In such a case, an application might only use a small fraction of the library, and the cost of linking the whole archive may be considered too high.  

One way to achieve the original behavior is to directly link to any library that might cause inclusion of target offload code.

In the above example, if libbar.a has target offload code, the command line to link could change to

ifx -o prog obj1.o obj2.o /path/to/libs/libfoo.a /path/to/libs/libbar.a

The current situation is considered a defect that will be fixed in a future release of oneAPI. Linux* LLVM-based compilers in the Intel® oneAPI Base Tookit and the Intel® oneAPI HPC Toolkit ( dpcpp, icx, icpx, and ifx) are all affected.

Product and Performance Information


Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804