6. Source Navigation

6.1 Support for Cross References
6.2 The Navigate Menu
6.3 Source Navigation Contextual Menus

6.1 Support for Cross References

GPS provides cross-references for most of the entities defined in your application, as well as some advanced browsers like a call graph. For this to work, it needs some help from external tools, specific to each of the supported languages.

Ada

The GNAT compiler itself is used to generate the cross-references information. This means that you need to compile your application to get access to this feature or the various graphs. If your sources have been modified, you should recompile the modified files.

If you need to navigate through sources that are not fully compilable (e.g after heavy modifications, or while porting an application), GNAT can still generate partial information if you specify the -gnatQ compilation option. Along with the -k option of gnatmake, it is then possible to generate as much relevant information as possible for a complete set of non compilable sources.

There are a few special cases where GPS can not find the external file (called `ALI file') that contains the cross-reference information. Most likely, this is either because you haven't compiled your sources yet, or because the source code has changed since the `ALI file' was generated.

It could also be that you haven't included in the project the object directories that contain the `ALI files'.

In addition, one special case can not be handled automatically. This is for separate units, whose file names have been crunched through the gnatkr command. To handle this, you should force GPS to parse all the `ALI files' in the appropriate object directory. This is done by right-clicking on the object directory in the explorer (left-side panel on the main window), and selecting the menu "Parse all xref information".

C/C++

To enable the navigation features for C and C++ source files, you need to first generate a database of symbol references, by going through the menu Build->Recompute C/C++ Xref info. Messages in the console window will indicate the state of the processing. Due to the nature of these languages, in order to provide accurate cross references, GPS needs to generate the database in two phases: a first pass parses all the files that have been modified since the previous parsing, and a second pass generates global cross references by analyzing the complete database. It is thus expected that for large projects, this phase can take a significant amount of CPU to proceed.

In some cases, GPS won't be able to determine the exact function involved in a cross reference. This will typically occur for overloaded functions, or if multiple functions with the same name, but under different #ifdef sections, are defined. In this case, GPS will display a dialog listing the possible choices to resolve the ambiguity.

In addition, the C/C++ parser has the following limitations: name spaces are currently ignored (no specific processing is done for name spaces); no attempt is made to process the macros and other preprocessor defines. Macros are considered as special entities, so it is possible to navigate from a macro use to its definition, but the macro content is ignored, which means for example that function calls made through macros won't be detected.

6.2 The Navigate Menu

Find/Replace...

Open the find and replace dialog. See section 8. Searching and Replacing.

Find Next

Find next occurrence of the current search. See section 8. Searching and Replacing.

Find Previous

Find previous occurrence of the current search. See section 8. Searching and Replacing.

Goto Declaration

Go to the declaration/spec of the current entity. The current entity is determined by the word located around the cursor. This item is also accessible through the editor's contextual menu directly. This capability requires support for cross references.

Goto Body

Go to the body/implementation of the current entity. This item is also accessible through the editor's contextual menu directly. This capability requires support for cross references.

Goto Line...

Open a dialog where you can type a line number, in order to jump to a specific location in the current source editor.

Goto File Spec<->Body

Open the corresponding spec file if the current edited file is a body file, or body file otherwise. This option is only available for the Ada language. This item is also accessible through the editor's contextual menu

Find All References

Find all the references to the current entity in the project. The search is based on the semantic information extracted from the sources, this is not a simple text search. The result of the search is displayed in the location window, see 2.8 The Locations Tree.

This capability requires support for cross references. This item is also accessible through the editor's contextual menu

Previous Tag

Go to previous tag/location. See section 2.8 The Locations Tree.

Next Tag

Go to next tag/location. See section 2.8 The Locations Tree.

6.3 Source Navigation Contextual Menus

This contextual menu is available from any source editor by right-clicking. If you right click over an entity, or first select text, the contextual menu will apply to this selection or entity.

Goto declaration of entity

Go to the declaration/spec of entity. The current entity is determined by the word located around the cursor or by the current selection if any. This capability requires support for cross references.

Goto body of entity

Go to the body/implementation of entity. This capability requires support for cross references.

Goto file spec/body

Open the corresponding spec file if the current edited file is a body file, or body file otherwise. This option is only available for the Ada language.

References

This item gives access to different capabilities related to listing or displaying references to the current entity or selection.

Entity calls

Open or raise the call graph browser on the specified entity and display all the functions called by entity. See section 10.2 Call Graph.

Entity is called by

Open or raise the call graph browser on the specified entity and display all the functions calling entity. See section 10.2 Call Graph.

Note that this capability requires a global look up in the project cross references, which may take a significant amount of time the first time. After a global look up, information is cached in memory, so that further global queries will be faster.

Find all references to entity

See Find All References.

Find all local references to entity

Find all references to entity in the current file (or in the current top level unit for Ada sources). See Find All References for more details.

Find all writes to entity

Find all writes to an entity. This is a search global to the project. See Find All References for more details.

Find all reads of entity

Find all non write accesses to an entity. This is a search global to the project. See Find All References for more details.