4.5.1. Using include files

RealView Debugger enables you to use include files to enter commands and so carry out debugging tasks without user intervention. The commands are actioned as though they are being entered from the keyboard.

During your debugging session, you can create a log file of all the commands you enter. This file can then be used as the basis of a command file or a macro. By default, log files have the extension .log or .inc, but you can use any extension for writing.

Another log file, called the STDIOlog log file, enables you to keep a record of debuggee output only, that is messages from the target. This might be useful for controlling debugging by running scripts without using the RealView Debugger user interface. By default, these files have the extension .log, but you can use any extension for writing.

In addition to the log files, you can also create a journal of a debugging session. The session journal file you create contains all information including your commands, RealView Debugger output and any messages displayed in the Output pane. By default, journal files have the extension .jou, but you can use any extension for writing.

In summary:

The following sections describe how to manage your debugging session using include files such as log or journal files:

Output buffering

In the current release of RealView Debugger, output to the log files and journal files is unbuffered. This means that all lines are immediately flushed to the specified file. To change this, so that output to a file is buffered, set the JOULOG_UNBUF environment variable.

Creating log and journal files

RealView Debugger writes log and journal output to a file saved in a specified location. If the file does not exist, RealView Debugger creates it. Where a file exists, RealView Debugger gives you the option to add new entries to the file, or to overwrite the current contents.

To create an output file, or to open an existing file for writing:

  1. Select File → New → Log File... to display the Select File to Log to dialog box where the file can be located.

  2. Specify the pathname of the new log file, or locate a file created previously, for example program_directory\home\my_user_name\my_log.log.

  3. Click Save to confirm the settings and close the dialog box.

  4. If the specified log file already exists, RealView Debugger displays the File Exists prompt.

    This gives you the options:

    • Yes appends new commands to those already saved in the file

    • No replaces, or overwrites, any commands already saved in the file

    • Cancel closes the prompt and discontinues the log file access.

    Click Yes or No as required.

Output is now recorded automatically in the specified file.

RealView Debugger shows that it is recording using the status display area at the bottom of the Code window, shown in Figure 4.3.

Figure 4.3. Output files recording

Output files recording
Using log and journal files at start-up

You can start RealView Debugger and open a log or journal file for writing. Do this from MS-DOS, or from a Command Prompt window, or create a desktop shortcut, for example:

rvdebug.exe -s "C:\myProjects\test_files\my_image_file.log”

If the file does not exist, RealView Debugger creates it. Where the file exists, RealView Debugger overwrites the current contents, without displaying a warning message.

When RealView Debugger starts to write to the log file, it records the filename as the first entry, for example:

;;;;LOG FILE: C:\myProjects\test_files\my_log.log

Closing log and journal files

If you are recording a log, or journal file and you try to start a new recording, RealView Debugger gives you the option to close the current file so that a new file can be used.

To close a log or journal file, select File → Close Logs/Journals.... This displays a list selection box, shown in Figure 4.4, where you can specify which file, or files, to close.

Figure 4.4. Close log and journal files selection box

Close log and journal files selection box

Each entry has an associated check box that is ticked by default. Select a check box to unselect a file. The list selection box contains:

OK

Click this button to close selected files and then close the selection box.

Cancel

Click this button to leave all files open and then close the selection box. Using Cancel ignores the status of any check boxes in the list.

Help

Click this button to display the online help for this selection box.

Use the File Editor pane, or a text editor of your choosing, to view the contents of your log and journal files. You can then edit the commands shown in a log file to create an include file for use as a command file or as a macro.

Including files

Use a text editor to create a file of commands that can then be submitted to RealView Debugger to control a debugging session. To use an include file:

  1. Select Debug → Include Commands from File..., from the Code window, to display the Select File to Include Commands from dialog box.

  2. Locate the file where your RealView Debugger commands are stored. By default, RealView Debugger looks for a .inc or a .log file.

  3. Click Open to load the file and execute the commands stored there.

You can also start RealView Debugger with an include file, for example:

rvdebug.exe -inc "C:\myProjects\test_files\my_cmds_file.inc”
Copyright © 2003, 2004 ARM Limited. All rights reserved.ARM DUI 0234B
Non-Confidential