[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The section on the project explorer (2.5 The Project Explorer) has already given a brief overview of what the projects are, and the information they contain.
This chapter provides more in-depth information, and describes how such projects can be created and maintained.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes what the projects are, and what information they contain.
The most important thing to note is that the projects used by GPS are the same as the ones used by GNAT. These are text files (using the extension `.gpr') which can be edited either manually, with any text editor, or through the more advanced GPS interface.
The exact syntax of the project files is fully described in the GNAT User's Guide (gnat_ug.html) and GNAT Reference Manual (gnat_rm.html). This is recommended reading if you want to use some of the more advanced capabilities of project files which are not yet supported by the graphical interface.
GPS can load any project file, even those that you have been edited manually. Furthermore, you can manually edit project files created by GPS.
Typically you will not need to edit project files manually, since several graphical tools such as the project wizard (7.6 The Project Wizard) and the properties editor(7.7 The Project Properties Editor) are provided.
GPS doesn't preserve the layout nor comments of manually created projects after you have edited them in GPS. For instance, multiple case statements in the project will be coalesced into a single case statement. This normalization is required for GPS to be able to preserve the previous semantic of the project in addition to the new settings.
All command-line GNAT tools are project aware, meaning that the notion of project goes well beyond GPS' user interface. Most capabilities of project files can be accessed without using GPS itself, making project files very attractive.
GPS uses the same mechanisms to locate project files as GNAT itself:
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Project files contain all the information that describe the organization of your source files, object files and executables.
Generally, one project file will not be enough to describe a complex organization. In this case, you will create and use a project hierarchy, with a root project importing other sub projects. Each of the projects and sub projects is responsible for its own set of sources (compiling them with the appropriate switches, put the resulting files in the right directories, ...).
Each project contains the following information (see the GNAT user's guide for the full list)
If one of the source files of project A depends on some source files from project B, then B must be imported by A. If this isn't the case, the compiler will complain that some of the source files cannot be found.
One important rule is that each source file name must be unique in the project hierarchy (i.e. a file cannot be under control of two different projects). This ensures that the same file will be found no matter what project is managing the source file that uses
When sources from imported sub-projects are recompiled, the resulting object files are put in the sub project's own object directory, and will never pollute the parent's object directory.
The default to find this set of source files is to take all the files in the source directories that follow the naming scheme (see below) for each language. In addition if you edit the project file manually, it is possible to provide an explicit list of source files.
This attribute cannot be modified graphically yet.
The name of the file is generally related to the name of the executable.
A given project file hierarchy can be used to compile and link several executables. GPS will automatically update the Compile, Run and Debug menu with the list of executables, based on this list.
GPS also supports embedded targets (VxWorks, ...) by specifying alternate names for the build and debug tools.
The project file contains the information required to log on the remote host.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Another information stored in the project is the list of languages that this project knows about. GPS support any number of language, with any name you choose. However, advanced support is only provided by default for some languages (Ada, C and C++), and you can specify other properties of the languages through customization files (see section 15.4.11 Adding support for new languages).
By default, the graphical interface will only give you a choice of languages among the ones that are known to GPS at that point, either through the default GPS support or your customization files. But you can also edit the project files by hand to add support for any language.
Languages are a very important part of the project definition. For each language, you should specify a naming scheme that allows GPS to associate files with that language. You would for instance specify that all `.adb' files are Ada, all `.txt' files are standard text files, and so on.
Only the files that have a known language associated with them are displayed
in the Project View
, or available for easy selection through the
File->Open From Project
menu. Similarly, only these files are shown
in the Version Control System interface.
It is therefore important to properly setup your project to make these files
available conveniently in GPS, although of course you can still open any file
through the File->Open
menu.
If your project includes some README files, or other text files, you should
add "txt" as a language (or any other name you want), and make sure that
these files are associated with that language in the Project properties
editor
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The behavior of projects can be further tailored by the use of scenarios.
All the attributes of a project, except its list of imported projects, can be chosen based on the value of external variables, whose value is generally coming from the host computer environment, or directly set in GPS (using the small area on top of the project explorer (2.5 The Project Explorer).
This facility can for instance be used to compile all the sources either in debug mode (so that the executables can be run in the debugger), or in optimized mode (to reduce the space and increase the speed when delivering the software). In this configuration scenario, all the attributes (source directories, tools, ...) remain the same, except for the compilation switches. It would be more difficult to maintain a completely separate hierarchy of project, and it is much more efficient to create a new configuration variable and edit the switches for the appropriate scenario (7.7 The Project Properties Editor).
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Creating a new scenario variable is done through the contextual menu
(right-click) in the project explorer. Select the menu Add
Configuration Variable
. This opens the following dialog:
There are two main areas in this dialog: in the top line, you specify the name of the variable. This name is used for two purposes:
If you click on the arrow on the right of this name area, GPS will display the list of all the environment variables that are currently defined. However, you don't need to pick the name of an existing variable, neither must the variable exist when GPS is started.
The second part of this dialog is the list of authorized value for this variable. Any other value will generate an error reported by GPS, and the project won't be loaded as a result.
One of these values is the default value (the one whose button in the Default column is selected). This means that if the environment variable doesn't exist when GPS is started, GPS will behave as if it did exist with this default value.
The list of possible values can be edited through the Remove
,
Add
and Rename
buttons, although you can also simply
click on the value itself to change it.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
If at least one configuration variable is defined in your project, the area on top of the project explorer will contain something similar to:
This screen shot shows two configuration variables, named Build
and OS
, with their current value (resp. Debug
and
Unix
).
You can easily change the current value of any of these variables by clicking on the arrow on the right of the value. This will display a pop-up window with the list of possible values, from which you select the one you wish to use.
As soon as a new value is selected, GPS will recompute the project
explorer (in case source directories, object directories or list
of source files have changed). A number of things will also be updated
(like the list of executables in the Compile
, Run
and
Debug
menus).
Currently, GPS will not recompute the contents of the various browsers (call graph, dependencies, ...) for this updated project. This would be too expensive to do every time the value changes, and therefore you need to explicitly request an update.
You can change the list of possible values for a configuration variable at any time by clicking on the button to the far left of the variable's name. This will pop up the same dialog that is used to create new variables
Removing a variable is done by clicking on the button immediately to the left of the variable's name. GPS will then display a confirmation dialog.
If you confirm that you want to delete the variable, GPS will simply remove the variable, and from now on act as if the variable always had the value it had when it was deleted.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The project explorer, as mentioned in the general description of the GPS window, is one of the two explorers found by default on the left of the window. It shows in a tree structure the project hierarchy, along with all the source files belonging to the project, and the entities declared in the source files.
It is worth noting that the explorer provides a tree representation of the project hierarchy. If a project is imported by multiple other projects in the hierarchy, then this project will appear multiple times in the explorer.
Likewise, if you have edited the project manually and have used the
limited with
construct to have cycles in the project
dependencies, the cycle will expand infinitely. For instance, if
project `a' imports project `b', which in turns imports
project `a' through a limited with
clause, then expanding
the node for `a' will show `b'. In turn, expanding the node
for `b' will show a node for `a', and so on.
The contextual menu in this explorer provides a number of items to modify the project hierarchy (what each project imports), as well as to visualize and modify the attributes for each projects (compilation switches, naming scheme, ...)
The following entries are available in the contextual menu:
Show Projects Imported by...
Save The Project...
Project->Save All
.
Edit Project Properties
Add Dependency...
Remove Dependency...
Add Configuration Variable
Edit Project Source File
Any time one or several projects are modified, the contents of the explorer is automatically refreshed. No project is automatically saved. This provides a simple way to temporarily test new values for the project attributes. Unsaved modified projects are shown with a special icon in the project explorer, displaying a red exclamation mark on top of the standard icon:
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The menu bar item Project
contains several commands that
generally act on the whole project hierarchy. If you only want to act
on a single project, use the contextual menu in the project explorer.
Some of these menus apply to the currently selected project. This notion depends on what window is currently active in GPS: if it is the project explorer, the selected project is either the selected node (if it is a project), or its parent project (for a file, directory, ...). If the currently active window is an editor, the selected project is the one that contains the file.
In all cases, if there is no currently selected project, the menu will apply to the root project of the hierarchy.
These commands are:
New
Yes
, the new
project will replace the currently loaded project hierarchy.
Open
Recent
Edit Project Properties
Save All
Edit File Switches
Recompute Project
File View and Project View
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The project wizard allows you to create in a few steps a new project file. It has a number of pages, each dedicated to editing a specific set of attributes for the project.
The typical way to access this wizard is through the
Project->New...
menu. On exit, the wizard will ask whether the newly
created project should replace the currently loaded ones.
The project wizard is also launched when a new dependency is created between two projects, through the contextual menu in the project explorer.
The wizard gives access to the following list of pages:
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This is the first page displayed by the wizard.
You must enter the name and location of the project to create. This
name must be a valid Ada identifier (i.e. start with a letter,
optionally followed by a series of digits, letters or
underscores). Spaces are not allowed. Likewise, reserved Ada keywords
must be avoided. If the name is invalid, GPS will display an error
message when you press the Forward
button.
Child projects can be created from this dialog. These are project whose
name is of the form Parent.Child
. However, the generated project
is invalid, since one of the restrictions for these projects, which is
currently not enforced by GPS, is that the project must import or
extend its parent project. Therefore, you will not be able to
load this project in GPS until you have manually edited it.
In this page, you should also select what languages the source files
in this project are written in. Currently supported languages are Ada
,
C
and C++
. Multiple languages can be used for a single
project.
The last part of this page is used to indicate how the path should be stored in the generated project file. Most of the time, this setting will have no impact on your work. However, if you wish to edit the project files by hand, or be able to duplicate a project hierarchy to another location on your disk, it might be useful to indicate that paths should be stored as relative paths (they will be relative to the location of the project file).
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This page is used to select the programming languages used for the
sources of this project. By default, only Ada
is selected.
New languages can be added to this list by using XML files, see the
section on customizing GPS (see section 15.4.11 Adding support for new languages).
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The second page in the project wizard allows you to select which Version Control system is to be used for the source files of this project.
GPS doesn't attempt to automatically guess what it should use, so you must specify it if you want the VCS operations to be available to you.
The two actions Log checker
and File checker
are the
name and location of programs to be run just prior an actual commit of
the files in the Version Control System. These should be used for
instance if you wish to enforce style checks before a file is actually
made available to other developers in your team.
If left blank, no program will be run.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This page lists and edits the list of source directories for the project. Any number of source directory can be used (the default is to use the directory which contains the project file, as specified in the first page of the wizard).
If you do not specify any source directory, no source file will be associated with the project, since GPS wouldn't know where to look for them.
To add source directories to the project, select a directory in the top frame, and click on the down arrow. This will add the directory to the bottom frame, which contains the current list of source directories.
You can also add a directory and all its subdirectories recursively by using the contextual menu in the top frame. This contextual menu also provides an entry to create new directories, if needed.
To remove source directories from the project, select the directory in the bottom frame, and click on the up arrow, or use the contextual menu.
All the files in these directories that match one of the language supported by the project are automatically associated with that project.
The relative sizes of the top and bottom frame can be changed by clicking on the separation line between the two frames and dragging the line up or down.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The object directory is the location where the files resulting from the compilation of sources (e.g. `.o' files) are placed. One object directory is associated for each project.
The exec directory is the location where the executables are put. By default, this is the same directory as the object directory.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The main units of a project are the files that should be compiled and linked to obtain executables.
Typically, for C applications, these are the files that contain the
main()
function. For Ada applications, these are the files that
contain the main subprogram each partition in the project.
These files are treated specially by GPS. Some sub-menus of
Build
and Debug
will have predefined entries for the
main units, which make it more convenient to compile and link your
executables.
To add main units click on the Add
button. This opens a file
selection dialog. No check is currently done that the selected file
belongs to the project, but GPS will complain later if it doesn't.
When compiled, each main unit will generate an executable, whose name is visible in the second column in this page. If you are using a recent enough version of GNAT (3.16 or more recent), you can change the name of this executable by clicking in the second column and changing the name interactively.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A naming scheme indicates the file naming conventions used in the different languages supported by a given project. For example, all `.adb' files are Ada files, all `.c' files are C files.
GPS is very flexible in this respect, and allows you to specify the
default extension for the files in a given programming language. GPS makes a
distinction between spec (or header) files, which generally contain
no executable code, only declarations, and body files which contain
the actual code. For languages other than Ada, this header file is
used rather than the body file when you select Go To
Declaration
in the contextual menu of editors.
In a language like Ada, the distinction between spec and body is part of the definition of the language itself, and you should be sure to specify the appropriate extensions.
The default naming scheme for Ada is GNAT's naming scheme (`.ads' for specs and `.adb' for bodies). In addition, a number of predefined naming schemes for other compilers are available in the first combo box on the page. You can also create your own customized scheme by entering a free text in the text entries.
For all languages, GPS accepts exceptions to this standard naming scheme. For instance, this let you specify that in addition to using `.adb' for Ada body files, the file `foo.ada' should also be considered as an Ada file.
The list of exceptions is displayed in the bottom list of the naming scheme editor. To remove entries from this list, select the line you want to remove, and then press the Del key. The contents of the lines can be edited interactively, by double-clicking on the line and column you want to edit.
To add new entries to this list, use the fields at the bottom of the window, and press the update button.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The last page of the project wizard is used to select the default switches to be used by the various tools that GPS calls (compiler, linker, binder, pretty printer, ...).
This page appears as a notebook, where each page is associated with a specific tool. All these pages have the same structure:
The two parts of the pages are kept synchronized at any time: clicking on a button will edit the entry field to show the new switch; adding a new switch by hand in the entry field will activate the corresponding button if there is one.
Any switch can be added to the entry field, even if there is no corresponding button. In this case, GPS will simply forward it to the tool when it is called, without trying to represent it graphically.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The project properties editor gives you access at any time to the properties
of your project. It is accessible through the menu
Project->Edit Project Properties
, and through the contextual menu
Edit project properties
on any project item, e.g. from the Project
View or the Project Browser.
If there was an error loading the project (invalid syntax, non-existing directories, ...), a warning dialog is displayed when you select the menu. This reminds you that the project might be only partially loaded, and editing it might result in the loss of data. In such cases, it is recommended that you edit the project file manually, which you can do directly from the pop-up dialog.
Fix the project file as you would for any text file, and then reload
it manually (through the Project->Open...
or
Project->Recent
menus.
The project properties editor is divided in three parts:
General
page are exactly the same, and you should therefore
read the description for these in the project wizard chapter.
The general page gives access to more attributes than the general page of the project wizard does. In addition, you can select the name of the external tools that GPS uses (such as compilers, debugger, ...).
See also 14. Working in a Cross Environment for more info on the
Cross environment
attributes.
Clicking on the right title bar (Project
) of this selector will sort the
projects in ascending or descending order.
Clicking on the left title bar (untitled) will select or unselect all the projects.
This selector has two different possible presentations, chosen by the toggle button on top: you can either get a sorted list of all the projects, each one appearing only once. Or you can have the same project hierarchy as displayed in the project explorer.
Clicking on the left title bar (untitled, on the left of the Scenario
label) will select or unselect all values of all variables.
To select all values of a given variable, click on the corresponding check button.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The switches editor, available through the menu Project->Edit
Switches
, lists all the source files associated with the selected
project.
For each file, the compiler switches are listed. These switches are displayed in gray if they are the default switches defined at the project level (see section 7.7 The Project Properties Editor). They are defined in black if they are specific to a given file.
Double-clicking in the switches column allows you to edit the switches
for a specific file. It is possible to edit the switches for multiple
files at the same time by selecting them before displaying the contextual
menu (Edit switches for all selected files
).
When you double-click in one of the columns that contain the switches, a new dialog is opened that allows you to edit the switches specific to the selected files.
This dialog has a button titled Revert
. Clicking on this button
will cancel any file-specific switch, and revert to the default
switches defined at the project level.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The project graph is a special kind of browser (see section 10. Source Browsing). It shows the dependencies between all the project in the project hierarchy. Two items in this browser will be linked if one of them imports the other.
It is accessed through the contextual menu in the project explorer, by
selecting the Show projects imported by...
item, when
right-clicking on a project node.
Clicking on the left arrow in the title bar of the items will display all the projects that import that project. Similarly, clicking on the right arrow will display all the projects that are imported by that project.
The contextual menu obtained by right-clicking on a project item contains several items. Most of them are added by the project editor, and gives direct access to editing the properties of the project, adding dependencies... See section 7.4 The Project Explorer.
Some new items are added to the menu:
Locate in explorer
Show dependencies
Show recursive dependencies
Show projects depending on
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |