Documentation > Linux > VisualGDB Path Mapping

VisualGDB Path Mapping

Path mapping is a process of converting file paths between the Windows style and various Unix-based styles utilized by GDB. In most of the cases VisualGDB will select the appropriate path mapping automatically, however you can always modify it manually. This page describes the path mapping editor used to specify path mapping.

Toolchain types

The first thing to consider before changing the path mapping is do determine whether you are using a local toolchain or a remote toolchain:

  • A local toolchain means that you are running gdb.exe (e.g. from Cygwin or MinGW) on the local Windows machine. Such toolchain has direct access to the files on the local machine, however might require a special syntax for specifying the paths. A path c:\dir\file.cpp represented using various path styles looks as follows:
    • In native cygwin style: /cygdrive/c/dir/file.cpp
    • In native MinGW style: /c/dir/file.cpp
    • In compatible style: c:/dir/file.cpp
  • A remote toolchain means that GDB is running on a remote Linux machine and uses the files on the remote Linux machine. VisualGDB will automatically translate the paths to the files that it copies, however if you have copied some files or directories manually, you will need to edit the file mapping manually.

Path mapping editor

The path mapping editor allows customizing the following settings:

  1. GDB path style specifies which path style will be used by VisualGDB when setting breakpoints and how the paths reported by GDB are treated:
    • Most Cygwin- and MinGW-based toolchains support the c:/dir/file.cpp syntax. However, if you are using an older toolchain and experience problems setting breakpoints, please try other path styles.
    • When parsing GDB output and deriving the Windows file path, VisualGDB will always correctly recognize c:/dir/file.cpp and c:\dir\file.cpp style. It will also recognize the /cygdrive/c/dir/file.cpp style when any cygwin-based style is selected and will recognize /c/dir/file.cpp when any MinGW-based style is selected.
  2. Additional source path mappings allow specifying how given paths are transformed. E.g. if you map /usr/include to c:\cache\usr\include, then /usr/include/stdio.h will be mapped to c:\cache\usr\include\stdio.h. This is useful if you create local copies of some directories on the Linux machine. Note that the source path mappings override the GDB path style (i.e. if a match is found among them, the default style-based transformation will not be applied).
  3. Default directories for paths with no mapping specify the last fallback mapping VisualGDB performs if it does not recognize a Cygwin/MinGW path and does not find a match among the source path mappings:
    • Directory for absolute paths allows providing a default directory for the absolute paths that have no mapping entries. E.g. you can share the root directory (‘/’) using the samba server, connect it to a network drive (e.g. R:\) and specify R:\ as the root for the absolute paths.
    • Directory for relative paths allows specifying a Windows directory that will be used to search for files when GDB provides no full path. E.g. if c:\local is specified here and GDB reports subdir/file.cpp, VisualGDB will recognize it as c:\local\subdir\file.cpp.

Automatic entries

When you debug a project, VisualGDB will use the following path mappings additionally to the ones specified in the properties dialog:

  1. Each directory transferred by VisualGDB as a part of build process will be accounted automatically.
  2. All cached include directories will be accounted.
  3. All entries from dependent projects will be imported.

Automatic file downloading

Note that if you are debugging a remote Linux machine and VisualGDB fails to find a mapping for a file reported by GDB, it will try to download the file to a local cache automatically. You can read more about it on this page.