Enter search terms or a module, class or function name.
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 compile your project first before being able to navigate. 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:
The GNAT compiler is used to generate the cross-references information needed by GPS by default, unless you are using the -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.
The GCC C and C++ compilers that come with GNAT need to be used to generate the cross-references information needed by GPS, via the -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.
GPS is able to provide some basic navigation support for Ada, C and C++ sources in the absence of information coming from the compiler. It uses a built-in parser, parsing the files at startup and everytime they are modified. This provides basic 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.
GPS parses the cross-reference information generated by the compiler (the .ali and .gli files into an sqlite database. This database can become quite big, and should preferrably be on a fast local disk.
By default, GPS will place this database in the object directory of the root project that is currently loaded. You can override this choice by adding an attribute Xref_Database in the IDE package of your project file. This attribute can be either an absolute path, or a path relative to the location of the project file itself
We recommend that this path be specific to each user, and to each project this user might be working on, as in the following examples:
-- assume this is in /home/user1/work/default.gpr
project Default is
for Object_Dir use "obj";
package IDE is
for Xref_Database use "xref_database.db";
-- This would be /home/user1/work/xref_database.db
for Xref_Database use Project'Object_Dir & "/xref_database.db";
-- This would be /home/user1/work/obj/xref_database.db
-- This is the default when this attribute is not specified
for Xref_Database use external("HOME") & "/prj1/database.db";
-- This would be /home/user1/prj1/database.db
end IDE;
end Default;
One of the drawbacks in altering the default location is that gprclean will not be able to remove this database when you clean your project.
On the other hand, it might speed up your system if you can put the database on a fast local disk.
Open the corresponding spec file if the current edited file is a body file, or body file otherwise. This item is also accessible through the editor’s contextual menu
This capability requires support for cross-references. This item is also accessible through the editor’s contextual menu
This contextual menu is available from any source editor. If you right click on an entity, or first select text, the contextual menu will apply to this selection or entity.
This menu is similar to the one above, except it is possible to select more precisely what kind of reference should be displayed. It is also possible to indicate the scope of the search, and whether the context (or caller) at each reference should be displayed.
This dialog has an option Include overriding and overriden operations, which, when activated, will include references to overriden or overriding entities of the one you selected.
This is particularly useful when you are wondering whether you can easily modify the profile of a primitive operation or method, since you can then see what other entities will also be impacted. If you select only the declaration check box, you will see the list of all related primitive operations.
This dialog also allows you to find out which entities are imported from a given file/unit. Click on any entity from that file (for instance on the with line for Ada code), then select the All entities imported from same file toggle button. This will display in the location window the list of all entities imported from the same file as the entity selected.
In addition, if you have selected the Show context option, you will get a list of all the exact references to these entities within the file. Otherwise, you just get a pointer to the declaration of the imported entities.
Remove expanded code from the current editor.
For Ada files only, this entry will generate, and will open this file at the location corresponding to the current source line.
When the Control key is pressed and you start moving the mouse, entities in the editors under the mouse cursor become hyperlinks and the mouse cursor aspect changes.
Left-clicking on a reference to an entity will open a source editor on the declaration of this entity, and left-clicking on an entity declaration will open an editor on the implementation of this entity.
Left-clicking on the Ada declaration of a subprogram imported from C will open a source editor on the definition of the corresponding C entity. This capability requires support for cross-references.
Clicking with the middle button on either a reference to an entity or the declaration of an entity will jump directly to the implementation or type completion) of this entity.
Note that for efficiency, GPS may create hyperlinks for some entities which have no associated cross reference. In this case, clicking will have no effect, even though an hyperlink may have been displayed.
This behavior is controlled by the General ‣ Hyper links preference.
Dispatching calls in Ada and C++ source code are highlighted by default in GPS via the dispatching.py plug-in.
Based on the cross-reference information, this plug-in will highlight (with a special color that you can configure in the preferences dialog) all calls that are dispatching (or calls to virtual methods in C++). A dispatching call, in Ada, is a subprogram call where the actual subprogram that is called is not known until run time, and is chosen based on the tag of the object (so this of course only exists when you are using object-oriented programming).
To disable this highlighting (which might sometimes be slow if you are using big sources, even though the highlighting itself is done in the background), you can go to the Tools ‣ Plug-ins menu, and disable the dispatching.py plug-in.