Intel® Advisor User Guide

ID 766448
Date 3/22/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

advisor Command Line Interface Reference

This reference section describes the CLI actions and options used in the command syntax: advisor <--action> [--action-options] [--global-options] [[--] target [target options]].

The main advantage of using the Intel® Advisor command line interface, advisor, instead of the GUI is you can collect data as part of an automated or background task, and then view the result in a command line interface (CLI) report or in the GUI at your convenience.

Prerequisite: Set Intel® Advisor environment variables to start using the command line interface.

TIP:

You can generate command lines from Intel® Advisor for selected configuration. In the Analysis Workflow pane:

  • To generate a set of commands for the whole perspective, click .
  • To generate a command for a specific analysis, expand the analysis you want to get a command for and click .

advisor Command Syntax

The advisor command syntax is:

advisor <--action> [--action-options] [--global-options] [[--] target [target options]]

where:

advisor

The name of the Intel® Advisor command line tool.

<--action>

The action to perform, such as collect or report. Each command has exactly one action. For example, you cannot use both the collect and report actions in the same command.

[--action-options]

Action options modify behavior specific to the action. You can have multiple action options per command. Using an action option that does not apply to the action results in a usage error.

[--global-options]

Global options modify behavior in the same manner for all actions. You can have multiple global options per action.

target

The target (application executable) to analyze.

[target-options]

Options that apply to the target.

Action option/Global option rules:

  • If opposing action options are used on the same command line the last specified action option applies.

  • An action option that is redundant or has no meaning in the context of the specified action is ignored.

  • Attempted use of an inappropriate action option that might lead to unexpected behavior returns a usage error

Syntax Alternatives

An action option or global option can be preceded by one or two dashes. This chapter uses one dash before the short form of an action option/global option, and two dashes before the long form of an action option/global option. For example: The following are equivalent:

advisor --help

advisor -help

An option-value pair can be separated by an equal sign (=) or by a space. This chapter uses an equal sign. For example: The following are equivalent:

advisor --report=survey

advisor --report survey

The target executable must be preceded by two dashes and a space. For example:

advisor --collect=survey -- ./myApplication

Some action options accept multiple arguments. Most of the time, you can pass these arguments in a comma-separated string (with no spaces), or by repeating the action option. For example: The following are equivalent.

advisor --collect=survey --project-dir=./advi_results --exclude-files=./src/foo,./src/bar -- ./myApplication

advisor --collect=survey --project-dir=./advi_results --exclude-files=./src/foo --exclude-files=./src/bar -- ./myApplication

Directories

Project Directory

By default, the project directory is your current working directory. Use the project-dir action option to write a result to a different directory. For example:

Survey the application for hotspots and write the result to the ./advi project directory.

advisor --collect=survey --project-dir=./advi_results --search-dir all:=./src -- ./myApplication

Generate a Survey report from the Survey result and write it to the ./advi project directory.

advisor --report=survey --project-dir=./advi_results --format=text --report-output=./out/survey.txt

Search Directory

Use the search-dir action option to specify the directories containing the source, symbol, and binary files that support analysis.

You can specify multiple search directories. For example:

advisor --collect=survey --project-dir=./advi_results --search-dir src:=./src1,./src2 -- ./myApplication

TIP:

Always specify your search directories when using collect action.

User Data Directory

Use the user-data-dir action option to write result files to a directory other than project-dir, such as a remote directory or simply another directory when there is not enough space in project-dir.

For example: Collect Suitability data and write the result to a remote directory.

advisor --collect=suitability --project-dir=./advi_results --user-data-dir=./remote_dir --search-dir src:=./src -- ./myApplication