When you compile an application with debug information enabled, such as with
-g, the compiler records absolute source file paths in the ELF
debug information. The debugger uses these recorded paths to map program addresses
to source lines and to open the corresponding source files in the editor during a
debug session.
If the debugger cannot find the source files at the recorded paths, it cannot open the correct files or bind breakpoints correctly. This typically happens when you move the source tree after building the ELF, debug an application built on another machine, or debug across operating systems. Source code remap resolves this issue by mapping the original source paths recorded in the ELF to the current local paths where the same source files exist.
When to use Source Code Remap
Use source code remap when the source paths recorded in the ELF do not exist on your system. Common scenarios include debugging an ELF built on a different machine, debugging a pre‑built image without rebuilding sources, moving the source tree after the build, or debugging when the Call Stack view shows file paths that are not valid on your system.
Important Notes
The destination source files must match the sources used to build the ELF. If the sources differ, the debugger can display incorrect line mappings or bind breakpoints to unexpected locations. If the build records multiple source roots, you must add one mapping for each distinct source root.
How Source Code Remap Works
During debugging, the debugger reads the original source file paths stored in the ELF debug information. For each path map you define, the debugger replaces the recorded path prefix with the destination path prefix that you provide. The debugger then loads the source files from the destination path when resolving stack frames or displaying source code.
Add a path map in the Vitis Unified IDE
- Go to debug launch configuration and expand the Path
Map.
- Click + to add source
map.
- SOURCE: Refers to the original path of the source file. You can hover over the source file name in the CALL STACK view to see this path.
- DESTINATION: The current file path of the source code.
- Click OK and start debug.
Tip: Hover over a source file name in the Call Statck view to see the source path recorded in the ELF.
Example Mapping
If the ELF was built with sources under C:\testapp, use
C:\testapp as the SOURCE path. If the same sources now exist
under /scratch/source, use /scratch/source as the
DESTINATION path. This mapping directs the debugger to load source files from
/scratch/source.
Verify the Mapping
Stop execution at a breakpoint and open the Call Stack view. Select a stack frame and confirm that the editor opens the correct local source file. If some files still fail to resolve, add additional mappings for other source roots recorded during the build.
Troubleshooting
If breakpoints do not bind after adding a path map, the destination sources likely do not match the sources used to build the ELF. If some files resolve but others do not, the build likely recorded multiple source roots and requires multiple mappings. If the debugger still cannot locate source files, verify that the SOURCE path matches the recorded path prefix in the ELF.