Introduction to Linking with the Intel© IPP 7.0 Library

There are two ways to link the Intel IPP library with your application: static and dynamic. Within the static solution there are two additional options: linking with the single-threaded static library or with the multi-threaded static library. There are probably an equal number of pros and cons for choosing between dynamic and static linking, this article serves only to illustrate the basic information you need to know regarding how to link, not which approach is "better."

The following instructions assume you have already configured your development system's environment to compile and link applications that will use the Intel IPP library. Please see the Intel® IPP 7.0 Library Getting Started guide For more information on setting up your environment. This KB article only applies to version 7.0 of the Intel IPP library.

Dynamic Linking

The default linkage model used by most of the Intel IPP samples is dynamic (aka linking with shared objects). Dynamic linking against the prebuilt Intel IPP dynamic libraries involves linking with a "stub library" (Windows) or directly with the shared library objects (Linux). The dynamic linking method described here is "implicit linking," meaning that the libraries will be automatically loaded by the operating system at application run-time. (Ignore these instructions if you intend to use "explicit dynamic linking, in which case you probably already know all this and don't need to be reading this article.)

When you link against dynamic libraries the linker's search for external Intel IPP function names (e.g., the names of the Intel IPP function you are calling from within your application) is satisfied without actually including the Intel IPP function code in your application. In this case, the functions you are calling reside within the dynamic link library (DLL) or shared object (SO) files that you must distribute along with your application executable(s).

You can build and distribute a custom shared library (built from the Intel IPP static libraries) or you can distribute the prebuilt shared libraries that are provided with the Intel IPP library. Custom shared libraries are generally much smaller than the prebuilt shared libraries, because you can limit the number of functions included in the shared library file to only those required by your application. If you distribute the standard prebuilt shared libraries you will be including many functions that your application will never use; doing this does not impact the functionality or performance of your application (ignoring memory and/or paging requirements for the larger dynamic library), but it may substantially increase the number and size of the files you distribute to your customer(s).

The instructions for dynamic linking that follow assume you will use the default prebuilt shared library files with your application.

Note: the prebuilt dynamic libraries are multi-threaded using the Intel OpenMP threading library. If this threading technique is incompatible with your application or runtime environment you should use the single-threaded static libraries. If your application requires a dynamic library, you can build a custom dynamic library from the single-threaded static libraries. Please read this Intel IPP FAQ regarding threading and the OpenMP library for more information.

Windows Dynamic Linking

With the release of Intel IPP 7.0 the method by which you specify linkage dependencies has been significantly simplified. All that is required is to include the ipp.h header file in your source files (only those source files that reference Intel IPP functions or data structures need to include the ipp.h header file) and then define a special preprocessor label that will automatically instruct the linker as to which library files need to be linked against your application. In summary:

#include "ipp.h"

goes in your source files that reference Intel IPP functions and data structures and:

/D_IPP_PARALLEL_DYNAMIC

needs to be part of your compiler command line.

This technique works with either the MIcrosoft* Visual Studio* compiler (including the Visual Studio Express compiler) or with the Intel compiler. If you inspect the Intel IPP header files you'll see how this works. It uses a special "#pragma comment( lib, "libfilename" )" feature of these compilers. More information regarding this special pragma can be found here: http://msdn.microsoft.com/en-us/library/7f0aews7(v=vs.71).aspx.

Linux Dynamic Linking

Unfortunately, dynamic linking on the Linux platform requires slightly more effort than the Windows solution shown above. You must determine the names of the libraries you need to link against and include them in your link list. This article, Selecting the Intel® Integrated Performance Primitives (Intel® IPP) libraries needed by your application, can help you identify which library files you depend upon, if you know which domains the functions you are using belong to.

Once you've assembled the list of libraries (or domains) specify the names of the library files that correspond to those names and include the core library at the end of that list. For example, assume your application requires functions from the audio coding and the signal processing domains. Your link list would look like this:

-lippac –lipps –lippcore

The ippcore library is normally located last in the link list. If you inspect the makefiles distributed with the Intel IPP samples you will typically find this list defined as follows:

IPPLIB = -lippac -lipps –lippcore

with subsequent references to the macro $(IPPLIB) within the makefile.

Note that the simplest way to determine which Intel IPP libraries your domain may be dependent upon is to inspect the #pragma definitions used in the include files to direct the Windows* linker (for example, the image compression domain – ippj.h – depends on the image processing and signal processing domains, as well as the core library). These pragma statements are included in the Linux* include files even though they are only used by the Windows* build environments. Not every function within a given domain is dependent upon the other domain libraries listed in the pragma lists!

Static Linking

Static linking requires that you choose between one of two static library solutions: the single-threaded or the multi-threaded static library. Which library you choose to link against depends upon the needs of your application and your runtime environment. If you choose the multi-threaded static library you should understand that you will also need to include the Intel OpenMP library with your application.

Working with static libraries is generally much simpler than dynamic libraries. When you link against an Intel IPP static library the function code is included as part of your application executable. So you only need to distribute your application executable(s) and, optionally, the Intel OpenMP dynamic library if you are using the multi-threaded static library.

Note that when using static linking only the code required by those functions that you call from within your application are included with your executable. In other words, if you call ten Intel IPP functions from within your application then only the code for those ten functions (and any additional functions those ten functions reference) will be included in the final executable. The entire Intel IPP library is not included with your application when you link statically, only those functions that your application requires.

Because the multi-threaded static libraries depend on the Intel OpenMP library, you will also have to link against that library. You can use either the dynamic edition of the Intel Intel OpenMP library or the static edition, regardless of the fact that you are linking against a static version of the Intel IPP library. Linking against the dynamic Intel OpenMP library is shown below, since this is the recommended solution. Likewise, linking statically against the Intel IPP library does not require that you also link statically against other system libraries, such as the C runtime library.

Keep in mind that when you link against the dynamic version of the Intel OpenMP library you will need to distribute that library file along with your executable to your customer(s). Linking statically with the Intel OpenMP library eliminates that requirement but presents the possibility of a resource conflict with other OpenMP libraries that may be used by other applications on the customer's runtime system.

Windows Static Linking

As above, the release of Intel IPP 7.0 simplifies the method by which you specify linkage dependencies on a Windows system. All that is required is to include the ipp.h header file in your source files and define the appropriate preprocessor label that specifies which static library option will be linked against your application. In summary:

#include "ipp.h"

goes in your source files that reference Intel IPP functions and data structures and either:

/D_IPP_PARALLEL_STATIC

or:

/D_IPP_SEQUENTIAL_STATIC

needs to be part of your compiler command line.

This technique works with either the MIcrosoft* Visual Studio* compiler (including the Visual Studio Express compiler) or with the Intel compiler. If you inspect the Intel IPP header files you'll see how it works. This technique uses a special "#pragma comment( lib, "libfilename" )" feature of these compilers. More information regarding this special pragma can be found here: http://msdn.microsoft.com/en-us/library/7f0aews7(v=vs.71).aspx.

The "_IPP_PARALLEL_STATIC" preprocessor label indicates that you want to use the multi-threaded static library. And using the "_IPP_SEQUENTIAL_STATIC" preprocessor label means that you wish to use the single-threaded static library.

Linux Static Linking

Static linking on the Linux platform requires slightly more effort than the Windows solution shown above but is simpler than the Linux dynamic linking solution. Unlike the Linux dynamic linking process, you do not need to determine the names of the libraries against which you need to link before including them in your link list. Instead, you can simply list all the Intel IPP static libraries in your link list and let the linker do the work for you.

If you want to use the multi-threaded libraries your link list macro definition in your makefile should look something like this:

IPPLIB = -lippac_t -lippdc_t -lippcc_t -lippcv_t -lippj_t -lippdi_t -lippch_t -lippm_t -lippr_t -lippsc_t -lippvm_t -lippvc_t -lippi_t -lipps_t -lippcore_t -liomp5 -lpthread

If you use the single-threaded libraries, your link list macro definition in your makefile should look something like this:

IPPLIB = -lippac_l -lippdc_l -lippcc_l -lippcv_l -lippj_l -lippdi_l -lippch_l -lippm_l -lippr_l -lippsc_l -lippvm_l -lippvc_l -lippi_l -lipps_l -lippcore_l

The ippcore library is always located last in the link list of Intel IPP library files, due to the default single-pass nature of the standard Linux linker. The lists shown above should take care of any inter-library dependencies. however, if you have interdependencies between libraries that cause link errors you may need to use the -( and -) options (or equivalent --start-group and --end-group options) around the list of libraries you are linking against to force the linker into multi-pass behavior, at the expense of slightly reduced linker performance. Or, you can repeat the name of a library on the link list to resolve circular dependencies, without resorting to the -( and -) options; by listing a library file a second time after the library or object code files that depends on that key library. The nm and/or ldd commands can be used to help determine external references and dependencies.

Additional Information

Using Intel® IPP Threaded Static Libraries
Building a Windows* Application Using Intel® IPP
Compiling and Linking with Microsoft* Visual C++* and Intel® C++ Compiler
Error LNK2001: Unresolved External Symbol _ipp*
How to Build an Intel IPP Application
Intel® IPP - Intel® IPP Linkage Models - Quick Reference Guide
Intel® IPP- Library Dependencies by Domain
Intel® IPP - Threading / OpenMP* FAQ

For more complete information about compiler optimizations, see our Optimization Notice.