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.
The project wizard is also launched when a new dependency is created between two projects, through the contextual menu in the project view.
The wizard gives access to the following list of pages:
Several types of project wizards are provided in GPS. Depending on the information you have or your current setup, you will choose one or the other.
This is likely the wizard you will use most often. It creates a project file from scratch, and asks you for the location of source directories, the object directory, ...; The rest of this chapter describes this wizard in more details
This wizard will attempt to create a set of one or more project files to represent your current build environment. It will analyze what your sources are, where the corresponding object files are, and will try and find some possible setup for the project files (remember that a given .gpr project file can be associated with a single object directory.
This wizard might not work in all cases, but is worth a try to get you started if you already have an existing set of sources
This wizard will help you convert a .adp project file that is used by the GLIDE environment. The same restrictions apply as above, except that the list of source directories, object directories and tool switches are read directly from that file.
Single Project.
This is the first page displayed by any of 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. GPS will automatically generate
the dependency to the parent project so as to make the child project
valid.
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).
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 Adding support for new languages).
Additionally, this page allows you to select the toolchain used when working on your project. There you can select one of the pre-defined toolchains or scan your system for installed toolchains. You can also manually define some of the tools in the toolchain such as the debugger to use, the gnat driver to use or the gnatls tool to use.
If you need to select a toolchain for a cross environment, you should have a look at Working in a Cross Environment for more info on this subject.
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.
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.
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.
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 makes 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.
This page allows you to configure your project so that the output of its compilation is a library (shared or static), as opposed to an executable or a simple set of objet files. This library can then be linked with other executables (and will be automatically if the project is imported by another one.
You need to define the attributes in the top box to transform your project into a library project. See the tooltips that appear when you leave your mouse on top of the label to the left of each field.
If you define any of the attributes in the Standalone Library box, you will compile a standalone library. This is a library that takes care of its elaboration by itself, instead of relying on its caller to elaborate it as is standard in Ada. You also have more control over what files make up the public interface to the library, and what files are private to the library and invisible from the outside.
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.
GNAT and GPS both support Ada source files that contain multiple Ada units (typically a single file would contain both the spec and the body of the unit for instance). This is not a recommend approach if you can avoid it, since that might trigger unnecessary recompilation of your source files. Such source files are always handled as naming scheme exceptions, and you can specify those in the editor by adding "at 1", "at 2",... after the file name for either the spec, the body or both. The digit after "at" is the index (starting at 1) of the unit in the source file.
For instance, specifying "file.ada at 1" for the spec and "file.ada at 2" for the body of the unit "unit" indicates that the two components of the unit are in the same file, first the spec, followed by the body.
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.
