About Using the Intel Advisor Annotation Definitions Files

Intel® Advisor provides macro or routine definitions that enable use of its annotations for each language:

  • For C/C++, the advisor-annotate.h header file defines macros that begin with ANNOTATE_, so you can use annotations such as ANNOTATE_SITE_BEGIN();.

  • For Fortran, the advisor_annotate module declares subroutines starting with annotate_, so you can call annotations such as annotate_site_begin().

  • For C# on Windows systems, the AdvisorAnnotate header declares an Annotate class containing member routines, so you can use annotations such as Annotate.SiteBegin();.

Referencing the Annotation Definitions from Your Source Files

Before you add Intel Advisor annotations into your source files, you need to reference the definitions for the Intel Advisor annotations:

  • For C/C++, insert: #include "advisor-annotate.h" or #include <advisor-annotate.h> (see the help topic Including the Annotations Header File in C/C++ Sources).

  • For Fortran, insert: use advisor_annotate

  • For C#, insert: using AdvisorAnnotate;

Where to Add USE Statements in Fortran Programs

Fortran does not have file scope declarations, so the USE statement needs to be inside the subroutine, function or main program where the annotation(s) appear. For example:

program F_example

! The main program does not contain annotations, do not add use advisor_annotate here!
! some code . . .
subroutine F_sub 
! This subroutine contains annotations, so add the use advisor_annotate statement
use advisor_annotate
! some code . . .
! add Intel Advisor site and task annotations around compute intensive code
! For example, begin a parallel site: call annotate_site_begin(site1) 
end subroutine F_sub
! some code . . .
end program F_example

If the call is in a module procedure, the USE statement can be at the module level. For more details about placing USE statements, see your Fortran compiler documentation.

Specifying Build Settings

Specific build settings are needed for each language. Certain build settings are needed for each module that contains Intel Advisor annotations, such as specifying the directory where the annotations definitions are located. For C/C++ and Fortran applications, other build (compiler and linker) settings are needed for all modules in an application, such as full debug information. Read the Build Settings... topics by clicking the links below under See Also for your language.

Redistributing the Annotations Definition File(s)

You only need annotations in your code when you are using the Intel Advisor Suitability and Correctness tools to predict your serial program's parallel behavior. Before you distribute your application, you will typically replace these annotations when you add the parallel framework code. However, because the annotations do not change how your applications runs unless you use Intel Advisor tools, you can distribute your application with the annotations still present.

For information about redistributing the annotation definition files, see the installed End User License Agreement (EULA.rtf ) and the redist.txt file installed in the Intel Advisor ...\documentation\<locale> directory.

Special Considerations for C/C++ Applications

With C/C++ programs:

  • If your program encounters errors when you include the advisor-annotate.h file, see the help topic Handling Compilation Issues that Appear After Adding advisor-annotate.h. In rare cases, you may want to consider using a project- or solution-specific copy of advisor-annotate.h to allow you to modify it.

    If you do need to modify this file, you can add a copy of advisor-annotate.h that you can modify for a specific project or solution. If the Intel Advisor version of advisor-annotate.h changes, you will need to update your copies of the file. See the help topic Adding the Annotations Include File to Your Visual Studio Project.

    If you do not need to modify this file, you can reference the same installed advisor-annotate.h from multiple projects or solutions as a read-only file. If you use the Intel Advisor environment variable and the version of Intel Advisor advisor-annotate.h changes, you only need to change this reference if the environment variable name changes, such as for a major version. Thus, using a read-only version can minimize future maintenance.

  • Since the annotations do not change the values computed by your program, you can change the expansions of the macro, or suppress expansion altogether, as described in the help topic Controlling the Expansions in advisor-annotate.h.