Next: , Previous: Introduction, Up: GNAT Project Manager

11.2 Building With Projects

In its simplest form, a unique project is used to build a single executable. This section concentrates on such a simple setup. Later sections will extend this basic model to more complex setups.

The following concepts are the foundation of project files, and will be further detailed later in this documentation. They are summarized here as a reference.

Project file:
A text file using an Ada-like syntax, generally using the .gpr extension. It defines build-related characteristics of an application. The characteristics include the list of sources, the location of those sources, the location for the generated object files, the name of the main program, and the options for the various tools involved in the build process.
Project attribute:
A specific project characteristic is defined by an attribute clause. Its value is a string or a sequence of strings. All settings in a project are defined through a list of predefined attributes with precise semantics. See Attributes.
Package in a project:
Global attributes are defined at the top level of a project. Attributes affecting specific tools are grouped in a package whose name is related to tool's function. The most common packages are Builder, Compiler, Binder, and Linker. See Packages.
Project variables:
In addition to attributes, a project can use variables to store intermediate values and avoid duplication in complex expressions. It can be initialized with a value coming from the environment. A frequent use of variables is to define scenarios. See External Values, See Scenarios in Projects, and See Variables.
Source files and source directories:
A source file is associated with a language through a naming convention. For instance, foo.c is typically the name of a C source file; bar.ads or bar.1.ada are two common naming conventions for a file containing an Ada spec. A compilation unit is often composed of a main source file and potentially several auxiliary ones, such as header files in C. The naming conventions can be user defined See Naming Schemes, and will drive the builder to call the appropriate compiler for the given source file. Source files are searched for in the source directories associated with the project through the Source_Dirs attribute. By default, all the files (in these source directories) following the naming conventions associated with the declared languages are considered to be part of the project. It is also possible to limit the list of source files using the Source_Files or Source_List_File attributes. Note that those last two attributes only accept basenames with no directory information.
Object files and object directory:
An object file is an intermediate file produced by the compiler from a compilation unit. It is used by post-compilation tools to produce final executables or libraries. Object files produced in the context of a given project are stored in a single directory that can be specified by the Object_Dir attribute. In order to store objects in two or more object directories, the system must be split into distinct subsystems with their own project file.

The following subsections introduce gradually all the attributes of interest for simple build needs. Here is the simple setup that will be used in the following examples.

The Ada source files pack.ads, pack.adb, and proc.adb are in the common/ directory. The file proc.adb contains an Ada main subprogram Proc that withs package Pack. We want to compile these source files with the switch -O2, and put the resulting files in the directory obj/. 

     ^common/^[COMMON]^
       pack.ads
       pack.adb
       proc.adb
     ^common/release/^[COMMON.RELEASE]^
       proc.ali, proc.o pack.ali, pack.o

Our project is to be called Build. The name of the file is the name of the project (case-insensitive) with the .gpr extension, therefore the project file name is build.gpr. This is not mandatory, but a warning is issued when this convention is not followed.

This is a very simple example, and as stated above, a single project file is enough for it. We will thus create a new file, that for now should contain the following code: 

     project Build is
     end Build;