Table of Contents
Basic concepts and general configuration
This chapter explains basic concepts of WinGDB and general configuration
options that should be set first. You should familiarize with these before
starting working with WinGDB.
Quick and project mode
WinGDB allows two general schemes of operation:
Quick mode which involves no Visual Studio project usage. You can launch
a debug session with parameters entered ad hoc in a configuration dialog.
WinGDB remembers these parameters in the system registry, so that you may launch
the session with same parameters again. This mode also supports simple edition
and creation of remote files, as well as starting the build. It allows you to
make quick fixes to the code and test them immediately.
This section describes the quick mode in more detail.
Project mode which integrates with Visual Studio project mechanism. You can
configure any standard Visual C++ project for WinGDB. In this mode, WinGDB adds
its configuration options to existing Visual Studio options. The options are stored in
suo (solution options) or project (vcproj or vcxproj) files.
Different options values can be specified for each configuration.
You can find more information here.
GDB can be used in many kinds of environments: Linux systems,
Windows development under MinGW or Cygwin, mobile/embedded platforms,
embedded devices and many more. WinGDB supports continuously growing
number of these configurations. Due to various differences in GDB
behavior and usage between the configurations, WinGDB needs to know
in advance the type of development target. The types differ
mainly in what machine performs the role of the build host
and debugging target, and how to interact with them.
There can be three kinds of machines involved in debugging single program.
These are the logical roles rather than physical machines. Several roles
may be performed by a single machine depending on the mode (and typically are).
Debugging host: the machine where GDB itself is being run.
Debugging target: the machine where the debugged program is being run.
Build host: the machine where the sources reside and the program is being built.
These machines can run different operating systems. For example, for many
types of embedded systems, GDB is being run under Windows (as well
as GCC in cross-compile mode), but the program is debugged under
Linux. On the other hand, when debugging Linux applications, GDB and
debugged program are often both executed on the same Linux machine and WinGDB
uses SSH connection to communicate with GDB.
Supported target types
Current version of WinGDB supports the following target types:
Remote Linux: GDB and debugged program runs on the same remote Linux
machine. WinGDB connects to the machine through SSH. This
is typical mode for Linux application development. Also the build is performed on
a Linux machine -- it can be the same computer as the debugging host,
or dfferent one.
Indirect Linux: GDB runs on remote Linux machine. WinGDB connects
to the machine through SSH. The debugged program runs on
another Linux machine and GDB connects to it through its remote debugging
protocol and special program called gdbserver. This adds one level
of indirection to the Remote Linux mode. Again,
the build can be done on one of the above machines or on separate
one. There can be maximum three machines involved in the process.
This mode is useful in some advanced debugging scenarios.
Native Windows: GDB runs on the Windows machine. WinGDB communicates
with it directly. Also the debugged program runs and is being built locally.
All three roles mentioned above are being performed by the local
computer running Windows. This is typical for Windows development
using MinGW or Cygwin tools.
Embedded Linux: GDB runs on the Windows machine. WinGDB communicates
with it directly. The debugged program is also being built locally by
a cross-compiling toolchain,
but it runs on a remote Linux machine (typically an embedded system).
So there are two machines involved. The local computer performs the role
of debugging and build host. The debugging target
is connected by some means (usually TCP through network or USB tunneling) and
also runs gdbserver to control the debugged process.
Embedded device: GDB runs on the Windows machine. WinGDB communicates
with it directly. The debugged program is also being built locally
by a cross-compiling toolchain. However it runs on an embedded device without
operating system. This
differs from the Embedded Linux mode, as WinGDB does not assume
any access to the target device nor existence of any OS-related
concepts, like processes or shared libraries. This scenario is typical
for low-level OCD debugging over JTAG.
General settings page
The General settings page is present when configuring most
of WinGDB debugging functions: launching proceses, attaching, examining
core dumps. It's also the first one in the project settings.
The page contains a target type selector and fields to enter
login information for three machine roles described above.
Depending on target type, some of the fields may by grayed out
when the corresponding machine is assumed to be local computer.
Some settings are required for some target types. The following table
||Same as debug host
||Optional (required for some functions)
For the Embedded device type of target, there is one more fundamental
option, the Target specification located on the Target options
Here you specify how to connect to the target device, in the format of GDB target
command. You can find more information on development for embedded devices
in this section.
Login specification strings format
WinGDB has simple unified format for specification strings for develoment machines.
You enter strings in this format into fields like Debug host login in the
Properties and similar dialogs. The string has several variants, depending
on what kind of machine is the target of the connection.
Remote Linux/Unix machine connected through SSH
The format is:
The user name is mandatory. The password (with ':' character) is optional.
If you do not specify the password, WinGDB will ask you for it when attempting
connection. The host address may be an IP address or a resolvable host name.
The port (with ':' character) is also optional. Default port 22 is assumed
if not specified explicitly.
Local machine (not using Cygwin)
The string is just a single word:
You can specify this type when using the local machine. Usually this is
not necessary, as WinGDB knows for which target types local or remote
machine would be used. In such cases, the login fields may be grayed out
when only local machine is allowed. It is very unlikely that you might
ever have to enter local manually.
Local machine (using Cygwin)
The string is just a single word:
You can specify this type when using the local machine with Cygwin.
WinGDB uses this type internally to enable some Cygwin-specific
path translations. Same remarks apply as with local
Environment settings page
The Environment settings page contains some additional settings
related to environment in which WinGDB runs.
Debugger path: allows to specify the debugger path for current project
and configuration. You can also set the Default value, which means the path will
be taken from global preferences.
Build toolchain path: allows to specify the path to build tools
(compiler, linker, etc.) for current project and configuration. You can also
set the Default value, which means the path will be taken from global preferences.
Intercept standard IDE commands: if enabled, WinGDB will override standard Visual Studio
build commands (from Build menu). These commands will launch WinGDB build instead of
standard Visual Studio build process. When disabled, WinGDB will not override these commands
and you will have to use options from WinGDB menu. This setting is especially useful when
you have separate configurations for native (Visual Studio) and remote (WinGDB) development
on single project. If you enable the override only in the second configuration, the Build
command will start proper build process according to the current configuration. Also note that
the Intercept setting on this page affects only project-scoped build commands. To
enable of intercepting the Build solution command, right-click on the solution node
in Solution Explorer, then choose WinGDB / Properties and the Environment
page from there.
WinGDB provides a toolbar in Visual Studio for quick access to most frequently
used options. In order to show or hide the toolbar, open the Customize
dialog in Visual Studio, click Toolbars tab and select or deselect
the WinGDB row.
All WinGDB options (except those from WinGDB/Preferences) can be set per configuration
and platform. You can have multiple configurations and target multiple platforms,
all with different settings. It is described in detail in
this section of the manual.
Configuration guidelines for available target types
The following chapters describe how to configure WinGDB for each target type. They
assume using the project mode, but the options and their meaning is the
same for the quick mode.
Table of Contents
Copyright (C) 2008-2019 SOFT-ERG. All rights reserved.