### 7.1 Description of the Projects

#### 7.1.1 Project files and GNAT tools

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 (The Project Wizard) and the properties editor(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:

- absolute paths
- relative paths. These paths, when used in a with line as described below, are relative to the location of the project that does the with.
- ADA_PROJECT_PATH. If this environment variable is set, it contains a colon-separated (or semicolon under Windows) list of directories in which the project files are searched.
- predefined project path. The compiler itself defines a predefined project path, in which standard libraries can be installed, like XML/Ada for instance.

#### 7.1.2 Contents of project files

Project files contain all the information that describe the organization of your source files, object files and executables.

A project file can contain comments, which have the same format as in Ada, that is they start by "–" and extend to the end of the line. You can add comments when you edit the project file manually. GPS will attempt to preserve them when you save the project through the menu, but this will not always be possible. It helps if the comments are put at the end of the line, as in

         project Default is
             for Source_Dirs use ();  --  No source in this project
         end Default;

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)

- List of imported projects: When you are compiling sources from this project, the compiler (either through GNAT or the automatically generated Makefiles) will first make sure that all the imported projects have been correctly recompiled and are up-to-date. This way, dependencies between source files are properly handled.

  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

- List of source directories: All the sources managed by a project are found in one or more source directories. Each project can have multiple source directories, and a given source directory might be shared by multiple projects.
- Object directory: When the sources of the project are compiled, the resulting object files are put into this object directory. There exist exactly one object directory for each project. If you need to split the object files among multiple object directories, you need to create multiple projects importing one another as appropriate.

  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.

- Exec directory: When a set of object files is linked into an executable, this executable is put in the exec directory of the project file. If this attribute is unspecified, the object directory is used.
- List of source files: The project is responsible for managing a set of source files. These files can be written in any programming languages. Currently, the graphical interface supports Ada, C and C++.

  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.

- List of main units: The main units of a project (or main files in some languages) are the units that contain the main subprogram of the application, and that can be used to link the rest of the application.

  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.

- Naming schemes: The naming scheme refers to the way files are named for each languages of the project. This is used by GPS to choose the language support to use when a source file is opened. This is also used to know what tools should be used to compile or otherwise work with a source file.
- Embedded targets and cross environments: GPS supports cross environment software development: GPS itself can run on a given host, such as GNU/Linux, while compilations, runs and debugging occur on a different remote host, such as Sun/Solaris.

  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.

- Tools: Project files provide a simple way to specify the compiler and debugger commands to use.
- Switches: Each tool that is used by GPS (compiler, pretty-printer, debugger, ...) has its own set of switches. Moreover, these switches may depend on the specific file being processed, and the programming language it is written in.