6. Source Navigation
6.1. Support for Cross-References
GNAT Studio provides cross-reference navigation for program entities defined in your application such as types, procedures, functions, and variables.
6.2. Navigating with hyperlinks
When you press the Control key and start moving the mouse, entities in the editors under the pointer become hyperlinks and the form of the pointer changes.
Left-clicking on a reference to an entity opens a source editor on the declaration of the entity and left-clicking on an entity declaration opens an editor on the implementation of the entity. Depending on the Editor ‣ Ada ‣ Display ancestry on navigation preference, a menu can popup when navigating, for instance to list all the possible declarations that can be called when ctrl-clicking on a dispatching call.
For efficiency, GNAT Studio may create hyperlinks for some entities which have no associated cross reference. In this case, clicking has no effect even though a hyperlink is displayed.
This behavior is controlled by the General ‣ Hyper links preference.
6.3. Contextual Menus for Source Navigation
This contextual menu is available from any source editor. If you right-click on an entity or selected text, the contextual menu applies to the selection or entity. Most of these menus requires support for cross-references. Here are the main ones regarding navigation.
Jump to Specification/Implementation File
Open the corresponding spec file if the current edited file is a body file, or the body file otherwise. This entry is only available for the Ada language.
Go To Declaration
Go to the declaration (spec) of the clicked entity.
Go To Body or Full Declaration
This entry appears for a private on subprograms or limited private types. Go to body or the full declaration (spec) of the clicked entity.
Go To Type Declaration
Go to the type declaration of the clicked entity.
Find All References
Finds all the references to the clicked entity.
The option Include overriding and overridden operations includes references to overridden or overriding entities. This is particularly useful if you need to know whether you can easily modify the profile of a primitive operation or method since you can see which other entities would also be changed. If you select only the declaration check box, you see the list of all related primitive operations.
This dialog allows you to determine which entities are imported from a given file or unit. Click on any entity from that file (for example on the with line for Ada code) and select the All entities imported from same file toggle, which displays in the Location view the list of all entities imported from the same file.
Selecting the Show context option produces a list of all the references to these entities within the file. If it is not selected, you just get a pointer to the declaration of the imported entities.
Call Trees ‣ *Entity* is called by
Display a list of all subprograms calling the clicked entity in a tree view.
6.4. The gnatinspect cross-reference database (deprecated)
Previous versions of GNAT Studio relied on the compiler for navigation information; this section covers specifics for this engine, which is now deprecated.
6.4.1. The cross-reference database
GNAT Studio parses the cross-reference information generated by the compiler
(the .ali
) files into one or several sqlite databases (e.g:
if your project uses Ada and C). These database files can become quite large
and should preferably be on a fast local disk.
By default, GNAT Studio places these database files in the object directory of the currently-loaded root project, or, if specified, in the directory designated by the relative or absolute path given by the Artifacts_Dir attribute of the IDE package of your project file:
-- assume this is in /home/user1/work/default.gpr
project Default is
for Object_Dir use "obj";
package IDE is
for Artifacts_Dir use "artifacts";
-- All the artifacts generated by GNAT Studio
-- (including the xref databases)
-- will be put in the /home/user1/work/artifacts/ directory.
--
-- We could also have specified an absolute path here
-- (e.g: for Artifacts_Dir use "/home/user1/work/artifacts/").
end IDE;
end Default;
If you want to have more advanced control regarding the naming of the Ada cross-references database file, you can use the Xref_Database in the IDE package of your project file, either as an absolute path or a path relative to the location of the project file. We recommend this path to be specific to each use, 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 drawback in altering the default location is that gprclean will not remove these database files when you clean your project. But it might speed up GNAT Studio if your project is not on a fast local disk and you can put the databases there.
WARNING: You should not store this file in a directory that is accessed via a network filesystem, like NFS, or Clearcase’s MVFS. If your obj directory is on such a filesystem, be sure to specify a local directory for IDE’Artifacts_Dir project attribute or, if you project only uses Ada, a custom local file path for the IDE’Xref_Database project attribute.
6.4.2. Cross-references and partially compiled projects
The cross-reference engine works best when the cross-reference
information generated by the compiler (the .ali
files) is
fully up to date.
If you start from such a state and then modify the spec or body of an Ada package and recompile only that file, any reference to entities declared in that spec in other packages might no longer be found (until you recompile those other packages, as gprbuild would).
This is because GNAT Studio has no way to know for sure whether an entity
Foo
in the spec is the same entity as before or is a new one with
the same name. It uses an approximate algorithm where the references are
only preserved if an entity with the same name remains at precisely the
same location in the new version of the source. But if a blank line in the
file will change the declaration line for all entities declared further in
the file, so those will lose their references from other source files.
6.4.3. Cross-reference and GNAT runtime
By default, GNAT Studio does not parse the GNAT runtime files because there is
a large number of them and doing so would significantly slow down GNAT Studio,
while producing only a minimal gain for most users. However, the location of
subprograms in those runtime files is available from the .ali
files
corresponding to the sources of your project.
From your own sources, you can navigate to one of the runtime files (for
example, if you have a reference to Put_Line()
, you will jump to its
declaration in a-textio.ads
). But you cannot perform
cross-reference queries from a runtime file itself.
If you need this capability, enable the preference Project/Cross References in Runtime Files.