Next: , Up: Source Navigation


6.1 Support for Cross-References

GPS provides cross-reference navigation for program entities, such as types, procedures, functions, variables, ..., defined in your application. The cross-reference support in GPS relies on language-specific tools as explained below.

Ada
The GNAT compiler is used to generate the cross-references information needed by GPS. This means that you must compile your application before you browse through the cross-references or view various graphs in GPS. If sources have been modified, you should recompile the modified files.

If you need to navigate through sources that do not compile (e.g after modifications, or while porting an application), GNAT can still generate partial cross-reference 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 your non compilable sources.

There are a few special cases where GPS cannot 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 cannot 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 project view (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: namespaces are currently ignored (no specific processing is done for namespaces); minimal support for templates; 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.1.1 Loading xref info in memory

The cross-reference information, as mentioned above, is generated either by the compiler when you recompile your sources, or explicitly when you select the menu Build->Recompute C/C++ Xref info.

This information will be loaded in memory automatically by GPS when it needs it, and as little as possible, to limit the memory footprint. However, this means that some operations, for instance searching for all the references to a global entity, will need to parse most, if not all, of the cross-reference information. This will slow done the search the first time (and then the information is in memory and the search is fast, unless the cross-reference information has been regenerated on the disk).

You can select the menu Build->Load xref info in memory to force GPS to load all the available information immediately in memory. This will speed up future queries.

This menu can also be used in some cases for C and C++. Since these languages have no notion of package, the declaration of a subprogram and its actual implementation can be in two different files with vastly different names. GPS in such case will not be able to display a Goto body contextual menu unless it has already parsed both files. A way to get fully accurate cross-reference information is thus to load all information into memory before attempting any navigation operation.

A special case has been put in place so that both file.h and file.cpp are loaded together in memory. This means that in the general case where an entity is defined in foo.h and implemented in foo.cpp, nothing special needs to be done. The specific file extensions depend on the naming scheme specified in your project.

A preference can be set to have GPS load the cross-information automatically on startup, See The Preferences Dialog.