How to locate source files for debugging
Overview
When you compile an application on one machine and debug it on another, winIDEA may not be able to find the source files because the paths stored in the symbol file point to the original build machine. This guide shows you how to tell winIDEA where the source files actually are.
Use this guide when:
My situation |
Go to |
|---|---|
The Symbols view shows grayed-out modules and I want winIDEA to figure out the path for me |
|
I already opened the correct source file in the Editor and want to link it to the symbol file |
|
I know both the original build path and the current path on this machine |
|
I don't know what path was recorded in the symbol file at compile time |
|
I want the workspace to work on any machine without reconfiguring paths |
|
winIDEA is locating the wrong source files after they were moved |
•Symbols window shows modules grayed out (source not found).
•You are sharing a winIDEA workspace between computers — for example, from a build machine to a debug machine.
•You moved or renamed the source directory after compiling.
Option 1: Locate files from the Symbols view
Use this option when winIDEA is already showing you that source files are missing (grayed Modules in the Symbols window).
1. Open View > Symbols.
2. Right-click a grayed module and select Goto Source.
3. Browse to the actual location of the clicked file and select it.
winIDEA will:
•Determine the correct path conversion.
•Adjust configuration in Debug > Configure Session > Switch to Full > Application > Directories.
•Attempt to locate remaining sources without interrupting a live session.
•Refresh the Symbols window and editor line-of-code (LoC) markers.
Result: The module is no longer grayed out in the Symbols view, and you can open and step through the source file in the Editor.
Option 2: Locate files from an open Editor document
Use this option when you have already opened the correct source file manually in the Editor and want to associate it with the symbol file.
1. Open the source file in the Editor.
1. Right-click in the Editor to open the context menu.
2. Select Associate to symbol file, then choose one of the presented paths.
These are the paths that are reported in the Symbols File. If multiple applications or symbol files contain a file with this name, all will be presented. Make sure to select the one(s) who actually contain this exact file.
winIDEA will:
•Determine the correct path conversion.
•Adjust configuration in Debug > Configure Session > Switch to Full > Application > Directories.
•Attempt to locate remaining sources without interrupting a live session.
•Refresh the Symbols view and editor LoC markers.
Result: The file is associated with the correct symbol file entry. The Symbols view and LoC markers update to reflect the resolved path.
Option 3: Configure paths manually — original path known
Use this option when you know where the source files were located on the build machine and where they are now on the debug machine.
For these examples we use:
•Source files location of a compiled application: C:\Project
•Source files location of a debugged application: L:\Mirror\Project
In the Directories page you can define source files if you know where the source files are located on both computers or if you don’t know the original path to the source files.
1. Go to Debug > Configure Session > Switch to Full > Application > Directories.
2. Enable Convert source file paths.
3. Replace the old path with the new path.Type into the field:
C:\Project=L:\Mirror\Project.
Result: winIDEA replaces C:\Project with L:\Mirror\Project when resolving source file paths. Files that were previously grayed out in the Symbols view should now resolve correctly.
Option 4: Configure paths manually — original path unknown
Use this option when you do not know the path that was recorded in the symbol file at compile time.
1. Perform a Download.
If no hardware is connected, you can use Demo mode to load the symbol file without a physical target.
2. Go to the View > Debug > Symbols Browser and select Modules.
3. Click one of the listed files.
The path stored in the symbol file appears below the file list. This is the original build path.
4. Compare this path to the actual path and identify the required replacement.
For example: the symbol file records C:\Project, but the files are now at L:\Mirror\Project.
5. Open Debug > Configure Session > Switch to Full > Application > Directories.
6. Enable Convert source file paths.
7. In the path conversion field, type the old path and the new path separated by =:
Type into the field
C:\Project=L:\Mirror\Project.
Result: winIDEA resolves the source paths using the conversion rule. The Symbols window updates and you can step through source code.
Option 5: Use relative paths to make the workspace configuration portable
You may specify the new path relative to the workspace file, when the workspace file is located in the same folder hierarchy.
If a winIDEA directory is created next to the sources the relative path from the workspace file in this case is ..\Project.
If you specify the relative path it will allow you to copy the entire L:\Mirror directory to any other location or PC and winIDEA will still locate the source code correctly.
Option 6: Reset source file associations
Use this option when winIDEA is locating the incorrect source files, for example, source files have been relocated elsewhere in the file system.
1. Open View > Symbols.
2. In the Symbols window, right-click the symbol file.
3. Select Reset Source File Associations.
winIDEA clears the previously configured associations for that symbol file. You can then re-locate the source files using any of the options above.
See also
