Table of Contents

Indirect Linux development using WinGDB

This chapter explains how to setup WinGDB for debugging and building programs on remote Linux machines, using additional gdbserver indirection. The sources are stored and built on remote side. This is more advanced scenario which can be used for development of server or desktop Linux applications. In most cases, the simpler Remote Linux mode is sufficient and recommended.

Create WinGDB project

One of possible options to start work with WinGDB is using a project template from the New Project dialog. Here you can choose from several project types: executable program, static library or shared library (shared libraries are not supported on some kinds of platforms).

This option creates the project and opens Project configuration wizard described below.

Create and configure standard Visual Studio project

You can also work with remote Linux using WinGDB without any special project type. Just use any C++ project type that Visual Studio offers, e.g. Console application. This facilitates multiplatform development. Your application can be compiled and run both under Windows and Linux. You can also use WinGDB for existing Windows project, e.g. for porting.

Prepare solution configuration

WinGDB works with Visual Studio solution configurations. After creating the project, it is recommended you review configurations that Visual Studio creates. By default, these are Debug and Release configurations. If you want only to work on single platform, you may configure WinGDB for these configurations. If you plan multiplatform development, please read remarks on multiple configurations and platforms here.

Choose configuration method

WinGDB offers two ways to configure a project:

The rest of this document covers the detailed configuration mode. You do not need to perform the steps described below while using the wizard, as it does them for you. It is however recommended to read the following sections and other documentation chapters, as they explain the Properties interface required to to utilise full capabilities of WinGDB. Some settings are also adjustable globally, using the Preferences dialog from main WinGDB menu.

Locate your debugger

To be able to debug with WinGDB, you must let it know the debugger location. To set that information, choose Preferences option from WinGDB menu. There is Default debugger location field in the preferences. You can enter full path to the debugger executable, or only the executable name. In the second case you have to configure your PATH variable on Windows host, so that the executable can be found. For Linux systems this name is usually just "gdb".

Alternatively you can specify the debugger path in project or solution properties (Debugger path setting on Environment tab). This will override the global setting described above. Thus, you can use a different debugger in different projects or configurations. To return to default debugger, reset the Properties setting to default value.

Basic configuration

The most important properties adjustable for a project or solution, are Target Type, Debug Host Login and Debug Target Login, located on the General tab.

Target type

WinGDB supports many possible scenarios of debugging with GDB. You have to select which one suits you. In this case, it will be "Linux indirect debugging (SSH+remote target)".

Debug Host Login

In order to connect to the remote machine where GDB runs, WinGDB needs to know connection details. You specify them in the following format:


Parts in brackets are optional. If you do not specify the port, default one equal to 22 will be assumed, If you do not specify the password, WinGDB will ask you for one later. You can specify either host name or IP address. You can find more information about supported authentication methods in this section.

Debug Target Login

This is the login information for the machine where debugged program runs. It is not required by WinGDB, but if present, it enables additional features: target file system browsing and automatic gdbserver launch (see below).

GDB server

In order to debug Linux programs indirectly you will need a special program called "gdbserver". It should be installed on the target machine. It usually comes with GDB.

You have to decide how do you want to start gdbserver. With WinGDB you have the following options:

Either automatically or manually, gdbserver can be started in one of three modes. You have to specify the mode in Server mode field:

This option should be properly set both in manual and automatic mode, since WinGDB must know it to properly interact with gdbserver.

The remaining options are specific to the automatic launch mode.

In the indirect mode, usually there is no sysroot set. Shared libraries are assumed to be identical on the debug host and the target. In that case, set Launch server from sysroot option to No. If you need sysroot functionality, please consult Embedded Linux chapter which explains how to configure it.

Mapping the source directories

Another important thing for remote development is to tell WinGDB which directories on the local side correspond to which ones on the remote side. It's called a source directory mapping. You can establish those mappings using the "Map source directories" option from WinGDB menu. It shows the Mapping Manager window.

As you can build/debug on many machines or user accounts, Mapping Manager allows you to set mappings separately for each machine you use. To add a machine, click "Add login" button, and enter login information in usual format.

Next, click "Add Mapping" button. It will show another window in which you enter actual mapping information. It consists of three components:

You can enter as many mappings as you need. Usually one mapping for entire solution will suffice, but if your sources structure does not match perfectly between Windows and Linux, you may need more.

Configuring the makefile generator

WinGDB includes a simple makefile generator. This generator automatically creates a makefile from current project. Generated makefiles can be used with standard GNU make. Other build systems are in plans. The generator is optional, you can write your makefile by hand if you wish, or use a build system which is currently not supported.

You can find more information about the makefile generator in this section.

Transferring the solution to remote machine

WinGDB offers the means to transfer solution files to the remote machine (and back). See this section for more details.

Compiling on remote machine

WinGDB has a simple mechanism to control compilation using "make" or any other build system. Although this option is called Remote build, it works both in remote and local mode. It can start any build command, however if you want to be able to locate errors and warning in the source code, the build command output must be compatible with standard make and gcc message format. For best results, use standard make build system.

You have to set some additional properties before using it. Right click on your project in Solution Explorer and open the Properties dialog. First, choose the General tab. Since you can build on different machine than the one you debug your program on, there exists a separate field to enter the build login information. You can also enter the same login as for debug.

Next, go to the Remote build tab. Here you can set the following properties:

If you click on solution instead of project, there will also be shown another tab, Remote solution build. On that tab there is a similar set of options, this time concernin the whole solution.

Apart from Remote solution build, there is also regular Remote build tab. On that tab you can set default settings for the projects, which can be then selectively overridden on any project settings page.

To start the build, choose Remote build option from WinGDB menu on any project or solution in Solution Explorer. You will see results in the console. When you click on an error or warning, the code editor will jump to appropriate place in the code.

You can also use Remote rebuild and Remote clean options to perform these alternative actions.

Program configuration

Executable paths

To launch a program in debug mode, WinGDB needs to know the full path of the program both on the host and the target. You specify the first one in the Executable path field on Debug tab, just as in other debugging modes.

The corresponding path on the target is entered into Executable on target field on Target tab.

Optional parameters

You can also set some optional parameters, like program arguments, additional environment variables, working directory. If you set "Stop in main()" option, the program will stop at the beginning of main() function. This option is added for convenience, as you can achieve the same effect by setting a function breakpoint in Visual Studio before starting the program.

Project-specific configuration

You can also set all above options per single project. Right-click on a project in Solution Explorer instead of the solution. There is also Properties option. This option activates exactly the same dialog as in case of the solution. The difference is, the solution-wide settings become defaults and you can override any of them by setting a new value.

Table of Contents

Copyright (C) 2008-2019 SOFT-ERG. All rights reserved.