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.

Development targets

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.

Development machines

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 summarizes it.

For the Embedded device type of target, there is one more fundamental option, the Target specification located on the Target options page:

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:

    user_name[:password]@host_address[:port]

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:

    local

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:

    cygwin

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 connections.

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 toolbar

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.

Multiplatform development

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.

Native Linux

Indirect Linux

Native Windows

Embedded Linux

Embedded device

Table of Contents