Next: The Navigate Menu, Up: Source Navigation
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.
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".
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.
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.