5.1. Crucial Setup Requirement

Unlike Ada-aware editing, which will work for any properly-named Ada source file, browsing and navigating require some processing prior to use. Specifically, these facilities require the Ada source code to be in a GNATbench project and to have been analyzed by the GNAT Pro compiler. Failure to meet these requirements will result in either unsuccessful invocations or missing menu entries in some menus.

Being “in” a GNATbench project means that the source code is in a file residing within one of the directories specified by the Source_Dirs attribute of a GNATbench project file (the project “gpr file”). Implicit inclusion by residence within the same directory as the project file will also suffice.

Analysis by the GNAT Pro compiler happens either automatically, as a result of normal compilation, or explicitly, by manual invocation of the compiler in a special mode to perform the analysis.

Therefore, building the entire project will make all the sources navigable. Of course, those Ada files not in a GNATbench project are not compiled when building the project so they are not analyzed. That means they will not support navigation and browsing, even though the Ada editor will open them.

You can compile individual files via the Ada editor’s contextual menu. Manually compiling some of the files will make some of the files navigable.

Analysis results are stored in a cross-reference database. By default this database is named ‘gnatinspect.db’ and is located in the project’s object directory.

For your convenience, GNATbench attempts to support navigation prior to the corresponding files’ analysis, but to ensure full functionality you must use the compiler to analyze the sources. When the functionality is not possible a dialog box will notify you of that fact, suggesting the cause of the problem.

Also for your convenience, GNATbench attempts to support navigation even in the face of changes to the source code. Such changes can invalidate any previous analysis, however, so ensuring accurate navigation functionality requires that you re-analyze the code.

5.1.1. The cross-reference database

GNATbench parses the cross-reference information generated by the compiler (the .ali and .gli) files into an sqlite database. This database can become quite large and should preferably be on a fast local disk.

By default, GNATbench places this database in the object directory of the currently-loaded root project. Override this choice by adding an attribute 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 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 this database when you clean your project. But it might speed up GNATbench if your project is not on a fast local disk and you can put the database 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 custom Xref_Database directory in your project file.

5.1.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 GNATbench 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.