Next: The Project Dependencies Editor, Previous: The Project Menu, Up: Project Handling

### 7.8 The Project Wizard

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:

- Project type
- Project Naming
- Languages Selection
- Version Control System Selection
- Source Directories Selection
- Build Directory
- Main Units
- Library
- Naming Scheme
- Switches

#### 7.8.1 Project Type

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.

- Single Project

  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

- Project Tree

  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

- Convert GLIDE Project (.adp)

  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.

- Library Project This specialized wizard is similar to the Single Project wizard, except it adds one extra page, the Library page. The output of the compilation of this project is a library (shared or static), as opposed to an executable in the case of `Single Project`.
- Extending Project This specialized wizard allows you to easily create extending projects (see Extending Projects).

#### 7.8.2 Project Naming

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).

#### 7.8.3 Languages Selection

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.

#### 7.8.4 VCS Selection

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.

#### 7.8.5 Source Directories Selection

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.

#### 7.8.6 Build Directory

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.

#### 7.8.7 Main Units

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.

#### 7.8.8 Library

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.

#### 7.8.9 Naming Scheme

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.

#### 7.8.10 Switches

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:

Graphical selection of switches
  The top part of each page contains a set of buttons, combo boxes, entry fields, ... which give fast and intuitive access to the most commonly used switches for that tool.
Textual selection of switches
  The bottom part is an editable entry field, where you can directly type the switches. This makes it easier to move from an older setup (e.g. Makefile, script) to GPS, by copy-pasting switches.

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.