2.3.75. INCLUDE

Executes RealView Debugger CLI commands stored in the specified script file.


INCLUDE [/D] [/S] filename



Steps through the CLI commands in the script file. Before each command is executed, it is displayed in the Output view, together with the following prompt:

Press ENTER to execute the line...

If a DEFINE command is encountered, then the macro definition is executed completely. That is, the macro code is not stepped.


Commands from included script files are stepped only if you add the /D qualifier to each INCLUDE command used in your main script.


Stops the commands in the INCLUDE file being echoed to the display. However, the commands are still added to the command history list.


If your main script file includes additional script files using the /D qualifier, then the commands in the additional script files are still stepped.


Specifies the command file to be read. Quotation marks are optional, but see Rules for specifying filenames in the INCLUDE command for details on how to specify filenames that include a path.


If you specify both the /D and /S qualifiers, then the behavior depends on the order that you specify them.


The INCLUDE command executes a group of commands stored in the specified file as though they were entered from the keyboard. By default, commands in the file are executed until the end of the file is reached or an error occurs. However, you can step through the commands if you want to debug the INCLUDE file.

When you run a command script, RealView Debugger sets the RVDEBUG_INCLUDE_BASE environment variable to the location of that command script. Therefore, you can use this environment variable in your command script if required. The environment variable definition exists only for the current debugging session, and changes for each command script that you run.


The environment variable does not change if the INCLUDE command is used in another command script.

If an error occurs, the debugger behaves as specified by the ERROR command. If a filename extension is not specified, the debugger automatically appends the extension .inc.


If you want to include a batch file when a target is running, you must first enter the wait=off command, then include the batch file:

> wait=off
> include myfile.inc

Your batch file can still include the wait=on command, if required.

The INCLUDE command is normally used to perform repetitive or complex initializations, such as:

  • loading and running programs, setting up breakpoints and initial variable definitions

  • creating debugger aliases and macros, perhaps for use in later debugging


    The DEFINE command, used to create macros, can only be used in an INCLUDE file.

  • running test suites.

You can configure the debugger to load a given INCLUDE file automatically when a target connection is made using the Commands setting of the Advanced_Information block for your target.

You can also run script files using the -inc argument to RealView Debugger itself.

The INCLUDE command runs asynchronously.

Restrictions on the use of INCLUDE

The INCLUDE command is not allowed in a macro.

Rules for specifying filenames in the INCLUDE command

Follow these rules when specifying a filename:

  • If the filename consists of only alphanumeric characters, slashes, or a period, but the filename does not start with a slash, then you do not have to use quotation marks. For example, includes/file.

  • Filenames with a leading slash must be in double quotation marks, for example "/file".

  • Filenames containing a backslash must be in single quotation marks. For example '\file' or 'c:\myfiles\file'.

    Alternatively, you can escape each backslash and use double quotation marks. For example, "c:\\myfiles\\file".

  • You can use environment variables to specify paths to a file. For example, if PATHROOT=C:\MYFILES and PATHTEST=TEST1:


    You can include:

    • the filename as part of the second environment variable, and then specify '$PATHROOT\$PATHTEST'.

    • the path separator in the environment variable, and then specify '$PATHROOT$PATHTEST'.


The following example shows how to use INCLUDE:

INCLUDE "startup.inc"

Read the file startup.inc in the current directory and interpret the contents as RealView Debugger commands. The file startup.inc might contain:

; startup.inc 12/12/00
; Author: J.Doe
alias sf*ile =dtfile ;99
alias dub =dump /b
vopen 99

See also

Copyright © 2002-2011 ARM. All rights reserved.ARM DUI 0175N