-------- Concepts -------- .. toctree:: GNAT Pro ======== .. toctree:: .. _concepts-gnat-projects: GNAT Projects ------------- A "GNAT project" is a specific set of values specifying compilation properties, including the switches to be applied, the source files, their directories, their file naming scheme, the name of the executable (if any), and many other aspects. A GNAT project is described by one or more "project files", text files that contain specifications for the properties to be set. Project files can be used individually but can also be arranged into hierarchical subsystems, where build decisions are delegated to the subsystem level, and thus different compilation environments (switch settings) can be used for different subsystems. Project files can be used on the command line and in scripts (e.g., makefiles). Using project files considerably simplifies command line and script usage because some or all of the switches are specified by the project file and, therefore, need not be written as explicit tool invocation arguments. The settings specified by a project file become effective when using the GNAT Project Manager. The Project Manager interprets the content of the project file and applies all the corresponding settings when the tools are invoked. The Project Explorer project presentation is oriented around GNAT projects and displays their sources accordingly. The source files or a project are made available for editing and it is these Ada source files that the Builder will build into an executable. Because GNAT Project Files and the GNAT Project Manager control what is displayed to the user as well as what and how executables are built, they form the conceptual foundation for development using GNATbench and should be understood by the user. *See the GNAT User's Guide, section 11 "GNAT Project Manager", for full details of the Project Manager and project files.* .. _concepts-gnat-projects-foreign-ada-source-files: Foreign Ada Source Files ------------------------ A file containing Ada source code *must* be part of a GNATbench project in order for the relevant capabilities of GNATbench to function properly. For example, navigation based on the Ada constructs within the file cannot succeed if the file is not part of a GNATbench project. Being "part of a GNATbench project" means that it is located in a "source directory", i.e., one specified, directly or indirectly, in the Source_Dirs attribute of a project managed by GNATbench. All other Ada source files are "foreign" and will not be processed by GNATbench, except for the most basic of functions. Foreign files are not included in a project build, for example, and navigation and cross referencing for such files will also fail to operate properly. Foreign files are an issue because there are ways within Eclipse to open arbitrary files, including files containing Ada source code, located either inside or outside the Eclipse workspace. Although the Ada editor will be opened for such a file, and will be able to function somewhat for editing, other functionality will fail. When such files are intended to be part of GNATbench they should be located in a source directory specified in the Source_Dirs attribute of an existing GNATbench project. There are various ways to do so, including importing the containing folder from the file system via the "Import..." wizard and then ensuring it is in the list of directories in the Source_Dirs attribute. Alternatively, you can import an entire external GNAT (not GNATbench) project into Eclipse, so that it becomes a GNATbench project too. You could even simply copy the file to an existing source directory, but one way or the other, the directory containing the file in question must be a "source directory." Project Files ------------- Project file are text files written in a syntax close to that of Ada, using familiar notions such as packages, context clauses, declarations, default values, assignments, and inheritance. Packages within project files correspond to individual tools and are thus defined not by the user but by AdaCore. For example, there is a package Compiler, a package Naming\_Scheme, a package Builder, and so forth. Users set the values of switches for a given tool by defining the property settings within the corresponding package. Global properties may also be defined within a project file, for example the name of the directory to contain all intermediate build products (object files and .ali files). Property values in project files are either strings or lists of strings. Properties that are not explicitly set receive default values. A project file may interrogate the values of "external variables" (user-defined command-line switches or environment variables), and it may specify property settings conditionally, based on the value of such variables. Users have available both a GUI interface and a syntax-driven text editor to specify the property values within project files. The following figure shows a simple project file inside the editor (see the corresponding Help files for the details of the GUI and this syntax-driven editor). In this case all defaults are taken for the tools and only global properties are defined. Specifically, the file name of the main subprogram is specified, the executable is directed to the same directory containing the project file itself, and all intermediate products are directed to a directory named "objs" located immediately underneath the directory containing the project file. .. image:: images/project_file_editor_example.png :align: center :alt: project file editor example Project hierarchies are formed when the so-called "root" project file imports other GNAT project files via "with clauses", as illustrated in the first line of the following project file: .. image:: images/project_file_with_import.png :align: center :alt: project file with-clauses example GNAT Project Manager -------------------- The Project Manager is invoked along with a specific tool and applies the properties of a project file to that tool. The specific project file to be applied is specified by the "-P" argument when the tool invoked. For example, suppose we want to invoke the "gnatmake" tool to do a complete build of everything necessary to generate an executable for some main subprogram. If the project file "myproject.gpr" specifies the name of the main subprogram file, all we have to do is invoke gnatmake with the -P switch and specify the name of that project file: ``gnatmake -P myproject.gpr`` GNATbench will apply the -P switch for you when the builder is invoked, specifying automatically the project file that corresponds to the Ada project to be built. You can see the application of the -P switch when watching the build output in the Builder Console. .. _concepts-scenario-vars: Scenario Variables ------------------ GNAT project files can define "scenario variables" that allow conditional specifications and external dependencies, among other capabilities. For example, scenario variables could be used to define two build scenarios in which different switch settings are applied: one for a debugging release and one for a production release. The debugging release would enable debugging information, reduce optimizations for the sake of debugging, and turn on other checks. The production release would, in contrast, disable debugging information and enable extensive optimizations. External dependencies are possible because the values of scenario variables can be read from environment variables defined at the operating system level. Access to the environment variables is via a function named ``external``. In the following figure, one scenario variable defines the two debug/release build scenarios described above. First, the type Build\_modes defines two possible values (line 3). The a scenario variable of that type named Mode is declared (line 4). The initial value of Mode is from the function ``external`` that reads the value of an environment variable named "BUILD", with a default value of "Debug" corresponding to one of the two values that Mode can take on. The value of Mode is then used to further control switch settings. On line 10, for example, the location of the object directory is determined. On line 17 the default compilation switch settings are defined for the two builder modes: lines 19-21 specify the "Debug" mode compilation settings, whereas lines 22-23 do so for the "Release" mode compilation settings. .. image:: images/project_file_editor_debugrelease_example.png :align: center :alt: project file debug-release scenario example GNATbench defines a wizard that creates a project file defining exactly this builder scenario. In fact, the project file in the figure above was generated entirely automatically by that wizard, with inputs from the user. *See section 11 of the GNAT User's Guide, "GNAT Project Manager", for full details on project files and scenario variables.* GNATbench ========= .. toctree:: Ada Perspective --------------- GNATbench defines a perspective dedicated to the Ada language. The icon representing this perspective (see the figure below) has the letter 'A' in the upper right, with standard Eclipse symbols denoting packages, types, and tasks in the center. You can select this perspective by clicking on the Ada perspective icon at the upper right of the Eclipse window if the perspective is already opened. In the figure below, the Ada perspective icon is shown immediately to the right of the Workbench "open perspective" icon: .. image:: images/ada_perspective.png :align: center :alt: Ada perspective at upper right If it is not open already, you can activate the Ada perspective by clicking on the "open perspective" icon and choosing "Other..." and then Ada from the dialog box listing the perspectives. Alternatively, you can use the menu "Window-> Open Perspective-> Other..." to open that dialog box. The dialog box appears as follows: .. image:: images/perspective_list_dialog.png :align: center :alt: perspective choices Ada Perspective Menus --------------------- The GNATbench Ada perspective adds menus for building, editing, and other activities. These menus are described in detail in other sections; they are enumerated here to facilitate familiarity. For example, an additional menu named "Ada" is added to the menu bar whenever an Ada source file is edited. This menu is illustrated in the figure below: .. image:: images/source_menu_addition.png :align: center :alt: source menu Similarly, addition menu entries are added to the editor's contextual menu when editing an Ada source file: .. image:: images/contextual_editor_menu_addition.png :align: center :alt: editor contextual menu Finally, builder commands are added to the Project menu on the menu bar and the GNAT Project Explorer contextual menu: .. image:: images/project_menu.png :align: center :alt: project menu .. image:: images/explorer_contextual_menu.png :align: center :alt: project explorer contextual menu .. _concepts-wizards: Ada Perspective Wizards ----------------------- The GNATbench Ada perspective defines wizards for creating new Ada projects, new Ada source files, and new Ada source folders. There are multiple ways to select and invoke these wizards. Using the File Menu ~~~~~~~~~~~~~~~~~~~ You can use the menu bar and select "File" and then "New", or use the contextual menu and select "New". In either case you can then select one of the wizards offered: .. image:: images/file_new_wizards.png :align: center :alt: file new wizards You could alternatively select "Other...", as shown in the figure above. This choice will bring up a dialog box showing all the "new" wizards, organized by category, so that you can choose which one to invoke. Note the "Ada" category. .. image:: images/new_wizard_selection_dialog.png :align: center :alt: new wizard selection Expand the "Ada" category, if necessary, and choose between the wizards offered there. .. image:: images/new_wizard_selection_ada.png :align: center :alt: new project wizard Ada category Using the Contextual Menu ~~~~~~~~~~~~~~~~~~~~~~~~~ You can also use the contextual menu of the GNAT Project Explorer: .. image:: images/new_wizard_contextual_menu.png :align: center :alt: new-project wizards in Project Explorer contextual menu The contextual menu of the Navigator also provides these wizards: .. image:: images/new_wizard_contextual_menu_navigator.png :align: center :alt: new-project wizards in Navigator contextual menu Using the Toolbar ~~~~~~~~~~~~~~~~~ GNATbench also provides additions to the Eclipse toolbar, for creating new Ada projects (highlighted by the tool-tip in this case), new Ada source files, and new Ada source folders (automatically added to the GNAT project file): .. image:: images/new_project_wizard_gnat_toolbar.png :align: center :alt: new-project wizards on toolbar Finally, you can use the standard "New" button on the Eclipse toolbar: .. image:: images/new_wizard_toolbar_button.png :align: center :alt: standard new wizard button on toolbar GNATbench Project File Editor ----------------------------- GNATbench provides a simple syntax-oriented editor for GNAT Project Files. Although the GUI interface discussed elsewhere is likely more convenient initially, eventually you may want to edit the file directly. The editor is associated with files having an extension of ".gpr" (standing for "Gnat PRoject") and is thus invoked by double-clicking on the project file within the various viewers, such as the GNAT Project Explorer. (If the default system editor is invoked, you can reassign the GNATbench editor by selecting "Open With -> GNAT Project File Editor" in the contextual menu.) Note also that you can invoke the editor on a project file even when the file is not visible within one of the viewers. This could be the case when the project file is not resident in the project root, for example. In this case, the viewer's contextual menu can be used, as shown below: .. image:: images/gpr_editor_menu_entry.png :align: center :alt: project file editor invocation menu entry Project files are simply text files with an Ada-like syntax. The purpose of the editor is facilitate making syntactically correct changes to these files. To that end, the primary feature of the editor is syntax-driven entity coloring. The colors follow the selections made within the Ada editor for corresponding syntactic categories. An example project file illustrating this coloring is shown in the figure below. .. image:: images/project_file_editor_debugrelease_example.png :align: center :alt: project file editor debug-release example Additionally, the project file editor supports some of the same editor capabilities as the Ada source editor. Specifically, the comment toggle, text refill, smart indenting tab key, and construct closing commands are supported. The Outline view is also supported for packages, variables, and types. .. image:: images/project_file_outline_view.png :align: center :alt: project file outline view GNAT Project Properties Editor ------------------------------ In addition to manually editing the project file, the GNAT project properties can be also manipulated using a multi-tabbed properties dialog. This dialog box is invoked by right-clicking on the project node in the Project View and selecting "GNAT Project -> Edit Properties" from the contextual menu. .. image:: images/gnat_project_edit_prop_menu.png :align: center :alt: gnat project edit properties menu Note that the entry "Edit GPR File" will invoke the textual editor rather than the graphical editor discussed in this section. The following tabbed dialog box will appear. Simply make the required changes and press OK, or press Cancel to abandon any changes. .. image:: images/project_properties_dialog.png :align: center :alt: project properties dialog box Outline View ------------ The Ada plugin supports the standard Workbench Outline view, such that a high-level view of the code is available to facilitate program comprehension and development. .. image:: images/outline_view.png :align: center :alt: Outline View for Ada Specifically, the Outline view presents a hierarchy of entity declarations in the file and annotates the presentation with indicators of entity visibility. Green icons indicate "public" entities and red icons indicate "private" entities. For Ada entities that can appear in both public and private sections, such as the partial and full views of private types, the public section icon will be green and the private section icon will be red. Entities displayed in the Outline view can be ordered by type, visibility, and name. Additionally, all private entities can be hidden so that only the public interfaces are presented. Clicking on an entry of the outline will traverse to the corresponding location in the source file. .. _concepts-scenario-view: Scenario Variables View ----------------------- You can view and modify the scenario variables currently defined by any GNAT project using the Scenario Variables view. This view depicts the external scenario variables defined by all GNAT projects, allowing you to chose the values to apply to them. The external names of the variables appear underneath their defining project names, with the possible values for each variable in the corresponding pull-down list. You can click on the value to invoke the pull-down list, or click on the down-arrow at the right of the value. .. image:: images/scenario_view_native.png :align: center :alt: scenario view If a given project does not define any scenario variables, none will appear underneath the project name. Projects that are not Ada projects will not appear in the view at all, nor will those Ada projects that are not root projects. Call Hierarchy View ------------------- The GNATbench Ada plugin also supports the Call Hierarchy View. This view shows all the invocations of a given subprogram or, alternatively, all subprograms invoked by that selected subprogram. The view is opened by selecting the subprogram in question, right-clicking to invoke the contextual menu, and then selecting Open Call Hierarchy in that menu. Alternatively, pressing *control+alt+H* will open the view on the subprogram currently selected. The following is a Call Hierarchy View for a procedure named Display, showing the routines it invokes. .. image:: images/call_hierarchy_view1.png :align: center :alt: Call Hierarchy View for Ada .. _concepts-project-explorer: GNAT Project Explorer --------------------- The GNAT Project Explorer provides a GNAT-specific view of the project, including a contextual menu, without the additional information provided by the Navigator (for example) that might be extraneous in normal use. Projects that are not configured as GNATbench projects are given the standard resource layout with no changes. With the GNAT Project Explorer you will not need to use the Eclipse Navigator except for a few Eclipse resource-oriented activities. In this view, GNATbench projects contain four kind of entries: the source directories, the run-time library, the object directory, and finally the resources present in the project but not managed through the GNAT project file. The source directories are listed at the beginning of the project. Their content is the exact sources of the project, filtering out non-source files. The run-time library entry gives access to the run-time files currently used by the project. The object directory contains the object code files and the ali files generated by the compilation process. Unless you specify otherwise, this directory will also contain the executable image, but as shown below the executable can be in a dedicated directory as well. A sample project in the GNAT Project Explorer is shown in the figure below. .. image:: images/project_explorer.png :align: center :alt: gnat project explorer Enabling the GNAT Project Explorer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the Ada perspective you can open the view by using the Window menu entry and selecting the shortcut to the view: .. image:: images/enabling_project_explorer_ada_perspective.png :align: center :alt: enabling the project explorer view via Window menu Otherwise you can use the Window menu entry and select "Show View" -> "Other..." to bring up the dialog box shown below. Expand the "Ada" category and select "GNAT Project Explorer". .. image:: images/enabling_project_explorer.png :align: center :alt: enabling the project explorer view Press OK and the Explorer will open. Source Folders and Source Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ "Source folders" are those folders specified in the GNAT project file via the "Source\_Dirs" attribute. Similarly, "binary folders" are those folders defined to contain compilation products, such as object files and executables, via the "Object\_Dir" and "Exec\_Dir" attributes. The figure below illustrates two of these attributes: .. image:: images/gpr_file_source_object_dir_attributes.png :align: center :alt: gpr\_file\_source\_object\_dir\_attributes "Source files" are files that are both located within "source folders" and are of recognized languages defined by GNAT and the GNAT project file. The next figure shows a typical definition of the Languages attribute in a project file: .. image:: images/gpr_file_languages_attr_example.png :align: center :alt: gpr\_file\_languages\_attr\_example The GNAT Project Explorer only shows the "source files" within a "source folder". If you want to maintain other files in folders, you should create additional folders to contain them rather than use a "source folder" for that purpose. Viewing Project Source Folders and Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The GNAT Project Explorer shows the source folders and source files within those directories, in tree format, as the first node(s) in the project. The icon for the source folders is that of a folder containing a package, as shown below. Clicking on file names within these trees will open the corresponding files in the Ada-aware editor. Note that the source folders are displayed as a flat list, regardless of how they are represented on the disk. .. image:: images/project_explorer_files.png :align: center :alt: project explorer showing source files Browsing Unit Content ~~~~~~~~~~~~~~~~~~~~~ Additionally, the GNAT Project Explorer includes browser functionality similar to that of the Outline View. In particular, if you expand a given file node you will see icons for the language-specific contents of the file. Clicking on one of these entities in the Project Explorer will take you to the source code for that entity, opening the file in an editor if not already open. .. image:: images/project_explorer_browsing.png :align: center :alt: project explorer browsing Contextual Menus ~~~~~~~~~~~~~~~~ Project nodes within the GNAT Project Explorer have a contextual menu offering specific commands for Ada development, as well as some general capabilities. Additional menu entries for other external tools will also appear, in particular SPARK if it is installed. .. image:: images/project_explorer_contextual_menu.png :align: center :alt: project explorer contextual menu Lower level nodes also have a contextual menu offering specific commands for Ada development. Note in particular the command to compile the corresponding file. .. image:: images/project_explorer_contextual_menu_lower_level.png :align: center :alt: project explorer contextual menu Viewing Run-Time Library Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The run-time library entry gives access to the run-time files currently used by the project. You can open any of these files in the editor for browsing. You should not alter these files unless you intend to recompile the library. Note that the run-time library files include the GNAT-provided utility packages in the GNAT.\* hierarchy. Note also that the displayed content may change if you install a new version of the compiler or if you change the settings of the project file to use a different compiler or run-time library. In the following figure we have expanded the run-time library node to show the source files and have opened the spec for package Ada.Calendar.Formatting in the file named "a-calfor.ads" .. image:: images/project_explorer_browsing_runtime.png :align: center :alt: project explorer browsing runtime library Viewing Project Dependencies ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The GNAT Project Explorer displays the other projects, if any, that the current project depends upon. (One project depends upon another if its GNAT project file (the "gpr file") contains a "with-clause" specifying the other GNAT project file.) These dependencies are displayed in a sub-node named "Project Dependencies." For example, the following figure illustrates the case in which the GNAT project "example" depends upon another project named "Components": .. image:: images/project_explorer_showing_dependency.png :align: center :alt: project explorer showing project dependency Metrics View ------------ The Metrics view shows the results of performing a metrics analysis on Ada source files using several different metric quantifiers. See :ref:`tool-integrations-gnatmetric` for the details. Results are shown in a tree format, with an overall project summary provided first. Results for each file then follow the project summary. In the figure below, the view has been maximized to show more of the results, and both the summary and the results for one of the subprograms have been expanded. .. image:: ../tool_integrations/images/metrics_view_example.png :align: center :alt: metrics view showing results The Metrics view will be opened automatically after the analysis completes. You can open the view manually, using the shortcut: .. image:: ../tool_integrations/images/showing_metrics_view.png :align: center :alt: showing metrics view via shortcut Opening GNATbench Views ----------------------- In the Ada perspective, you can open a GNATbench view using the "Show View" menu entry (under the Window menubar entry): .. image:: images/enabling_project_explorer_ada_perspective.png :align: center :alt: enabling the project explorer view via Window menu When not in the Ada perspective, use the Window menubar entry select "Show View" as before, and then select "Other..." to bring up the dialog box shown below. Expand the "Ada" category and select the view desired. .. image:: images/enabling_gnatbench_views.png :align: center :alt: enabling GNATbench views Ada Build Console ----------------- GNATbench will show the steps for any project build command in a specific subconsole for that project. These commands include the user-defined commands invoked via the builder menus, as well as the standard builder commands (including project cleaning) and the GNATbench extended build commands. The subconsole will have a title of "Ada build" followed by the name of the project enclosed within square brackets. For example, in the following figure, the project Ms1553\_Demo has completed a full build: .. image:: images/build_console_showing_competed_build.png :align: center :alt: Ada builder subconsole Allocating Enough Memory and Solving OutOfMemoryErrors ====================================================== With GNATbench installed, you may get OutOfMemoryErrors raised by Eclipse. If this happens, it's likely the case that your Java Virtual Machine doesn't reserve enough memory for Eclipse. There are two ways of solving this problem. If the error is raised at startup, you may want to increase the initial amount of memory reserved by the virtual machine. By default, Eclipse will allocate up to 256 megabytes. But it allows you to pass arguments directly to the Java VM using the -vmargs command line argument, which must follow all other Eclipse specific arguments. Thus, to increase the available heap memory, you would typically use: eclipse -vmargs -Xmx<*memory size*> with the <*memory size*> value set to greater than "256M" (256 megabytes -- the default). When using a Sun VM, you may also need to increase the size of the permanent generation memory. The default maximum is 64 megabytes The maximum permanent generation size is increased using the -XX:MaxPermSize= argument: eclipse -vmargs -XX:MaxPermSize=<*memory size*> This argument may not be available for all VM versions and platforms; consult your VM documentation for more details. Note that specifying memory sizes larger than the amount of available physical memory on your machine will cause Java to "thrash" as it copies objects back and forth to virtual memory, which will severely degrade your performance.