5.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, Scenarios in Projects, and 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 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 `with's package Pack. We want to compile
these source files with the switch
`-O2', and put the resulting files in
the directory obj/.
common/
pack.ads
pack.adb
proc.adb
common/obj/
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;