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 the compiler
generated xref information, which means that you need to either compile
your project first before being able to navigate, or use the menu
Build->Recompute Xref info.
Similarly when your sources have been modified, you need to rebuild and
recompute xref information so that your changes are taken into account.
Here are language specific information about source navigation:
-gnatD or
-gnatx switches, in which case no cross reference information
will be available.
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".
-fdump-xref
switch. This means that you need to first add the -fdump-xref
switch to your project's switches for C and C++ sources, and 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.
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 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.
Note that GPS always loads all xref information for C and C++ sources in order to provide accurate source navigation, so this menu is mainly relevant for Ada sources.
A preference can be set to have GPS load the cross-information automatically on startup, See The Preferences Dialog.
GPS is able to provide some basic navigation support for Ada sources in the absence of information coming from the compiler. It uses a built-in Ada parser parsing the Ada files at startup and allowing navigation in simple cases.
In this mode, GPS is able to navigate to an entity body from the declaration, and to an entity declaration from the body. In case of other references, GPS will navigate to the declaration on simple cases, namely if the heuristics provide an information without ambiguity. In particular, it may not work with overloaded entities.
These heuristics are not used in global reference searching operations or call graphs.
Note that this parser is also used to provide the Ada outline view, code completion and entity view.