Compile and Link with ITT API

Step 1: Configure Your Build System

Before instrumenting your application with ITT API, configure your build system to establish access to the headers and libraries of the API:

• Add <ittapi_dir>\include to your INCLUDE path

• Add <ittapi_dir>\build_<target_platform>\<target_bits>\bin to your LIBRARIES path

Step 2: Include the ITT API Header/Module in Your Application

C/C++ Applications

For every source file that you want to instrument, add the following #include statements:

#include <ittnotify.h>

The ittnotify.h header contains definitions for ITT API routines and important macros that provide the correct logic to invoke the API from your application.

When tracing is disabled, The ITT API incur almost zero overhead. To achieve completely zero overhead, you can compile out all ITT API calls from your application. To do this, prior to including the ittnotify.h file, define the INTEL_NO_ITTNOTIFY_API macro in your project at compile time. You can do this from the compiler command line or in your source file.

Fortran Applications

Add the ITTNOTIFY module to your source files. Use the following source line:

USE ITTNOTIFY

Step 3: Insert ITT Notifications in Your Application

To insert ITT notifications in your application, use:

Language	Notification	Example
C/C++	__itt_*	__itt_pause();
Fortran	ITT_*	CALL ITT_PAUSE()

To learn more, open:

• Instrumenting Your Application

• ITT API Reference

Step 4: Link the libittnotify Static Library to Your Application

Once you finish inserting ITT notifications in your application, the next step is to link the libittnotify static library. This library is libittnotify.a in Linux* and FreeBSD* systems and libittnotify.lib in Windows* systems.

If you have enabled tracing, the static library loads the dynamic collector of the ITT API data and forwards to the collector instrumentation data from the ITT API.

If you have disabled tracing, the static library ignores ITT API calls, resulting in near-zero instrumentation overhead.

Step 5: Load the Dynamic Library

After you instrument your application and link the static library, you must load the dynamic library of the ITT API to your application. To do this, depending on your system architecture, set the INTEL_LIBITTNOTIFY32 or the INTEL_LIBITTNOTIFY64 environment variable.

Windows OS:

set INTEL_LIBITTNOTIFY32=<install-dir>\bin32\runtime\ittnotify_collector.dll
set INTEL_LIBITTNOTIFY64=<install-dir>\bin64\runtime\ittnotify_collector.dll

Linux OS:

export INTEL_LIBITTNOTIFY32=<install-dir>/lib32/runtime/libittnotify_collector.so
export INTEL_LIBITTNOTIFY64=<install-dir>/lib64/runtime/libittnotify_collector.so

FreeBSD OS:

setenv INTEL_LIBITTNOTIFY64=<target-package>/lib64/runtime/libittnotify_collector.so

Additional Information: Unicode Support

All API functions that take parameters of type __itt_char follow the Windows OS Unicode convention.

When compilation happens on a Windows system, if the UNICODE macro is defined, __itt_char is set to wchar_t. If the UNICODE macro is not defined, __itt_char is set to char.

The actual function names are suffixed with A for the ASCII APIs and W for the Unicode APIs. Both types of functions are defined in the DLL that implements the API.

Strings that contain only ASCII characters are internally equivalent for both the Unicode and ASCII API versions. For example, the following strings are equivalent:

__itt_sync_createA( addr, "OpenMP Scheduler", "Critical Section", 0);
__itt_sync_createW( addr, L"OpenMP Scheduler", L"Critical Section", 0);