Documentation > Linux > Linux Project Overview

Linux Project Overview

This document explains how building and debugging Linux applications works with VisualGDB: what tools are involved, how they communicate and what can be customized.

If you are looking for a step-by-step guide on building Linux applications with VisualGDB, read this tutorial.

Building and debugging Linux applications with VisualGDB can be done in 3 different ways:

  1. Building the code directly on the target (i.e. Linux machine).
  2. Using a Windows-based cross-toolchain built for a specific Linux target.
  3. Using a cross-toolchain running on one Linux machine to target another Linux machine.

Most of the Linux-based setups require the Linux machine to be accessible over SSH. If your Linux machine is missing the SSH server, you can use the VisualGDB Custom Target API to create a target-specific plugin for communicating with it.

Directly Built Projects

The easiest way to get started it to build the code directly on your target machine. This is the default mode and it is recommended for most setups, unless the target is considerably slower than your Windows machine. It can be enabled by selecting “Build the project under Linux over network” in the VisualGDB Linux Project Wizard:In this mode VisualGDB will automatically launch build and debug tools (e.g. gcc/gdb) on the Linux target as needed, and will automatically take care of synchronizing the sources between the Windows and the Linux side. The target machine would need to have the following tools installed:

  • GCC/C++
  • GDB
  • GNU Make

When building the code on the target, VisualGDB will automatically synchronize the source files between the Windows machine and the Linux machine where the build tools will be running. You can use one of the following file synchronization methods:

  1. Store all files on the Windows machine and upload the modified files to Linux during builds.
  2. Automatically share a Windows folder using SMB and mount it from Linux.
  3. Share a Linux directory over SMB and access it from Windows.

If you are using the Advanced CMake project subsystem, you also have the option of accessing the files directly on the Linux machine via SSH.

Cross-Compiled Projects

If the target is too slow to build the code, you can use a Windows-based cross-toolchain instead. A cross-toolchain is a special build of GCC, GDB and other tools that run on your x86/x64 computer, and produce the code for an embedded board (typically ARM-based). You can configure VisualGDB to use a cross-compiler in the VisualGDB Linux Project Wizard as shown below:Note that the cross-compiler must exactly match the target and the specific Linux distro you are using. You can read more about Linux cross-toolchains shipped with VisualGDB on this page.

For most embedded boards, a cross-toolchain would be provided by the board vendor. If your board vendor does not provide a Windows-based cross-toolchain, they may still provide a Linux-based toolchain. If this is the case, you can easily import it into VisualGDB and still manage your development from the Windows machine:See our Linux cross-compiler tutorial for detailed step-by-step instructions for this case.

Source File Synchronization and Mapping

If you decide to build the code on a Linux machine, VisualGDB will automatically upload the modified files before building the project. You can use  Project Settings page of VisualGDB Project Properties to fine-tune the exact files that will be uploaded, and also what will be considered a changed file:Normally, VisualGDB will remember the timestamps of the files uploaded to the Linux machine, and will compare the files against them next time. This makes the file uploading extremely fast, since VisualGDB can detect the modified files without contacting the target. However, you can also configure it to explicitly compare the local files against the target files, or to re-upload everything each time.

The file uploads are performed using the highly optimized SysprogsSync engine, that fully supports Linux symlinks, special files, and runs extremely fast.

If your project includes pre-built libraries with Linux source paths that don’t make sense on the Windows machine, you can use the Path Mapping page of VisualGDB Project Properties to create manual mapping rules between the Linux source paths and Windows source paths:Path mapping rules will not initiate any file transfers, but will help VisualGDB locate the sources on the Windows machine when GDB reports one of the related paths.

IntelliSense Setup and Source Cache

VisualGDB automatically determines the include directories and preprocessor macros used by your compiler and configures IntelliSense based on them. For projects built on the Linux machines, VisualGDB will automatically cache the header directories under %LOCALAPPDATA%\VisualGDB\RemoteSourceCache so that IntelliSense can find them. You can read more about source cache on this page.

Further Reading

VisualGDB is integrated with many Linux tools and provides convenient GUI for managing them from Visual Studio. You can read more about it in the following tutorials: