\input texinfo   @c -*-texinfo-*-
@input texiplus

@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@c                                                                            o
@c                           GPRBUILD DOCUMENTATION                           o
@c                                                                            o
@c                  G P R B U I L D   U S E R ' S   G U I D E                 o
@c                                                                            o
@c                      Copyright (C) 2007-2008, AdaCore                      o
@c                                                                            o
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo

@setfilename gprbuild_ug.info
@settitle GPRbuild User's Guide
@setchapternewpage odd
@syncodeindex fn cp

@set gprconfig GPRconfig

@c Should be set if we want to generate an index
@c @set useindex 1

@c ------------------------------- macro
@c This macro can be used to insert code sample. Each line should end with
@c @NL{}, since otherwise texinfo doesn't guarantee that newlines will be
@c preserved
@macro CODESAMPLE{TXT}
@ifhtml
@smallexample
@group
\TXT\
@end group
@end smallexample
@end ifhtml
@ifnothtml
@smallexample
@group
\TXT\
@end group
@end smallexample
@end ifnothtml
@end macro

@c simulates a newline when in a @CODESAMPLE
@macro NL{}
@end macro

@c --------------------------- macro
@c This macro can be used to insert a "Tip" or "Did you know" box. In HTML,
@c this box is displayed in the right margin of the text, and thus doesn't
@c disturbs the normal reading flow, but provides additional useful
@c information. A small icon is displayed on the left of the box.
@c Calls to this macro should be followed by @noindent for proper rendering
@c in pdf
@macro TIP{TXT}
@ifhtml
@html
<div class="tip">
@end html
\TXT\
@html
</div>
@end html
@end ifhtml
@ifnothtml
@quotation
@noindent
@image{tip,15pt}  \TXT\
@end quotation
@end ifnothtml
@end macro

@c -------------------------- macro
@c This macro is similar to TIP, but only has an effect in html output,
@c and displayed a note in the margin. This can be used to highlight important
@c points that are repeated in the text. In the other outputs, we do not
@c know how to create margin notes, and whether that would only duplicate
@c information in the main text
@macro TIPHTML{TXT}
@ifhtml
@html
<div class="tip">
@end html
\TXT\
@html
</div>
@end html
@end ifhtml
@end macro

@c -------------------------- macro
@c This macro can be used to insert an "Important" box in the text.
@c This box is displayed inline in the main body of the text, but is
@c surrounded by a frame, and has a small icon on the left.
@c Calls to this macro should be followed by @noindent for proper rendering
@c in pdf
@macro IMPORTANT{TXT}
@ifhtml
@html
<div class="important">
@end html
\TXT\
@html
</div>
@end html
@end ifhtml
@ifnothtml
@quotation
@noindent
@image{important,15pt}  \TXT\
@end quotation
@end ifnothtml
@end macro

@c ------------------------- macro
@c This macro can be used to insert a "Note" box in the text. It is
@c displayed inline in the main body of the text, but has a different
@c icon that the "Important" box
@c Calls to this macro should be followed by @noindent for proper rendering
@c in pdf
@macro NOTE{TXT}
@ifhtml
@html
<div class="note">
@end html
\TXT\
@html
</div>
@end html
@end ifhtml
@ifnothtml
@quotation
@noindent
@image{note,15pt}  \TXT\
@end quotation
@end ifnothtml
@end macro

@c -------------------------- macro
@c This macro creates index entries. Optionally, it can display that
@c entry in the right-side margin of the text in HTML, to help people
@c locate where exactly the index entry points to.

@macro CINDEX{TXT}
@cindex \TXT\
@ifset useindex
@ifhtml
@html
<div class="side"><a href="#Index">
@end html
\TXT\
@html
</a></div>
@end html
@end ifhtml
@end ifset
@end macro

@c ---------------------------

@titlepage
@title GPRbuild User's Guide
@subtitle Document revision level <<TBD>>
@subtitle Date: <<TBD>>
@author AdaCore

@page
@vskip 0pt plus 1filll

Printed November 2007 @*
Copyright @copyright{} 2007, AdaCore

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
@end titlepage

@ifnottex
@node Top, Introduction, (dir), (dir)
@top GPRBUILD User's Guide

@noindent
@menu
* Introduction::
* Guided Tour::
* Important Concepts::
* Building with GPRbuild::
* Cleaning up with GPRclean::
* Configuring with GPRconfig::
* Configuration File Reference::
@ifset useindex
* Index::
@end ifset

@detailmenu
 --- The Detailed Contents ---

Introduction

Guided Tour
* Configuration::
* First Steps::
* Subsystems::
* Project Extensions::
* Libraries::
* Scenarios and conditional source files::

Important Concepts

Building with GPRbuild
* Command Line::
* Switches::
* Initialization::
* Compilation of one or several sources::
* Compilation Phase::
* Post-Compilation Phase::
* Linking Phase::

Cleaning up with GPRclean

Configuring with GPRconfig
* Using GPRconfig::
* The GPRconfig knowledge base::

The GPRconfig knowledge base
* General file format::
* Compiler description::
* Configurations::

Compiler description
* GPRconfig external values::
* GPRconfig variable substitution::

Configuration File Reference
* Project Level Attributes::
* Package Naming::
* Package Builder::
* Package Compiler::
* Package Binder::
* Package Linker::

Index
@end detailmenu
@end menu
@end ifnottex

@c  ------------------------------------------------------------------------
@node Introduction
@unnumbered Introduction
@c  ------------------------------------------------------------------------

@code{GPRbuild} is a generic build tool designed for the construction of
large multi-language systems organized into subsystems and libraries.
It is well-suited for compiled languages supporting separate compilation,
such as Ada, C, C++ or Fortran.

@noindent
@code{GPRbuild} manages a three step build process
@itemize @bullet
@item compilation phase:

Each compilation unit of each subsystem is examined in turn, checked for
consistency, and compiled or recompiled when necessary by the appropriate
compiler.  The recompilation decision is based on dependency information
that is typically produced by a previous compilation.

@item post-compilation phase (or binding):

Compiled units from a given language are passed to a language-specific
post-compilation tool if any. Also during this phase
objects are grouped into static or dynamic libraries as specified.

@item linking phase:

All units or libraries from all subsystems are passed to a linker tool
specific to the set of toolchains being used.
@end itemize

@noindent
@code{GPRbuild} takes as its main input a project file @file{<file>.gpr}
defining the build characteristics of the system under construction
such as:
@itemize
@item which sources to use,
@item where to find them,
@item where to store the objects produced by the compiler,
@item which options should be passed to the compiler.
@end itemize

@noindent
The tool is generic in that it provides, when possible, equivalent
build capabilities for all supported languages. For this, it uses a
configuration file @file{<file>.cgpr} that has a syntax and structure very
similar to a project file, but which defines the characteristics
of the supported languages and toolchains. The configuration file contains
information such as:
@itemize
@item the default source naming conventions for each language,
@item the compiler name, location and required options,
@item how to compute inter-unit dependency,
@item how to build static or dynamic libraries,
@item which post-compilation actions are needed,
@item how to link together units from different languages.
@end itemize

@noindent
On the other hand, @code{GPRbuild} is not a replacement for general-purpose
build tools such as @code{make} or @code{ant} which give the user a high
level of control over the build process itself. When building a system
requires complex actions that do not fit well in the three-phase process
described above, @code{GPRbuild} might not be sufficient.
In such situations, @code{GPRbuild} can still
be used to manage the appropriate part of the build. For
instance it can be called from within a Makefile.

@c  ------------------------------------------------------------------------
@node Guided Tour
@chapter Guided Tour
@c  --------------------------------------------------------------------------

@menu
* Configuration::
* First Steps::
* Subsystems::
* Project Extensions::
* Libraries::
* Scenarios and conditional source files::
@end menu

This chapter presents examples ranging from simple
multi-language builds to some of the most advanced scenarios.
All the examples shown in the text are included
in the GPRbuild package, which is installed on your
system in @file{<prefix>/share/examples/gprbuild/}.

@node Configuration
@section Configuration

GPRbuild requires one configuration file describing the languages and
toolchains to be used, and project files describing the
characteristics of the user project. Typically the configuration
file can be created automatically by @code{GPRbuild} based on the languages
defined in your projects and the compilers on your path. In more
involved situations -- such as cross compilation, or
environments with several compilers for the same language --
you may need to control more precisely the generation of
the desired configuration of toolsets. A tool, @value{gprconfig}, described in
@ref{Configuring with GPRconfig}), offers this capability. In this
chapter most of the examples can use autoconfiguration.

GPRbuild will start its build process by trying to locate a configuration
file called @file{default.cgpr}.
@CINDEX{@file{default.cgpr} configuration file}
@CINDEX{@option{--autoconf} option (to GPRbuild)}
If such a file is not available or if the option
@code{--autoconf=xxx} is used, GPRbuild will create its own configuration
file suitable for native development and assuming that there are known
compilers on your path for each of the necessary languages. It is
preferable and often necessary to manually generate your own
configuration file when:
@itemize
@item using cross compilers (in which case you need to use gprconfig's
@option{--target=}) option,
@item using a specific Ada runtime (e.g. @option{--RTS=sjlj}),
@item working with compilers not in the path or not first in the path, or
@item autoconfiguration does not give the expected results.
@end itemize

@noindent
@value{gprconfig} provides several ways of generating configuration files. By
default, a simple interactive mode lists all the known compilers for all
known languages. You can then select a compiler for each of the languages;
once a compiler has been selected, only compatible compilers for other
languages are proposed. Here are a few examples of @value{gprconfig}
invocation:
@itemize
@item
The following command triggers interactive mode. The configuration will be
generated
in GPRbuild's default location,
@code{<gprbuild_install_root>/share/gpr/default.cgpr)}
@smallexample
 gprconfig
@end smallexample
@item
The first command below also triggers interactive mode, but the resulting
configuration
file has the name and path selected by the user. The second command shows
how GPRbuild can make use of this specific configuration file instead of
the default one.
@smallexample
 gprconfig -o path/my_config.cgpr
 gprbuild --config=path/my_config.cgpr
@end smallexample

@item
The following command again triggers interactive mode, and only the relevant
cross compilers for target ppc-elf will be proposed.
@smallexample
 gprconfig --target=ppc-elf
@end smallexample

@item
The next command triggers batch mode and generates at the default location
a configuration file using the first native Ada and C compilers on the
path.
@smallexample
 gprconfig --config=Ada --config=C --batch
@end smallexample

@item
The next command, a combination of the previous examples, creates in
batch mode a configuration file named @file{x.cgpr} for cross-compiling
Ada with a run-time called @code{hi} and using C for the LEON processor.
@smallexample
 gprconfig --target=leon-elf --config=Ada,,hi --config=C --batch -o x.cgpr
@end smallexample
@end itemize


@node First Steps
@section First Steps

Assume a simple case of interfacing between Ada and C where the main
program is first in Ada and then in C. For a main program in Ada the
following project may be used:

@smallexample @c projectfile
project Ada_Main is
   for Languages    use ("Ada", "C");
   for Source_Dirs  use ("ada_src", "util_src");
   for Object_Dir   use  "obj";
   for Exec_Dir     use ".";
   for Source_Files use ("ada_main.adb", "c_lib.ads", "lib.h", "lib.c");
   for Main         use ("ada_main.adb");
end Ada_Main;
@end smallexample

@noindent
This project indicates that:
@itemize
@item the sources files of this subsystem are written in Ada and C.
@item the directories containing the sources are @code{ada_src} and
@code{util_src}.
@item the directory for the objects is @code{obj}.
@item the directory for the executables is ``.''; i.e., the
directory containing the project file itself.
@item the complete list of source files is @code{ada_main.adb},
@code{c_lib.ads}, @code{lib.h}, @code{lib.c}. They can be found anywhere
in the source directories mentioned above.
@item the main entry point of the system is in the source file
@code{ada_main.adb}.
@end itemize

@noindent
This information is sufficient for @code{GPRbuild} to build an executable
program from the sources. Note that no direct indication on how to build
the various elements is given in the project file, which describes
the project properties rather than a set of actions to
be executed. Here is the invocation of
@code{GPRbuild} that allows building the multi-language program:
@smallexample
$ gprbuild -Pada_main
gcc -c ada_main.adb -o ada_main.o
gcc -c c_lib.ads -o c_lib.o
gcc -c lib.c -o lib.o
gprbind ada_main
...
gcc ada_main.o -o ada_main.exe
@end smallexample

@noindent
Notice the three steps described in the @ref{Introduction}:
@itemize
@item
The first three gcc commands correspond to the compilation phase.
@item
The gprbind
command corresponds to the post-compilation phase.
@item
The last gcc command
corresponds to the final link.
@end itemize

@noindent
The default output of
GPRbuild's execution is kept reasonably simple and easy to understand.
In particular, some of the less frequently used commands
are not shown, and some parameters are abbreviated. GPRbuild's option
@code{-v}
@CINDEX{@option{-v} option (for GPRbuild)}
provides a much more verbose output which includes, among other
information, more complete compilation, post-compilation and
link commands.

To illustrate some other GPRbuild capabilities, here is a slightly different
project using similar sources and a main program in C:

@smallexample @c projectfile
project C_Main is
   for Languages    use ("Ada", "C");
   for Source_Dirs  use ("c_src", "util_src");
   for Object_Dir   use  "obj1";
   for Main         use ("c_main.c");
   package Compiler is
      C_Switches := ("-pedantic");
      for Default_Switches ("C")   use C_Switches;
      for Default_Switches ("Ada") use ("-gnaty");
      for Switches ("c_main.c")    use C_Switches & ("-g");
   end Compiler;
end C_Main;
@end smallexample

@noindent
This project has many similarities with the previous one, as evident in
the @code{Languages},
@code{Source_Dirs} and @code{Object_Dirs} attributes.
As expected, its @code{Main} attribute
now refers to a C source. The first noticeable difference is the lack of a
@code{Source_Files} attribute. When not specified explicitly, this attribute
has
an implicit value which is the complete set of sources of the given
@code{Languages} to
be found in @code{Source_Dirs}. Many attributes can be left implicit and will
be given
reasonable default values. For instance, @code{Source_Dirs} and
@code{Object_Dir}
default to the current directory (where the project file resides). The
@code{Exec_Dir} attribute defaults to the value of @code{Object_Dir}.

The other notable difference in this new project is the presence of the
package @code{Compiler}, which groups the attributes specific to
the compilation phases. The @code{Default_Switches} attribute provides the
list of compilation switches to be used for any source of a given
@code{Languages} value unless the source has its own set of compilation
switches
specified by the attribute @code{Switches}. Note also the use of a the
variable
@code{C_Switches}. A project variable can be useful to avoid duplication of
information and
here ensures that the file @file{c_main.c} is always compiled
with the default switches (whatever they may be), plus @option{-g}. In this
specific
situation the use of a variable could have been replaced by a reference
to the @code{Default_Switches} attribute:

@smallexample @c projectfile
   for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g");
@end smallexample

@noindent
Here is the output of the GPRbuild command using this project:

@smallexample
$gprbuild -Pc_main
gcc -c -pedantic -g c_main.c -o c_main.o
gcc -c -gnaty ada_lib.adb -o ada_lib.o
gcc -c -gnaty c_lib.ads -o c_lib.o
gcc -c -pedantic lib.c -o lib.o
gprbind c_main
...
gcc c_main.o -o c_main.exe
@end smallexample

@noindent
The switches for compiling Ada sources,
the default switches for C sources in the compilation of @file{lib.c},
and the specific switches for @file{c_main.c} have all been taken into
account.
When comparing this GPRbuild output with the previous one,
notice that there are common sources between the two projects, namely
@file{c_lib.ads} and @file{lib.c}. Those sources were compiled twice, once for
each
project. This is not surprising, since the two projects
are independent and have different @code{Object_Dir}s even though they share
some sources. It is possible to share more than the sources, and thus
avoid unnecessary recompilations when compilation units are
used in several different projects, by splitting a system into
subsystems.

@node Subsystems
@section Subsystems
@c describe a bigger project with several source dirs and object dirs
@c describe limited with & extended projects & source duplication.

The common compilation units may be grouped in a separate subsystem with
its own project file and a specified @code{Object_Dir} attribute:

@smallexample @c projectfile
project Common_Subsystem is
   for Source_Dirs  use ("util_src");
   for Object_Dir   use  "obj_util";
end Common_Subsystem;
@end smallexample

@noindent
By default, all the sources in directory @code{util_src} belong to
project @code{Common_Subsystem}, and when compiled, their objects go in
@code{obj_dir}.
Other projects, whose sources depend on sources in @code{util_src}, can create
a dependency relationship using a project @code{with} clause:

@smallexample @c projectfile
with "Common_Subsystem";
project Ada_Main is
   for Languages    use ("Ada");
   for Source_Dirs  use ("ada_src");
   ...
end Ada_Main;
@end smallexample

@noindent
The @code{Ada_Main.Source_Dirs} no longer includes @code{util_src}. The
main program in @code{ada_src} still needs sources from @code{util_src} to be
compiled.
It also needs those units built. Now they will be compiled using the build
properties defined in @code{Common_Subsystem} instead of those of
@code{Ada_Main}.

The
project's @code{with} clause has several effects. It provides visibility of
sources during the compilation process as if the units from @code{Ada_Main}
were
compiled with an implicit @code{-Iutil_src} option. It also guarantees that the
necessary units from @code{Common_Subsystem} are available for
@code{Ada_Main}'s linking
phase.

It is also possible to use the @code{with} relationship to define a project
file that allows sharing common attributes or packages. For instance, you
can define a project whose only purpose is to centralize the default
compilation options for various languages:

@smallexample @c projectfile
abstract project Attribute_Sharing is
   for Source_Files use ();
   package Compiler is
      for Default_Switches ("C")   use ("-pedantic");
      for Default_Switches ("Ada") use ("-gnaty");
   end Compiler;
end Attribute_Sharing;
@end smallexample

@noindent
This package does not correspond to a subsystem with
proper source files, and this is conveyed by the modifier @code{abstract}
just before the keyword @code{project}. An abstract project cannot have
associated sources, hence the definition of @code{Source_Files}
as the empty list. It informs the build manager that no compilation is to
take place directly from this project. Defining an empty list of sources is
essential for such utility projects because otherwise the default rules
would apply and all sources in the current directory would be associated
with this project. Now other projects can share this project's attributes
and packages. For instance, @code{Ada_Main} can share all the
@code{Compiler} package's attributes at once using a renaming declaration:

@smallexample @c projectfile
with "Attribute_Sharing";
...
project Ada_Main is
...
   package Compiler renames Attribute_Sharing.Compiler;
end Ada_Main;
@end smallexample

@noindent
or if other aspects of the @code{Compiler} package need to be defined locally,
such as adding @code{-g} for the @file{c_main.c} source only, sharing can be
done at the
attribute level directly as in this new version of @code{C_Main.Compiler}:
@smallexample @c projectfile
   package Compiler is
      for Default_Switches ("C") use
        Attribute_Sharing.Compiler'Default_Switches ("C");
      for Switches ("c_main.c")  use
        Compiler'Default_Switches ("C") & ("-g");
   end Compiler;
@end smallexample

@noindent
In order to change the compilation options of all C files used for
building both @code{C_Main} and @code{Ada_Main}, it is sufficient to edit a
single project file.

@node Project Extensions
@section Project Extensions

Previous sections have shown how to share both compilation units and project
properties
among different systems. Sharing is an essential aspect of large system
development since it avoids unnecessary duplication, reduces compilation time
and
lessens the maintenance burden. Unfortunately, it sometimes gets in the way.
In the above example, @code{Ada_Main} and @code{C_Main} both depend on
@code{Common_Subsystems} because they have precisely the same needs, but the
requirements of the two systems can diverge over time in which case
sharing becomes a problem rather than a solution. For instance,
suppose that @code{C_Main} is now baselined and should not be changed,
while @code{Ada_Main} is still under active development (which requires
changes in the sources of the common subsystem). The issue is how to satisfy
@code{Ada_Main}'s needs without taking any risk of perturbing @code{C_Main}.
One
possibility is to duplicate the common subsystem completely so that one
version can evolve while the other one can remain frozen. That will force
duplication and recompilation of the whole project. Extensions provide a
more flexible mechanism, making it possible to provide a new version of
a subsystem without having to duplicate the sources that do not change.
A project extension inherits all the sources and objects from the project it
extends and allows you to redefine some of the sources which hide the original
versions. You can also add new sources or remove existing ones.
Here is an example of extending project @code{Common_Subsystem}:

@smallexample @c projectfile
project New_Common_Subsystem
        extends "../subsystems/common_subsystem.gpr" is
   for Source_Dirs  use ("new_util_src");
   for Object_Dir   use  "new_obj_util";
end New_Common_Subsystem;
@end smallexample

@noindent
The project sources are to be found in @code{Common_Subsystem.Source_Dirs}
and @code{New_Common_Subsystem.Source_Dirs}, the latter hiding the former
when the same source filenames are found in both. New sources can be
added to the project extension by simply placing them in its
@code{Source_Dirs}. Original sources can be removed, because of the attribute
@code{Excluded_Source_Files}.
When building a project extension, all units depending on new versions of
sources are rebuilt in the extension's @code{Object_Dir}. Other objects
remain in their original location and will be used by the builder whenever
necessary.

A project extension can
be used in the context of a large program composed of many subsystems.
Extending one subsystem may implicitly affect many other subsystems
depending on it, even though there are no source changes in those
dependent projects. In order to avoid the need  to generate a
project extension for each of the affected subsystems, you can use the
notion of ``extending all'', which basically means ``extend all the projects
necessary so that this specific project extension can be used instead of
its original version''. Here is an example of an extending-all project:

@smallexample @c projectfile
with "new_common_subsystem.gpr";
project New_Ada_Main extends all "../subsystems/ada_main.gpr" is
   for Source_Dirs  use ("new_ada_src");
   for Object_Dir   use  "new_obj";
   for Exec_Dir     use ".";
end New_Ada_Main;
@end smallexample

@node Libraries
@section Libraries

A library is a subsystem packaged in a specific way. There are two
major kinds of libraries: @emph{static} and @emph{dynamic}. A project file
representing
a library is very similar to a project file representing a subsystem. You
just need to give the library a name, through the attribute
@code{Library_Name}. It is also possible to define a @code{Library_Dir}
which allows you to separate the final library components (e.g. archive files)
from the compilation byproducts (e.g. object files) that may be needed
to efficiently rebuild a new version of the library but which are not of any
interest to library users. Here is a simple project file for a static
library:

@smallexample @c projectfile
library project Static_Lib is
   for Languages    use ("Ada", "C");
   for Source_Dirs  use ("lib_src");
   for Object_Dir   use "obj";
   for Library_Dir  use "lib";
   for Library_Kind use "static";
   for Library_Name use "l1";
end Static_Lib;
@end smallexample

@noindent
The library can be built on its own using standard GPRbuild commands,
for example:
@smallexample
$gprbuild static_lib.gpr
@end smallexample

@noindent
It can also be built as a by product of building a main project using this
library through a "with" as it was the case for simple subsystems:
@smallexample @c projectfile
with "static_lib.gpr";
project Main is
   for Main  use ("ada_main.adb");
end Main;
@end smallexample

@noindent
in which case

@smallexample
$gprbuild main.gpr
@end smallexample

@noindent
will rebuild the library @code{l1} if it is not up to date.

To construct a dynamic library instead of a static library, simply replace
@smallexample @c projectfile
   for Library_Kind use "static";
@end smallexample

@noindent
by

@smallexample @c projectfile
   for Library_Kind use "dynamic";
@end smallexample

@noindent
Library projects can also be useful to describe a library that you may
want to use but that, for some reason, cannot be rebuilt,
for instance when the sources to rebuild the library are
not available. Such library projects need simply to use the
@code{externally_built} attribute as in the example below:
@smallexample @c projectfile
library project Extern_Lib is
   for Languages    use ("Ada", "C");
   for Source_Dirs  use ("lib_src");
   for Library_Dir  use "lib2";
   for Library_Kind use "dynamic";
   for Library_Name use "l2";
   for Externally_Built use "true";
end Extern_Lib;
@end smallexample

@noindent
In the case of externally built libraries, the @code{Object_Dir}
attribute does not need to be specified in this case because
it will never be used.

@node Scenarios and conditional source files
@section Scenarios and conditional source files

@noindent
In the previous section we have seen how to create libraries from
simple subsystems by using specific attributes. Rather than having
several almost identical project files defining a static or a dynamic
version of the library representing a subsystem, one can write a more
generic version of the project file thanks to the notion of scenarios.
Scenarios are defined as types with a known set of string values as shown
by the type @code{Lib_Kind} below. A scenario variable,@code{Kind} below
can get its initial value from the environment thanks to an @code{external}
call. This variable can then be used in a case statement as shown below.
Note that only scenario variables can be used to control case statements.
There is another kind of untyped string variables illustrated by
@code{Prefix} below that can be used in general string expressions but
cannot control case statements and thus are not scenarios variables.

@smallexample @c projectfile
library project General_Lib is
   type Lib_Kind is ("static", "dynamic", "extern");
   Kind : Lib_Kind := external ("LIB", "static");
   Prefix := "../libraries/";
   for Languages    use ("Ada", "C");
   for Source_Dirs  use (Prefix & "lib_src");
   case Kind is
      when "static" =>
         for Object_Dir   use  Prefix & "obj";
         for Library_Dir  use  Prefix & "lib";
         for Library_Kind use  "static";
         for Library_Name use "l1";
      when "dynamic" =>
         for Object_Dir   use  Prefix & "obj2";
         for Library_Dir  use  Prefix & "lib2";
         for Library_Kind use  "dynamic";
         for Library_Name use "l2";
      when "extern" =>
         for Library_Dir  use  Prefix & "lib2";
         for Library_Kind use "dynamic";
         for Library_Name use "l2";
         for Externally_Built use "true";
   end case;
end General_Lib;
@end smallexample


@c  ------------------------------------------------------------------------
@node Important Concepts
@chapter Important Concepts
@c  ------------------------------------------------------------------------

The following concepts are the foundation of
GNAT Project files and the GPRbuild process.

@itemize @bullet

@item Source files and source directories

A source file is associated with a language through a naming convention.
For instance, @code{foo.c} is typically
the name of a C source file; @code{bar.ads} or @code{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.
You can define or modify the naming conventions,
which are used by
@code{GPRbuild} to invoke the appropriate compiler.
Source files are looked up in the source directories associated with the
project through the @code{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 @code{Source_Files} or
@code{Source_List_File} attributes.

@item Object files and object directory

An object file is an intermediate file produced by the compiler from a
compilation unit. It is used by the post-compilation phases to produce
final executables or libraries. The object files produced in the context of
a given project are stored in a single directory, the @code{Object_Dir} that
can
be specified in the project file. A need for storing
objects in different directories corresponds to the need to split the
system into distinct subsystems.

@item Project file

A text file using an Ada-like syntax. It defines build-related
characteristics of an application, or a part of it. 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 default options for the various tools involved in the build
process. These characteristics can be conditionalized through scenario
variables and case statements.

@item Configuration file

A text file using the project file syntax. It defines languages and
their characteristics as well as toolchains for those languages and their
characteristics.

@item Project attribute

A specific characteristic as defined by a project attribute clause. Its
value is a string or a sequence of strings. For instance, the
@code{Source_Dirs}
attribute is a sequence of strings representing the actual names of the
directories containing the sources of the project. The attribute itself can
be parameterized. For instance @code{Compiler'Default_Options ("Ada")}
refers to the default compiler options for the Ada language.

@item Project subpackage

Global characteristics are defined at the top level of a project.
Specific characteristics affecting a given tool are grouped in a
subpackage with the same name as the tool. The most common
subpackages are @code{Builder}, @code{Compiler}, @code{Binder},
and @code{Linker}.

@item Project variables

Two kinds of variables are available with projects: simple variables and
scenario variables. A simple variable can hold any string, or sequence of string
values; this is useful as a shortcut for a complex expression. Scenario
variables are a restricted version of simple variables; they can only take their
values from a static enumeration of strings representing the various
supported scenarios. These scenario variables are used in conjunction with
the @code{case} construct to offer limited conditionalization of
project characteristics. Both types of variables are local to the project
defining them and can get initialized with an external value, such as
an environment variable, through the @code{external} directive.

@item Subsystem

A subsystem is a coherent part of the complete system to be built. It
is represented by a set of sources and one object directory. A simple
system is composed of a single subsystem. Complex systems are usually
composed of a graph of interdependent subsystems. A subsystem is
dependent on another subsystem if knowledge of the other one is
required to build it, and in particular if visibility on some of the
sources of this other subsystem is required. A subsystem is usually
represented by one project file. The subsystem dependency relationship
is represented by the @code{with} clause between corresponding project
files.

@item Library

A library is a specific type of subsystem where, for convenience, you group
the objects together using system-specific means.
Project files are a system- and language-independent way of
building both static and dynamic libraries. They also support the concept
of standalone libraries (SAL) which offers two significant properties: the
initialization of the library is either automatic or very simple; a
change in the implementation part of the library implies minimal
post-compilation actions on the complete system and potentially no
action at all for dynamic SALs.

@item Project extension

A project extension is a project that represents an augmentation
of the original project. Suppose for instance that a
subsystem @code{S} is shared by two unrelated systems @code{S1} and @code{S2}.
If @code{S1} requires a
change in @code{S}, but this change would adversely affect @code{S2},
then a modified version of @code{S} can be defined as an extension of
@code{S}, a ``delta'' to the original
version which only contains the new source files (those that have been
changed) and the objects that are affected by these changes.
@end itemize

@c  ------------------------------------------------------------------------
@node Building with GPRbuild
@chapter Building with GPRbuild
@c  ------------------------------------------------------------------------

@menu
* Command Line::
* Switches::
* Initialization::
* Compilation of one or several sources::
* Compilation Phase::
* Post-Compilation Phase::
* Linking Phase::
@end menu

@node Command Line
@section Command Line

@noindent
Three elements can optionally be specified on GPRbuild's command line:
@itemize
@item the main project file,
@item the switches for GPRbuild itself or for the tools it
drives, and
@item the main source files.
@end itemize

@noindent
The general syntax is thus:
@smallexample
gprbuild [<proj>.gpr] [switches] [names]
  @{[-cargs opts] [-cargs:lang opts] [-largs opts] [-gargs opts]@}
@end smallexample

@noindent
GPRbuild requires a project file, which may be specified on the
command line, either directly or through the @option{-P} switch. If not
specified, then GPRbuild uses the project file @file{default.gpr} if there
is one in the current working directory. Otherwise, if there is only
one project file in the current working directory, GPRbuild uses this
project file.

Main source files represent the sources to be used as the main
programs. If they are not specified on the command line, GPRbuild uses
the source files specified with the @code{Main} attribute in the project
file. If none exists, then no executable will be built.

When source files are specified along with the option @option{-c}, then
recompilation will be considered only for those source files. In all
other cases, GPRbuild compiles or recompiles all sources in the
project tree that are not up to date, and builds or rebuilds libraries
that are not up to date.

If invoked without the @option{--config=} or
@option{--autoconf=} options, then GPRbuild will look for a configuration
project file @file{default.cgpr}, or @file{<targetname>.cgpr} if option
@option{--terget=<targetname>} is used. If there is no such file in the default
locations expected by GPRbuild (<install>/share/gpr and the current
directory) then GPRbuild will invoke @value{gprconfig} with
the languages from the project files, and create a configuration project
file @file{auto.cgpr} in the object directory of the main project. The project
@file{auto.cgpr} will be rebuilt at each GPRbuild invocation unless you use
the switch @option{--autoconf=path/auto.cgpr}, which will use the configuration
project file if it exists and create it otherwise.

Options given on the GPRbuild command line may be passed along to
individual tools by preceding them with one of the ``command line
separators'' shown below. Options following the separator, up to the
next separator (or end of the command line), are passed along.  The
different command line separators are:

@itemize @bullet

@item @option{-cargs}

The arguments that follow up to the next command line separator are
options for all compilers for all languages.
Example: @option{-cargs -g}

@item @option{-cargs:<language name>}

The arguments that follow up to the next command line separator are
options for the compiler of the specific language.

Examples:
@itemize
@item @option{-cargs:Ada -gnatf}
@item @option{-cargs:C -E}
@end itemize

@item @option{-bargs}

The arguments that follow up to the next command line separator are
options for all binder drivers.

@item @option{-bargs:<language name>}

The arguments that follow up to the next command line separators are
options for the binder driver of the specific language.

Examples:
@itemize
@item @option{-bargs:Ada binder_prefix=ppc-elf}
@item @option{-bargs:C++ c_compiler_name=ccppc}
@end itemize

@item @option{-largs}

The arguments that follow up to the next command line separator are
options for the linker.

@item @option{-gargs}

The arguments that follow up to the next command line separator are
options for GPRbuild itself. Usually @option{-gargs} is specified after one or
several other command line separators.

@end itemize

@node Switches
@section Switches

@noindent
The switches that are interpreted directly by GPRbuild are listed below.

First, the switches that may be specified only on the command line, but not in
package Builder of the main project:

@itemize @bullet

@item @option{--version}

Display information about GPRbuild: version, origin and legal status, then
exit successfully, ignoring other options.

@item @option{--help}

Display GPRbuild usage, then exit successfully, ignoring other options.

@item @option{--display-paths}

Display two lines: the configuration project file search path and the user
project file search path, then exit successfully, ignoring other options.

@item @option{--config=<config project file name>}

This specifies the configuration project file name. By default, the
configuration project file name is @file{default.cgpr}. Option @option{--config=}
cannot be specified more than once. The configuration project file specified
with @option{--config=} must exist.

@item @option{--autoconf=<config project file name>}

This specifies a configuration project file name that already exists
or will be created automatically. Option @option{--autoconf=} cannot
be specified more than once. If the configuration project file
specified with @option{--autoconf=} exists, then it is
used. Otherwise, @value{gprconfig} is invoked to create it automatically.

@item @option{--target=<targetname>}

This specifies that the default configuration project file is
@file{<targetname>.cgpr}. If no configuration project file with this name
is found, then @value{gprconfig} is invoked with option
@option{--target=<targetname>}to create a configuration project file
@file{auto.cgpr}.

Note: only one of @option{--config}, @option{--autoconf} or @option{--target=}
can be specified.

@item @option{--subdirs=<subdir>}

This indicates that the real directories (except the source directories) are
subdirectories of the directories specified in the project files. This applies
in particular to object directories, library directories and exec directories.
If the directories do not exist, they are created automatically.

@item @option{--direct-import-only}

This indicates that sources of a project should import only sources or
header files from directly imported projects, that is those projects mentioned
in a with clause and the projects they extend directly or indirectly.
A check is done in the compilation phase, after a successful compilation, that
the sources follow these restrictions. For Ada sources, the check is fully
enforced. For non Ada sources, the check is partial, as in the dependency
file there is no distinction between header files directly included and those
indirectly included. The check will fail if there is no possibility that a
header file in a non directly imported project could have been indirectly
imported. If the check fails, the compilation artifacts (dependency file,
object file, switches file) are deleted.

@item @option{-aP dir} (Add directory @file{dir} to project search path)

Specify to GPRbuild to add directory @file{dir} to the user project file search
path, before the default directory.

@item @option{-b} (Bind only)

Specify to GPRbuild that the post-compilation (or binding) phase is to be
performed, but not the other phases unless they are specified by appropriate
switches.

@item @option{-c} (Compile only)

Specify to GPRbuild that the compilation phase is to be performed, but not
the other phases unless they are specified by appropriate switches.

@item @option{-d} (Display progress)

Display progress for each source, up to date or not, as a single
line @emph{completed x out of y (zz%)...}. If the file needs to be compiled
this is displayed after the invocation of the compiler. These lines are
displayed even in quiet output mode (switch @option{-q}).

@item @option{-eL} (Follow symbolic links when processing project files)

By default, symbolic links on project files are not taken into account
when processing project files. Switch @option{-eL} changes this default
behavior.

@item @option{-F} (Full project path name in brief error messages)

By default, in non verbose mode, when an error occurs while processing
a project file, only the simple name of the project file is displayed in the
error message. When switch @option{-F} is used, the full path of the project
file is used. This switch has no effect when switch @option{-v} is used.

@item @option{-l} (Link only)

Specify to GPRbuild that the linking phase is to be performed, but not
the other phases unless they are specified by appropriate switches.

@item @option{-o name} (Choose an alternate executable name)

Specify the file name of a single executable. Switch @option{-o} cannot be
used with
several mains on the command line, nor with no main on the command line and
several mains in attribute @code{Main} of the main project.

@item @option{-p} or @option{--create-missing-dirs} (Create missing object, library and exec directories)

By default, GPRbuild checks that the object, library and exec directories
specified in project files exist. Switch @option{-p} instructs GPRbuild to
attempt to create missing directories.

@item @option{-P proj} (use Project file @emph{proj})

Specify the path name of the main project file. The space between @option{-P}
and the project file name is optional. Specifying a project file name (with
suffix @file{.gpr}) may be used in place of option @option{-P}. Exactly one main
project file can be specified.

@item @option{-u} (Unique compilation, only compile the given files)

If there are sources specified on the command line, only compile these
sources. If there are no sources specified on the command line, compile
all the sources of the main project.

In both cases, do not attempt the binding and the linking phases.

@item @option{-U} (Compile all sources of all projects)

If there are sources specified on the command line, only compile these
sources. If there are no sources specified on the command line, compile
all the sources of all the projects in the project tree.

In both cases, do not attempt the binding and the linking phases.

@item @option{-vPx} (Specify verbosity when parsing Project Files)

By default, GPRbuild does not display anything when processing project files,
except when there are errors. This default behavior is obtained with switch
@option{-vP0}. Switches @option{-vP1} and @option{-vP2} yield increasingly
detailed output.

@item @option{-Xnm=val} (Specify an external reference for Project Files)

Specify an external reference that may be queried inside the project files
using built-in function @code{external}. For example, with
@option{-XBUILD=DEBUG},
@code{external("BUILD")} inside a project file will have the value
@code{"DEBUG"}.

@end itemize

Then, the switches that may be specified on the command line as well as in
package Builder of the main project (attribute Switches):

@itemize @bullet

@item @option{-f} (Force recompilations)

Force the complete processing of all phases (or of those explicitly specified)
even when up to date.

@item @option{-j<num>} (use @emph{num} simultaneous compilation jobs)

By default, GPRbuild invokes one compiler at a time. With switch @option{-j},
it is possible to instruct GPRbuild to spawn several simultaneous compilation
jobs if needed. For example, @option{-j2} for two simultaneous compilation
jobs or @option{-j4} for four.

@item @option{-k} (Keep going after compilation errors)

By default, GPRbuild stops spawning new compilation jobs at the first
compilation failure. Using switch @option{-k}, it is possible to attempt to
compile/recompile all the sources that are not up to date, even when some
compilations failed. The post-compilation phase and the linking phase are never
attempted if there are compilation failures, even when switch @option{-k} is
used.

@item @option{-q} (Quiet output)

Do not display anything except errors and progress (switch @option{-d}).
Cancel any previous switch @option{-v}.

@item @option{-s} (recompile if compilation switches have changed)

By default, GPRbuild will not recompile a source if all dependencies are
satisfied. Switch @option{-s} instructs GPRbuild to recompile sources when a
different set of compilation switches has been used in the previous
compilation, even if all dependencies are satisfied. Each time GPRbuild
invokes a compiler, it writes a text file that lists the switches used in the
invocation of the compiler, so that it can retrieve these switches if
@option{-s} is used later.

@item @option{-v} (Verbose output)

Display full paths, all options used in spawned processes, and reasons why
these processes are spawned. Cancel any previous switch @option{-q}.

@item @option{-we} (Treat all warnings as errors)

When @option{-we} is used, any warning during the processing of the project
files becomes an error and GPRbuild does not attempt any of the phases.

@item @option{-wn} (Treat warnings as warnings)

Switch @option{-wn} may be used to restore the default after @option{-we} or
@option{-ws}.

@item @option{-ws} (Suppress all warnings)

Do not generate any warnings while processing the project files.

@end itemize

@node Initialization
@section Initialization

@noindent
Before performing one or several of its three phases, GPRbuild has to read the
command line, obtain its configuration, and process the project files.

If GPRbuild is invoked with an invalid switch or without any project file on
the command line, it will fail immediately.

Examples:

@smallexample
$ gprbuild -P
gprbuild: project file name missing after -P

$ gprbuild -P c_main.gpr -WW
gprbuild: illegal option "-WW"
@end smallexample

@noindent
GPRbuild looks for the configuration project file first in the current
working directory, then in the default configuration project directory.
If the GPRbuild executable is located in a subdirectory @file{<prefix>/bin},
then
the default configuration project directory is @file{<prefix>/share/gpr},
otherwise there is no default configuration project directory.

When it has found its configuration project path, GPRbuild needs to obtain its
configuration. By default, the file name of the main configuration project
is @file{default.cgpr}. This default may be modified using the switch
@option{--config=...}

Example:

@smallexample
$ gprbuild --config=my_standard.cgpr -P my_project.gpr
@end smallexample

@noindent
If GPRbuild cannot find the main configuration project on the configuration
project path, then it will look for all the languages specified in the user
project tree and invoke @value{gprconfig} to create a configuration project file
named @file{auto.cgpr} that is located in the object directory of the main
project file.

Once it has found the configuration project, GPRbuild will process its
configuration: if a single string attribute is specified in the configuration
project and is not specified in a user project, then the attribute is added
to the user project. If a string list attribute is specified in the
configuration project then its value is prepended to the corresponding
attribute in the user project.

After GPRbuild has processed its configuration, it will
process the user project file or files. If these user project files are
incorrect then GPRbuild will fail with the appropriate error messages:

@smallexample
$ gprbuild -P my_project.gpr
ada_main.gpr:3:26: "src" is not a valid directory
gprbuild: "my_project.gpr" processing failed
@end smallexample

@noindent
Once the user project files have been dealt with successfully, GPRbuild
will start its processing.

@node Compilation of one or several sources
@section Compilation of one or several sources

If GPRbuild is invoked with -c and there are one or several source file names
specified on the command line, GPRbuild will compile or recompile these
sources, if they are not up to date or if -f is also specified.
Then GPRbuild will stop its execution, even if -b or -l are specified.

The options/switches used to compile these sources are described in section
@ref{Compilation Phase}.

@node Compilation Phase
@section Compilation Phase

When switch @option{-c} is used or when switches @option{-b} or @option{-l}
are not used, GPRbuild will first compile or recompile all the sources that
are not up to date in all the projects in the project tree.

GPRbuild will first consider each source and decide if it needs to be
(re)compiled.

A source needs to be compiled in the following cases:

@itemize @bullet

@item Switch @option{-f} (force recompilations) is used

@item The object file does not exist

@item The source is more recent than the object file

@item The dependency file does not exist

@item The source is more recent than the dependency file

@item The switch file does not exist

@item The source is more recent than the switch file

@item The dependency file cannot be read

@item The dependency file is empty

@item The dependency file has a wrong format

@item A source listed in the dependency file does not exist

@item A source listed in the dependency file has an incompatible time stamp

@item A source listed in the dependency file has been replaced

@item Switch @option{-s} is used and the source has been compiled with
different switches or with the same switches in a different order

@end itemize

@noindent
When a source is successfully compiled, the following files are normally
created in the object directory of the project of the source:

@itemize @bullet

@item An object file

@item A dependency file, except when the dependency kind for the language
      is @code{none}

@item A switch file

@end itemize

@noindent
The compiler for the language of the source is invoked with the following
switches/options:

@itemize @bullet

@item The required compilation switches for the language

@item The compilation switches coming from package @code{Compiler} of the
project of the source

@item The compilation switches specified on the command line for all compilers,
      after @option{-cargs}

@item The compilation switches for the language of the source, specified
      after @option{-cargs:<language>}

@item Various other options including a switch to create the dependency file
      while compiling, a switch to specify a configuration file, a switch
      to specify a mapping file, and switches to indicate where to look for
      other source or header files that are needed to compile the source.

@end itemize

@noindent
If compilation is needed, then all the options/switches, except those
described as ``Various other options'' are written to the switch file.
The switch file is a text file. Its file name is obtained by replacing
the suffix of the source with @file{.cswi}. For example, the switch file
for source @file{main.adb} is @file{main.cswi} and for
@file{toto.c} it is @file{toto.cswi}.

If the compilation is successful, then if the creation of the dependency
file is not done during compilation but after (see configuration attribute
@code{Compute_Dependency}), then the process to create the dependency file is
invoked.

If GPRbuild is invoked with a switch @option{-j} specifying more than one
compilation process, then several compilation processes for several sources of
possibly different languages are spawned concurrently.

For each project file, attribute Interfaces may be declared. Its value is a
list of sources or header files of the project file. For a project file
extending another one, directly or indirectly, inherited sources may be in
the list. When Interfaces is not declared, all sources or header files are
part of the interface of the project. When Interfaces is declared, only those
sources or header files are part of the interface of the project file. After
a successful compilation, gprbuild checks that all imported or included sources
or header files that are from an imported project are part of the interface of
the imported project. If this check fails, the compilation is invalidated and
the compilation artifacts (dependency, object and switches files) are deleted.

Example:

@smallexample
   project Prj is
      for Languages use ("Ada", "C");
      for Interfaces use ("pkg.ads", "toto.h");
   end Prj;
@end smallexample

If a source from a project importing project Prj imports sources from Prj other
than package Pkg or includes header files from Prj other than "toto.h", then
its compilation will be invalidated.

@node Post-Compilation Phase
@section Post-Compilation Phase

@noindent
@emph{To be provided in a subsequent version of the document.}


@node Linking Phase
@section Linking Phase

@noindent
@emph{To be provided in a subsequent version of the document.}

@c  ------------------------------------------------------------------------
@node Cleaning up with GPRclean
@chapter Cleaning up with GPRclean
@c  ------------------------------------------------------------------------

@menu
* Switches for GPRclean::
@end menu

The GPRclean tool removes the files created by GPRbuild.
At a minimum, to invoke GPRclean you must specify a main project file
in a command such as @code{gprclean proj.gpr} or @code{gprclean -P proj.gpr}.

Examples of invocation of GPRclean:

@smallexample
   gprclean -r prj1.gpr
   gprclean -c -P prj2.gpr
@end smallexample

@node Switches for GPRclean
@section Switches for GPRclean

The switches for GPRclean are:

@itemize @bullet

@item  @option{--config=<main config project file name>} : Specify the
       configuration project file name

@item @option{--autoconf=<config project file name>}

This specifies a configuration project file name that already exists or will
be created automatically. Option @option{--autoconf=}
cannot be specified more than once. If the configuration project file
specified with @option{--autoconf=} exists, then it is used. Otherwise,
@value{gprconfig} is invoked to create it automatically.

@item  @option{-c} : Only delete compiler-generated files. Do not delete
       executables and libraries.

@item  @option{-f} : Force deletions of unwritable files

@item  @option{-F} : Display full project path name in brief error messages

@item  @option{-h} : Display this message

@item  @option{-n} : Do not delete files, only list files to delete

@item  @option{-P<proj>} : Use Project File @emph{<proj>}.

@item  @option{-q} : Be quiet/terse. There is no output, except to report
       problems.

@item  @option{-r} : (recursive) Clean all projects referenced by the main
       project directly or indirectly. Without this switch, GPRclean only
       cleans the main project.

@item  @option{-v}  : Verbose mode

@item  @option{-vPx} : Specify verbosity when parsing Project Files.
       x = 0 (default), 1 or 2.

@item  @option{-Xnm=val} : Specify an external reference for Project Files.

@end itemize

@c  ------------------------------------------------------------------------
@node Configuring with GPRconfig
@chapter Configuring with GPRconfig
@c ----------------------------------------------------------------------

@menu
* Using GPRconfig::
* The GPRconfig knowledge base::
@end menu

@c ----------------------------------------------------------------------
@node Using GPRconfig
@section Using GPRconfig
@c ---------------------------------------------------------------------

@subsection Description

@noindent
The @value{gprconfig} tool helps you generate the configuration
files for GPRbuild. It automatically detects the available compilers
on your system and, after you have selected the one needed for your
application, it generates the proper configuration file.

@NOTE{In general, you will not launch @value{gprconfig} explicitly. Instead, it is used implicitly by GPRbuild through the use of @code{--config} and
@code{--autoconf} switches}

@subsection Command line arguments

@noindent
@value{gprconfig} supports the following command line switches:

@table @option
@item --target=platform
@CINDEX{@option{--target} for gprconfig}
@TIPHTML{Use @option{--target} to specify on which machine your application will
run}

This switch indicates the target computer on which your application will
be run. It is mostly useful for cross configurations. Examples include
@samp{ppc-elf}, @samp{ppc-vx6-windows}. It can also be used in native
configurations and is useful when the same machine can run different kind
of compilers such as mingw32 and cygwin on Windows or x86-32 and x86-64
on GNU Linux. Since different compilers will often return a different
name for those targets, @value{gprconfig} has an extensive knowledge of which
targets are compatible, and will for example accept @samp{x86-linux} as
an alias for @samp{i686-pc-linux-gnu}.
The default target is the machine on which @value{gprconfig} is run.

If you enter the special target @samp{all}, then all compilers found on the
@env{PATH} will be displayed.

@item --show-targets
@CINDEX{@option{--show-target} for gprconfig}
As mentioned above, @value{gprconfig} knows which targets are compatible. You
can use this switch to find the list of targets that are compatible
with @code{--target}.

@item --config=language[,version[,runtime[,path[,name]]]]
@CINDEX{@option{--config} for gprconfig}
@TIPHTML{Use @option{--config} to automatically select the first matching
compiler}

The intent of this switch is to preselect one or more compilers directly
from the command line. This switch takes several optional arguments, which
you can omit simply by passing the empty string. When omitted, the arguments
will be computed automatically by @value{gprconfig}.

In general, only @option{language} needs to be specified, and the first
compiler on the @env{PATH} that can compile this language will be selected.
As an example, for a multi-language application programmed in C and Ada,
the command line would be:

@CODESAMPLE{--config=Ada --config=C}

@option{path} is the directory that contains the compiler executable, for
instance @file{/usr/bin} (and not the installation prefix @file{/usr}).

@option{name} should be one of the compiler names defined in the @value{gprconfig}
knowledge base. The list of supported names can be found in the output of
@option{-h}, and includes @samp{GNAT}, @samp{GCC},@dots{}. This name is
generally not needed, but can be used to distinguish among several compilers
that could match the other arguments of @option{--config}.

@CODESAMPLE{gprconfig --config Ada,,,/usr/bin       # automatic parameters@NL{}
gprconfig --config C,,,/usr/bin,GCC     # automatic version}

This switch is also the only possibility to include in your project some
languages that are not associated with a compiler. This is sometimes useful
especially when you are using environments like GPS that support project files.
For instance, if you select "Project file" as a language, the files matching
the @file{.gpr} extension will be shown in the editor, although they of course
play no role for gprbuild itself.

@item --batch
@CINDEX{@option{--batch} for gprconfig}
@TIPHTML{Use @option{--batch} to generate the configuration file with no use
interaction}
If this switch is specified, @value{gprconfig} automatically selects the first
compiler matching each of the @code{--config} switches, and generates the
configuration file immediately. It will not display an interactive menu.

@item -o file
@CINDEX{@option{-o} for gprconfig}
@TIPHTML{Use @option{-o} to specify the name of the configuration file to generate}
This specifies the name of the configuration file that will be generated.
If this switch is not specified, a default file is generated in the
installation directory of GPRbuild (assuming you have write access to
that directory), so that it is automatically picked up by GPRbuild later
on. If you select a different output file, you will need to specify it
to GPRbuild.

@item --db directory
@itemx --db-
@CINDEX{@option{--db} for gprconfig}
Indicates another directory that should be parsed for @value{gprconfig}'s knowledge
base. Most of the time this is only useful if you are creating your own
XML description files locally. The second version of the switch prevents
@value{gprconfig} from reading its default knowledge base.

@item -h
@CINDEX{@option{-h} for gprconfig}
Generates a brief help message listing all GPRconfig switches and the
default value for their arguments. This includes the location of the
knowledge base, the default target,@dots{}

@end table

@subsection Interactive use

@noindent
When you launch @value{gprconfig}, it first searches for all compilers it
can find on your @env{PATH}, that match the target specified by
@option{--target}. It is recommended, although not
required, that you place the compilers that you expect to use for your
application in your @env{PATH} before you launch @command{gprconfig},
since that simplifies the setup.

@TIPHTML{The list of compilers is sorted so that the most likely compilers
appear first}

@value{gprconfig} then displays the list of all the compilers
it has found, along with the language they can compile, the run-time
they use (when applicable),@dots{}. It then waits for you to select
one of the compilers.  This list is sorted by language, then by order
in the @env{PATH} environment variable (so that compilers that you
are more likely to use appear first), then by run-time names and
finally by version of the compiler.  Thus the first
compiler for any language is most likely the one you want to use.

You make a selection by entering the letter that appears on the line for
each compiler (be aware that this letter is case sensitive). If the compiler was
already selected, it is deselected.

@TIPHTML{The list of compilers is filtered, so that only compatible compilers
can be selected}

A filtered list of compilers is then displayed:
only compilers that target the same platform as the selected
compiler are now shown. @value{gprconfig} then checks whether it is
possible to link sources compiled with the selected compiler and each of
the remaining compilers; when linking is not possible, the compiler is not
displayed. Likewise, all compilers for the same language are hidden, so that
you can only select one compiler per language.

As an example, if you need to compile your application with several C compilers,
you should create another language, for instance called C2, for that purpose.
That will give you the flexibility to indicate in the project files which
compiler should be used for which sources.

The goal of this filtering is to make it more obvious whether you have
a good chance of being able to link. There is however no guarantee that
@value{gprconfig} will know for certain how to link any combination of the
remaining compilers.

You can select as many compilers as are needed by your application. Once you
have finished selecting the compilers, select @key{s}, and @value{gprconfig} will
generate the configuration file.

@c ----------------------------------------------------------------------
@node The GPRconfig knowledge base
@section The GPRconfig knowledge base
@c ----------------------------------------------------------------------

@noindent
@value{gprconfig} itself has no hard-coded knowledge of compilers. Thus there
is no need to recompile a new version of @value{gprconfig} when a new compiler
is distributed.

@NOTE{The role and format of the knowledge base are irrelevant for most users
of @value{gprconfig}, and are only needed when you need to add support for new
compilers. You can skip this section if you only want to learn how to use
@value{gprconfig}.}

@noindent
All knowledge of compilers is embedded in a set of XML files called the
@emph{knowledge base}.
Users can easily contribute to this general knowledge base, and have
@value{gprconfig} immediately take advantage of any new data.

The knowledge base contains various kinds of information:
@itemize @bullet
@item Compiler description

   When it is run interactively, @value{gprconfig} searches the user's
   @env{PATH} for known compilers, and tries to deduce their
   configuration (version, supported languages, supported targets, run-times,
   @dots{}). From the knowledge base @value{gprconfig} knows how to extract the
   relevant information about a compiler.

   This step is optional, since a user can also enter all the information
   manually. However, it is recommended that the knowledge base explicitly
   list its known compilers, to make configuration easier for end users.

@item Specific compilation switches

   When a compiler is used, depending on its version, target, run-time,@dots{},
   some specific command line switches might have to be supplied. The
   knowledge base is a good place to store such information.

   For instance, with the GNAT compiler, using the soft-float runtime should
   force @emph{gprbuild} to use the @option{-msoft-float} compilation switch.

@item Linker options

   Linking a multi-language application often has some subtleties,
   and typically requires specific linker switches.
   These switches depend on the list of languages, the list
   of compilers,@dots{}.

@item Unsupported compiler mix

   It is sometimes not possible to link together code compiled with two
   particular compilers. The knowledge base should store this information,
   so that end users are informed immediately when attempting to
   use such a compiler combination.
@end itemize

@noindent
The end of this section will describe in more detail the format of this
knowledge base, so that you can add your own information
and have @value{gprconfig} advantage of it.

@menu
* General file format::
* Compiler description::
* Configurations::
@end menu

@c ------------------------------------------------------------------------
@node General file format
@subsection General file format
@c ------------------------------------------------------------------------

@noindent
The knowledge base is implemented as a set of XML files. None of these
files has a special name, nor a special role. Instead, the user can
freely create new files, and put them in the knowledge base directory,
to contribute new knowledge.

The location of the knowledge base is @file{$prefix/share/gprconfig},
where @file{$prefix} is the directory in which @value{gprconfig} was
installed. Any file with extension @file{.xml} in this directory will
be parsed automatically by @value{gprconfig} at startup.

All files must have the following format:

@CODESAMPLE{<?xml version="1.0">@NL{}
<gprconfig>@NL{}
   @dots{}@NL{}
</gprconfig>}

@noindent
The root tag must be @code{<gprconfig>}.

The remaining sections in this chapter will list the valid XML tags that
can be used to replace the ``@dots{}'' code above. These tags can either all be
placed in a single XML files, or split across several files.

@c ------------------------------------------------------------------------
@node Compiler description
@subsection Compiler description
@c ------------------------------------------------------------------------

@noindent
One of the XML tags that can be specified as a child of @code{<gprconfig>} is
@code{<compiler_description>}. This node and its children describe one of
the compilers known to @value{gprconfig}. The tool uses them when it
initially looks for all compilers known on the user's @env{PATH}
environment variable.

This is optional information, but simplifies the use of @value{gprconfig},
since the user is then able to omit some parameters from the @option{--config}
command line argument, and have them automatically computed.

The @code{<compiler_description>} node doesn't accept any XML
attribute.  However, it accepts a number of child tags that explain
how to query the various attributes of the compiler.  The child tags
are evaluated (if necessary) in the same order as they are documented below.

@table @code
@item <name>
This tag contains a simple string, which is the name of the compiler.
This name must be unique across all the configuration files, and is used to
identify that @code{compiler_description} node.

@CODESAMPLE{
<compiler_description>@NL{}
   <name>GNAT</name>@NL{}
</compiler_description>}

@item <executable>
This tag contains a string, which is the name of an executable
to search for on the PATH. Examples are @samp{gnatls}, @samp{gcc},@dots{}

In some cases, the tools have a common suffix, but a prefix that might depend
on the target. For instance, GNAT uses @samp{gnatmake} for native platforms,
but @samp{powerpc-wrs-vxworks-gnatmake} for cross-compilers to VxWorks.
Most of the compiler description is the same, however.
For such cases, the value of the @code{executable} node is considered as
beginning a regular expression. The tag also accepts an attribute @code{prefix},
which is an integer indicating the parenthesis group that contains the prefix.
In the following example, you obtain the version of the GNAT compiler by running
either @command{gnatls} or @command{powerpc-wrs-vxworks-gnatls}, depending on
the name of the executable that was found.

The regular expression needs to match the whole name of the file, i.e. it
contains an implicit ``^'' at the start, and an implicit ``$'' at the end.
Therefore if you specify @samp{.*gnatmake} as the regexp, it will not match
@samp{gnatmake-debug}.

A special case is when this node is empty (but it must be specified!). In
such a case, you must also specify the language (see <language> below) as a
simple string. It is then assumed that the specified language does not
require a compiler. In the configurations file (@pxref{Configurations}),
you can test whether that language was specified on the command line by
using a filter such as
@smallexample
 <compilers>
  <compiler language="name"/>
 </compilers>
@end smallexample

@smallexample
<executable prefix="1">(powerpc-wrs-vxworks-)?gnatmake</executable>
<version><external>$@{PREFIX@}gnatls -v</external></version>
@end smallexample

@value{gprconfig} searches in all directories listed on the PATH for such
an executable. When one is found, the rest of the @code{<compiler_description>}
children are checked to know whether the compiler is valid. The directory
in which the executable was found becomes the ``current directory'' for
the remaining XML children.

@item <target>

This node indicates how to query the target architecture for the compiler.
See @ref{GPRconfig external values} for valid children.

@item <version>

This tag contains any of the nodes defined in @ref{GPRconfig external values} below.
It shows how to query the version number of the compiler. If the version
cannot be found, the executable will not be listed in the list of compilers.

@item <variable name="varname">

This node will define a user variable which may be later referenced.  The
variables are evaluated just after the version but before the languages
and the runtimes nodes.  See @ref{GPRconfig external values}
below for valid children of
this node.  If the evaluation of this variable is empty then the compiler
is considered as invalid.

@item <languages>

This node indicates how to query the list of languages. See
@ref{GPRconfig external values}
below for valid children of this node.

The value returned by the system will be split into words. As a result, if
the returned value is ``ada,c,c++'', there are three languages supported by the
compiler (and three entries are added to the menu when using @value{gprconfig}
interactively).

If the value is a simple string, the words must be comma-separated, so that
you can specify languages whose name include spaces. However, if the actual
value is computed from the result of a command, the words can also be
space-separated, to be compatible with more tools.

@item <runtimes>

This node indicates how to query the list of supported runtimes for the
compiler. See @ref{GPRconfig external values}
below for valid children. The returned value
is split into words as for @code{<languages>}.

@end table

@menu
* GPRconfig external values::
* GPRconfig variable substitution::
@end menu

@c --------------------------------------------------------------------
@node GPRconfig external values
@subsubsection External values
@c --------------------------------------------------------------------
@noindent
A number of the XML nodes described above can contain one or more children,
and specify how to query a value from an executable. Here is the list of
valid contents for these nodes. The @code{<directory>} and @code{<external>}
children can be repeated multiple times, and the @code{<filter>} and
@code{<must_match>} nodes will be applied to each of these. The final
value of the external value is the concatenation of the computation for each
of the @code{<directory>} and @code{<external>} nodes.

@CINDEX{gprconfig, external values}

@itemize @bullet
@item A simple string

A simple string given in the node indicates a constant. For
instance, the list of supported languages might be defined as:

@CODESAMPLE{<compiler_description>@NL{}
   <name>GNAT</name>@NL{}
   <executable>gnatmake</executable>@NL{}
   <languages>Ada</languages>@NL{}
</compiler_description>}

for the GNAT compiler, since this is an Ada-only compiler.

Variables can be referenced in simple strings.

@item @code{<getenv name="variable" />}

If the contents of the node is an @code{<getenv>} child, the value of
the environment variable @env{variable} is returned. If the variable is
not defined, this is an error and the compiler is ignored.

@CODESAMPLE{<compiler_description>@NL{}
  <name>GCC-WRS</name>@NL{}
  <executable prefix="1">cc(arm|pentium)</executable>@NL{}
  <version>@NL{}
    <getenv name="WIND_BASE" />@NL{}
  </version>@NL{}
</compile_description>}

@item @code{<external>command</external>}

If the contents of the node is an @code{<external>} child, this indicates
that a command should be run on the system.
When the command is run, the current directory (i.e., the one that contains
the executable found through the @code{<executable>} node, is placed first
on the @env{PATH}. The output of the command is returned and may be later
filtered. The command is not executed through a shell; therefore you cannot
use output redirection, pipes, or other advanced features.

For instance, extracting the target processor from @command{gcc} can be done
with:

@CODESAMPLE{<version>@NL{}
  <external>gcc -dumpmachine</external>@NL{}
</version>}

Since the @env{PATH} has been modified, we know that the @command{gcc} command
that is executed is the one from the same directory as the @code{<external>}
node.

Variables are substituted in @var{command}.

@item @code{<grep regexp="regexp" group="0" />}

This node must come after the previously described ones. It is used to
further filter the output. The previous output is matched against the regular
expression @var{regexp} and the parenthesis group specified by
@var{group} is returned. By default, group is 0, which indicates the
whole output of the command.

For instance, extracting the version number from @command{gcc} can be done
with:

@CODESAMPLE{<version>@NL{}
   <external>gcc -v</external>@NL{}
   <grep regexp="^gcc version (\S+)" group="1" />@NL{}
</version>}

@item @code{<directory group="0">regexp</directory>}

If the contents of the node is a @code{<directory}> child, this
indicates that @value{gprconfig} should find all the files matching the
regular expression. Regexp is a path relative to the directory that contains
the @code{<executable>} file, and should use unix directory separators
(ie '/'), since the actual directory will be converted into this format
before the match, for system independence of the knowledge base.

The group attribute indicates which parenthesis group should be returned.
It defaults to 0 which indicates the whole matched path. If this attribute is
a string rather than an integer, then it is the value returned.

@var{regexp} can be any valid regular expression. This will only match
a directory name, not a subdirectory. Remember to quote special characters,
including ``.'', if you do not mean to use a regexp.

For instance, finding the list of supported runtimes for the GNAT compiler
is done with:

@CODESAMPLE{<runtimes>@NL{}
 <directory group="1">@NL{}
    \.\./lib/gcc/$@{TARGET@}/.*/rts-(.*)/adainclude@NL{}
 </directory>@NL{}
 <directory group="default">@NL{}
   \.\./lib/gcc/$@{TARGET@}/.*/adainclude@NL{}
 </directory>@NL{}
</runtimes>}

Note the second node, which matches the default run-time, and displays it as
such.

@item @code{<filter>value1,value2,...</filter>}

This node must come after one the previously described ones. It is used to
further filter the output. The previous output is split into words (it is
considered as a comma-separated or space-separated list of words), and only
those words in @samp{value1}, @samp{value2},@dots{} are kept.

For instance, the @command{gcc} compiler will return a variety of supported
languages, including ``ada''. If we do not want to use it as an Ada
compiler we can specify:

@CODESAMPLE{<languages>@NL{}
   <external regexp="languages=(\S+)" group="1">gcc -v</external>@NL{}
   <filter>c,c++,fortran</filter>@NL{}
</languages>}

@item @code{<must_match>regexp</must_match>}

If this node is present, then the filtered output is compared with the
specified regular expression. If no match is found, then the executable
is not stored in the list of known compilers.

For instance, if you want to have a @code{<compiler_description>} tag
specific to an older version of GCC, you could write:

@CODESAMPLE{<version>@NL{}
   <external regexp="gcc version (\S+)"@NL{}
        group="1">gcc -v </external>@NL{}
   <must_match>2.8.1</must_match>@NL{}
</version>}

Other versions of gcc will not match this @code{<compiler_description>}
node.

@end itemize

@c --------------------------------------------------------------------
@node GPRconfig variable substitution
@subsubsection Variable Substitution
@c --------------------------------------------------------------------
@noindent
The various compiler attributes defined above are made available as
variables in the rest of the XML files. Each of these variable can be used
in the value of the various nodes (for instance in @code{<directory>}),
and in the configurations (@pxref{Configuration}).

A variable is referenced by @code{$@{name@}} where @var{name} is either
a user variable or a predefined variable.  An alternate reference is
@code{$name} where @var{name} is a sequence of alpha numeric characters or
underscores.  Finally @code{$$} is replaced by a simple @code{$}.

User variables are defined by @code{<variable>} nodes and may override
predefined variables.  To avoid a possible override use lower case names.

Predefined variables are always in upper case.  Here is the list of
predefined variables

@table @var
@item $@{EXEC@}
is the name of the executable that was found through @code{<executable>}. It
only contains the basename, not the directory information.

@item $@{HOST@}
is replaced by the architecture of the host on which @value{gprconfig} is
running. This name is hard-coded in @value{gprconfig} itself, and is generated
by @command{configure} when @value{gprconfig} was built.

@item $@{TARGET@}
is replaced by the target architecture of the compiler, as returned by the
@code{<target>} node. This is of course not available when computing the
target itself.

@item $@{VERSION@}
is replaced by the version of the compiler. This is not available when
computing the target or, of course, the version itself.

@item $@{PREFIX@}
is replaced by the prefix to the executable name, as defined by the
@code{<executable>} node.

@item $@{PATH@}
is the current directory, i.e. the one containing the executable found through
@code{<executable>}. It always ends with a directory separator.

@item $@{GPRCONFIG_PREFIX@}
is the directory in which @value{gprconfig} was installed (e.g
@file{"/usr/local/"} if the executable is @file{"/usr/local/bin/gprconfig"}.
This directory always ends with a directory separator.

@item $@{LANGUAGE@}
is the language supported by the compiler, always folded to lower-case

@item $@{RUNTIME@}
@itemx $@{RUNTIME_DIR@}
This string will always be substituted by the empty string when the
value of the external value is computed. These are special strings
used when substituting text in configuration chunks.

@var{RUNTIME_DIR} always end with a directory separator.

@end table

If a variable is not defined, an error message is issued and the variable
is substituted by an empty string.

@c ------------------------------------------------------------------------
@node Configurations
@subsection Configurations
@c ------------------------------------------------------------------------

@noindent
The second type of information stored in the knowledge base are the chunks
of @emph{gprbuild} configuration files.

Each of these chunks is also placed in an XML node that provides optional
filters. If all the filters match, then the chunk will be merged with other
similar chunks and placed in the final configuration file that is generated
by @value{gprconfig}.

For instance, it is possible to indicate that a chunk should only be
included if the GNAT compiler with the soft-float runtime is used. Such
a chunk can for instance be used to ensure that Ada sources are always
compiled with the @code{-msoft-float} command line switch.

@value{gprconfig} does not perform sophisticated merging of chunks. It simply
groups packages together. For example, if the two chunks are:

@CODESAMPLE{chunk1:@NL{}
   @b{package} Language_Processing @b{is}@NL{}
     @b{for} Attr1 @b{use} ("foo");@NL{}
   @b{end} Language_Processing;@NL{}
chunk2:@NL{}
   @b{package} Language_Processing @b{is}@NL{}
     @b{for} Attr1 @b{use} ("bar");@NL{}
   @b{end} Language_Processing;}

@noindent
Then the final configuration file will look like:

@CODESAMPLE{@b{package} Language_Processing @b{is}@NL{}
  @b{for} Attr1 @b{use} ("foo");@NL{}
  @b{for} Attr1 @b{use} ("bar");@NL{}
@b{end} Language_Processing;}

@noindent
As a result, to avoid conflicts, it is recommended that the chunks be
written so that they easily collaborate together. For instance,
to obtain something equivalent to

@CODESAMPLE{@b{package} Language_Processing @b{is}@NL{}
  @b{for} Attr1 @b{use} ("foo", "bar");@NL{}
@b{end} Language_Processing;}

@noindent
the two chunks above should be written as:

@CODESAMPLE{chunk1:@NL{}
  @b{package} Language_Processing @b{is}@NL{}
    @b{for} Attr1 @b{use} Language_Processing'Attr1 & ("foo");@NL{}
  @b{end} Language_Processing;@NL{}
chunk2:@NL{}
  @b{package} Language_Processing @b{is}@NL{}
    @b{for} Attr1 @b{use} Language_Processing'Attr1 & ("bar");@NL{}
  @b{end} Language_Processing;}

@noindent
The chunks are described in a @code{<configuration>} XML node. The most
important child of such a node is @code{<config>}, which contains the
chunk itself. For instance, you would write:

@CODESAMPLE{<configuration>@NL{}
  @i{...  list of filters, see below}@NL{}
  <config>@NL{}
   @b{package} Language_Processing @b{is}@NL{}
      @b{for} Attr1 @b{use} Language_Processing'Attr1 & ("foo");@NL{}
   @b{end} Language_Processing;@NL{}
  </config>@NL{}
</configuration>}

@noindent
If @code{<config>} is an empty node (i.e., @samp{<config/>} or
@samp{<config></config>}) was used, then the combination of selected
compilers will be reported as invalid, in the sense that code
compiled with these compilers cannot be linked together. As a result,
@value{gprconfig} will not create the configuration file.

The special variables (@pxref{GPRconfig variable substitution}) are also
substituted in the chunk. That allows you to compute some attributes of the
compiler (its path, the runtime,@dots{}), and use them when generating the
chunks.

The filters themselves are of course defined through XML tags, and can
be any of:

@table @code
@item <compilers negate="false">

This filter contains a list of @code{<compiler>} children. The
@code{<compilers>} filter matches if any of its children match.
However, you can have several @code{<compilers>} filters, in which
case they must all match. This can be used to include linker switches
chunks. For instance, the following code would be used to describe
the linker switches to use when GNAT 5.05 or 5.04 is used in addition to
g++ 3.4.1:

@CODESAMPLE{<configuration>@NL{}
  <compilers>@NL{}
    <compiler name="GNAT" version="5.04" />@NL{}
    <compiler name="GNAT" version="5.05" />@NL{}
  </compilers>@NL{}
  <compilers>@NL{}
    <compiler name="G++" version="3.4.1" />@NL{}
  </compilers>@NL{}
  ...@NL{}
</configuration>}

@noindent
If the attribute @var{negate} is @samp{true}, then the meaning of this
filter is inverted, and it will match if none of its children matches.

The format of the @code{<compiler>} is the following:

@CODESAMPLE{<compiler name="name" version="..."@NL{}
   runtime="..." language="..." />}

@noindent
The name and language attributes, when specified, match
the corresponding attributes used in the @code{<compiler_description>}
children. All other attributes are regular expressions, which are matched
against the corresponding selected compilers. When an attribute is not
specified, it will always match. Matching is done in a case-insensitive
manner.

For instance, to check a GNAT compiler in the 5.x family, use:

@CODESAMPLE{<compiler name="GNAT" version="5.\d+" />}

@item <hosts negate="false">

This filter contains a list of @code{<host>} children. It matches when
any of its children matches. You can specify only one @code{<hosts>}
node.
The format of @code{<host>} is a node with a single mandatory attribute
@var{name}, which is a regexp matched against the architecture on
which @value{gprconfig} is running. The name of the architecture was
computed by @code{configure} when @value{gprconfig} was built.

If the @var{negate} attribute is @samp{true}, then the meaning of this
filter is inverted, and it will match when none of its children matches.

For instance, to active a chunk only if the compiler is running on an
intel linux machine, use:

@CODESAMPLE{<hosts>@NL{}
  <host name="i.86-.*-linux(-gnu)?" />@NL{}
</hosts>}

@item <targets negate="false">

This filter contains a list of @code{<target>} children. It behaves
exactly like @code{<hosts>}, but matches against the architecture
targeted by the selected compilers. For instance, to activate a chunk
only when the code is targeted for linux, use:

If the @var{negate} attribute is @samp{true}, then the meaning of this filter
is inverted, and it will match when none of its children matches.

@CODESAMPLE{<targets>@NL{}
  <target name="i.86-.*-linux(-gnu)?" />@NL{}
</targets>}
@end table

@c  ------------------------------------------------------------------------
@node Configuration File Reference
@chapter Configuration File Reference
@c  ------------------------------------------------------------------------

@menu
* Project Level Attributes::
* Package Naming::
* Package Builder::
* Package Compiler::
* Package Binder::
* Package Linker::
@end menu

@noindent
GPRbuild needs to have a configuration file to know the different
characteristics of the toolchains that can be used to compile sources and
build libraries and executables.

A configuration file is a special kind of project file: it uses the same
syntax as a standard project file. Attributes in the configuration file
define the configuration. Some of these attributes have a special meaning
in the configuration.

The default name of the configuration file, when not specified to GPRbuild by
switches --config= or --autoconf= is @file{default.cgpr}. Although the name of the
configuration file can be any valid file name, it is recommended that its
suffix be @file{.cgpr} (for Configuration GNAT Project), so that it cannot be
confused with a standard project file which has the suffix @file{.gpr}.

When @file{default.cgpr} cannot be found in the configuration project path,
GPRbuild invokes @value{gprconfig} to create a configuration file.

In the following description of the attributes, when an attribute is an
associative array indexed by the language name, for example
@code{Spec_Suffix (<language>)}, then the name of the language is case insensitive.
For example, both @code{C} and @code{c} are allowed.

Any attribute may appear in a configuration project file. All attributes in
a configuration project file are inherited by each user project file in the
project tree. However, usually only the attributes listed below make sense
in the configuration project file.

@node Project Level Attributes
@section Project Level Attributes

@menu
* General Attributes::
* General Library Related Attributes::
* Archive Related Attributes::
* Shared Library Related Attributes::
@end menu

@node General Attributes
@subsection General Attributes

@itemize @bullet

@item Default_Language

Specifies the name of the language of the immediate sources of a project when
attribute @code{Languages} is not declared in the project. If attribute
@code{Default_Language} is not declared in the configuration file, then each user
project file in the project tree must have an attribute @code{Languages} declared,
unless it extends another project. Example:

@smallexample
   for Default_Language use "ada";
@end smallexample

@item Run_Path_Option

Specifies a ``run path option''; i.e., an option to use when linking an
executable or a shared library to indicate the path where to look for other
libraries. The value of this attribute is a string list. When linking an
executable or a shared library, the search path is concatenated with the last
string in the list, which may be an empty string. Example:

@smallexample
   for Run_Path_Option  use ("-Wl,-rpath,");
@end smallexample

@item Toolchain_Version (<language>)

Specifies a version for a toolchain, as a single string. This toolchain
version is passed to the library builder. Example:

@smallexample
   for Toolchain_Version ("Ada") use "GNAT 6.1";
@end smallexample

This attribute is used by GPRbind to decide on the names of the shared GNAT
runtime libraries.

@item Toolchain_Description (<language>)

Specifies as a single string a description of a toolchain. This attribute is
not directly used by GPRbuild or its auxiliary tools (GPRbind and GPRlib) but
may be used by other tools, for example GPS. Example:

@smallexample
   for Toolchain_Description ("C") use "gcc version 4.1.3 20070425";
@end smallexample

@end itemize

@node General Library Related Attributes
@subsection General Library Related Attributes

@itemize @bullet

@item Library_Support

Specifies the level of support for library project. If this attribute is not
specified, then library projects are not supported. The only potential values
for this attribute are @code{none}, @code{static_only} and @code{full}. Example:

@smallexample
   for Library_Support use "full";
@end smallexample

@item Library_Builder

Specifies the name of the executable for the library builder. Example:

@smallexample
   for Library_Builder use "/.../gprlib";
@end smallexample

@end itemize

@node Archive Related Attributes
@subsection Archive Related Attributes

@itemize @bullet

@item Archive_Builder

Specifies the name of the executable of the archive builder with the minimum
options, if any. Example:

@smallexample
   for Archive_Builder use ("ar", "cr");
@end smallexample

@item Archive_Indexer

Specifies the name of the executable of the archive indexer with the minimum
options, if any. If this attribute is not specified, then there is no
archive indexer. Example:

@smallexample
   for Archive_Indexer use ("ranlib");
@end smallexample

@item Archive_Suffix

Specifies the suffix of the archives. If this attribute is not specified, then
the suffix of the archives is defaulted to @file{.a}. Example:

@smallexample
   for Archive_Suffix use ".olb"; --  for VMS
@end smallexample

@item Library_Partial_Linker

Specifies the name of the executable of the partial linker with the options
to be used, if any. If this attribute is not specified, then there is no
partial linking. Example:

@smallexample
   for Library_Partial_Linker use ("gcc", "-nostdlib", "-Wl,-r", "-o");
@end smallexample

@end itemize

@node Shared Library Related Attributes
@subsection Shared Library Related Attributes

@itemize @bullet

@item Shared_Library_Prefix

Specifies the prefix of the file names of shared libraries. When this attribute
is not specified, the prefix is @code{lib}. Example:

@smallexample
   for Shared_Library_Prefix use ""; --  for Windows, if needed
@end smallexample

@item Shared_Library_Suffix

Specifies the suffix of the file names of shared libraries. When this attribute
is not specified, the suffix is @file{.so}. Example:

@smallexample
   for Shared_Library_Suffix use ".dll"; --  for Windows
@end smallexample

@item Symbolic_Link_Supported

Specifies if symbolic links are supported by the platforms. The possible values
of this attribute are @code{"false"} (the default) and @code{"true"}. When this attribute is
not specified, symbolic links are not supported.

@smallexample
   for Symbolic_Link_Supported use "true";
@end smallexample

@item Library_Major_Minor_ID_Supported

Specifies if major and minor IDs are supported for shared libraries.
The possible values of this attribute are @code{"false"} (the default) and @code{"true"}.
When this attribute is not specified, major and minor IDs are not supported.

@smallexample
   for Library_Major_Minor_ID_Supported use "True";
@end smallexample

@item Library_Auto_Init_Supported

Specifies if library auto initialization is supported. The possible values of
this attribute are @code{"false"} (the default) and @code{"true"}. When this attribute is not
specified, library auto initialization is not supported.

@smallexample
   for Library_Auto_Init_Supported use "true";
@end smallexample

@item Shared_Library_Minimum_Switches

Specifies the minimum options to be used when building shared library. These
options are put in the appropriate section in the library exchange file when
the library builder is invoked. Example:

@smallexample
   for Shared_Library_Minimum_Switches use  ("-shared");
@end smallexample

@item Library_Version_Switches

Specifies the option or options to be used when a library version is used.
These options are put in the appropriate section in the library exchange file
when the library builder is invoked. Example:

@smallexample
   for Library_Version_Switches use ("-Wl,-soname,");
@end smallexample

@item Runtime_Library_Dir (<language>)

Specifies the directory for the runtime libraries for the language.
Example:

@smallexample
   for Runtime_Library_Dir ("Ada") use "/path/to/adalib";
@end smallexample

This attribute is used by GPRlib to link shared libraries with Ada code.

@end itemize

@node Package Naming
@section Package Naming

Attributes in package @code{Naming} of a configuration file specify defaults. These
attributes may be used in user project files to replace these defaults.

The following attributes usually appear in package @code{Naming} of a configuration
file:

@itemize @bullet
@item Spec_Suffix (<language>)

Specifies the default suffix for a ``spec'' or header file. Examples:

@smallexample
   for Spec_Suffix ("Ada") use ".ads";
   for Spec_Suffix ("C")   use ".h";
   for Spec_Suffix ("C++") use ".hh";
@end smallexample

@item Body_Suffix (<language>)

Specifies the default suffix for a ``body'' or a source file. Examples:

@smallexample
   for Body_Suffix ("Ada") use ".adb";
   for Body_Suffix ("C")   use ".c";
   for Body_Suffix ("C++") use ".cpp";
@end smallexample

@item Separate_Suffix

Specifies the suffix for a subunit source file (separate) in Ada. If attribute
@code{Separate_Suffix} is not specified, then the default suffix of subunit source
files is the same as the default suffix for body source files. Example:

@smallexample
   for Separate_Suffix use ".sep";
@end smallexample

@item Casing

Specifies the casing of spec and body files in a unit based language
(such as Ada) to know how to map a unit name to its file name. The values for
this attribute may only be @code{"lowercase"}, @code{"UPPERCASE"} and @code{"Mixedcase"}.
The default, when attribute @code{Casing} is not specified is lower case.
This attribute rarely needs to be specified, since on
platforms where file names are not case sensitive (such as Windows or VMS)
the default (lower case) will suffice.

@item Dot_Replacement

Specifies the string to replace a dot (``.'') in unit names of a unit based
language (such as Ada) to obtain its file name. If there is any unit based
language in the configuration, attribute @code{Dot_Replacement} must be declared.
Example:

@smallexample
   for Dot_Replacement use "-";
@end smallexample

@end itemize

@node Package Builder
@section Package Builder

@itemize @bullet

@item Executable_Suffix

Specifies the default executable suffix. If no attribute @code{Executable_Suffix} is
declared, then the default executable suffix for the host platform is used.
Example:

@smallexample
   for Executable_Suffix use ".exe";
@end smallexample

@end itemize

@node Package Compiler
@section Package Compiler

@menu
* General Compilation Attributes::
* Mapping File Related Attributes::
* Config File Related Attributes::
* Dependency Related Attributes::
* Search Path Related Attributes::
@end menu

@node General Compilation Attributes
@subsection General Compilation Attributes

@itemize @bullet

@item Driver (<language>)

Specifies the name of the executable for the compiler of a language. The single
string value of this attribute may be an absolute path or a relative path. If
relative, then the execution path is searched. Specifying the empty string for
this attribute indicates that there is no compiler for the language.

Examples:

@smallexample
   for Driver ("C++") use "g++";
   for Driver ("Ada") use "/.../bin/gcc";
   for Driver ("Project file") use "";
@end smallexample

@item Required_Switches (<language>)

Specifies the minimum options that must be used when invoking the compiler
of a language. Examples:

@smallexample
   for Required_Switches ("C")   use ("-c", "-x", "c");
   for Required_Switches ("Ada") use ("-c", "-x", "ada", "-gnatA");
@end smallexample

@item PIC_Option (<language>)

Specifies the option or options that must be used when compiling a source of
a language to be put in a shared library. Example:

@smallexample
   for PIC_Option ("C") use ("-fPIC");
@end smallexample

@end itemize

@node Mapping File Related Attributes
@subsection Mapping File Related Attributes

@itemize @bullet

@item Mapping_File_Switches (<language>)

Specifies the switch or switches to be used to specify a mapping file to the
compiler. When attribute @code{Mapping_File_Switches} is not declared, then no
mapping file is specified to the compiler. The value of this attribute is a
string list. The path name of the mapping file is concatenated with the last
string in the string list, which may be empty. Example:

@smallexample
   for Mapping_File_Switches ("Ada") use ("-gnatem=");
@end smallexample

@item Mapping_Spec_Suffix (<language>)

Specifies, for unit based languages that support mapping files, the suffix in
the mapping file that needs to be added to the unit name for specs. Example:

@smallexample
    for Mapping_Spec_Suffix ("Ada") use "%s";
@end smallexample

@item Mapping_Body_Suffix (<language>)

Specifies, for unit based languages that support mapping files, the suffix in
the mapping file that needs to be added to the unit name for bodies. Example:

@smallexample
    for Mapping_Spec_Suffix ("Ada") use "%b";
@end smallexample

@end itemize

@node Config File Related Attributes
@subsection Config File Related Attributes

@noindent

In the value of config file attributes defined below, there are some
placeholders that GPRbuild will replace. These placeholders are:

@itemize @bullet

@item %u : the unit name

@item %f : the file name of the source

@item %s : the spec suffix

@item %b : the body suffix

@item %c : the casing

@item %d : the dot replacement string

@end itemize

Attributes:

@itemize @bullet

@item Config_File_Switches (<language>)

Specifies the switch or switches to be used to specify a configuration file to
the compiler. When attribute @code{Config_File_Switches} is not declared, then no
config file is specified to the compiler. The value of this attribute is a
string list. The path name of the config file is concatenated with the last
string in the string list, which may be empty. Example:

@smallexample
   for Config_File_Switches ("Ada") use ("-gnatec=");
@end smallexample

@item Config_Body_File_Name (<language>)

Specifies the line to be put in a config file to indicate the file name of a
body. Example:

@smallexample
   for Config_Body_File_Name ("Ada") use
       "pragma Source_File_Name_Project (%u, Body_File_Name => ""%f"");";
@end smallexample

@item Config_Spec_File_Name (<language>)

Specifies the line to be put in a config file to indicate the file name of a
spec. Example:

@smallexample
   for Config_Spec_File_Name ("Ada") use
       "pragma Source_File_Name_Project (%u, Spec_File_Name => ""%f"");";
@end smallexample

@item Config_Body_File_Name_Pattern (<language>)

Specifies the line to be put in a config file to indicate a body file name
pattern. Example:

@smallexample
   for Config_Body_File_Name_Pattern ("Ada") use
       "pragma Source_File_Name_Project " &
       "  (Body_File_Name  => ""*%b""," &
       "   Casing          => %c," &
       "   Dot_Replacement => ""%d"");";
@end smallexample

@item Config_Spec_File_Name_Pattern (<language>)

Specifies the line to be put in a config file to indicate a spec file name
pattern. Example:

@smallexample
   for Config_Spec_File_Name_Pattern ("Ada") use
       "pragma Source_File_Name_Project " &
       "  (Spec_File_Name  => ""*%s""," &
       "   Casing          => %c," &
       "   Dot_Replacement => ""%d"");";
@end smallexample

@item Config_File_Unique (<language>)

Specifies, for languages that support config files, if several config files
may be indicated to the compiler, or not. This attribute may have only two
values: @code{"true"} or @code{"false"} (case insensitive). The default, when this attribute
is not specified, is @code{"false"}. When the value @code{"true"} is specified for this
attribute, GPRbuild will concatenate the config files, if there are more than
one. Example:

@smallexample
   for Config_File_Unique ("Ada") use "True";
@end smallexample

@end itemize

@node Dependency Related Attributes
@subsection Dependency Related Attributes

There are two dependency-related attributes: @code{Dependency_Switches} and
@code{Dependency_Driver}. If neither of these two attributes are specified for
a language other than Ada, then the source needs to be (re)compiled if
the object file does not exist or the source file is more recent than
the object file or the switch file.

@itemize @bullet

@item Dependency_Switches (<language>)

For languages other than Ada, attribute @code{Dependency_Switches} specifies
the option or options to add to the compiler invocation so that it creates
the dependency file at the same time. The value of attribute @code{Dependency_Option}
is a string list. The name of the dependency file is added to the last string
in the list, which may be empty. Example:

@smallexample
   for Dependency_Switches ("C") use ("-Wp,-MD,");
@end smallexample

With these @code{Dependency_Switches}, when compiling @file{file.c} the compiler will be
invoked with the option @option{-Wp,-MD,file.d}.

@item Dependency_Driver (<language>)

Specifies the command and options to create a dependency file for a source.
The full path name of the source is appended to the last string of the string
list value. Example:

@smallexample
   for Dependency_Driver ("C") use ("gcc", "-E", "-Wp,-M", "");
@end smallexample

Usually, attributes @code{Dependency_Switches} and @code{Dependency_Driver} are not both
specified.

@end itemize

@node Search Path Related Attributes
@subsection Search Path Related Attributes

@itemize @bullet

@item Include_Switches (<language>)

Specifies the option or options to use when invoking the compiler to indicate
that a directory is part of the source search path. The value of this
attribute is a string list. The full path name of the directory is concatenated
with the last string in the string list, which may be empty. Example:

@smallexample
   for Include_Switches ("C") use ("-I");
@end smallexample

Attribute @code{Include_Switches} is ignored if either one of the attributes
@code{Include_Path} or @code{Include_Path_File} are specified.

@item Include_Path (<language>)

Specifies the name of an environment variable that is used by the compiler to
get the source search path. The value of the environment variable is the source
search path to be used by the compiler. Example:

@smallexample
   for Include_Path ("C")   use "CPATH";
   for Include_Path ("Ada") use "ADA_INCLUDE_PATH";
@end smallexample

Attribute @code{Include_Path} is ignored if attribute @code{Include_Path_File} is declared
for the language.

@item Include_Path_File (<language>)

Specifies the name of an environment variable that is used by the compiler to
get the source search path. The value of the environment variable is the path
name of a text file that contain the path names of the directories of the
source search path. Example:

@smallexample
   for Include_Path_File ("Ada") use "ADA_PRJ_INCLUDE_FILE";
@end smallexample

@end itemize

@node Package Binder
@section Package Binder

@itemize @bullet

@item Driver (<language>)

Specifies the name of the executable of the binder driver. When this attribute
is not specified, there is no binder for the language. Example:

@smallexample
   for Driver ("Ada") use "/.../gprbind";
@end smallexample

@item Required_Switches (<language>)

Specifies the minimum options to be used when invoking the binder driver.
These options are put in the appropriate section in the binder exchange file,
one option per line. Example:

@smallexample
   for Required_Switches ("Ada") use ("--prefix=<prefix>");
@end smallexample

@item Prefix (<language>)

Specifies the prefix to be used in the name of the binder exchange file.
Example:

@smallexample
   for Prefix ("C++") use ("c__");
@end smallexample

@item Objects_Path (<language>)

Specifies the name of an environment variable that is used by the compiler to
get the object search path. The value of the environment variable is the object
search path to be used by the compiler. Example:

@smallexample
   for Objects_Path ("Ada") use "ADA_OBJECTS_PATH";
@end smallexample

@item Objects_Path_File (<language>)

Specifies the name of an environment variable that is used by the compiler to
get the object search path. The value of the environment variable is the path
name of a text file that contain the path names of the directories of the
object search path. Example:

@smallexample
   for Objects_Path_File ("Ada") use "ADA_PRJ_OBJECTS_FILE";
@end smallexample

@end itemize

@node Package Linker
@section Package Linker

@itemize @bullet

@item Driver

Specifies the name of the executable of the default linker. Example:

@smallexample
   for Driver use "g++";
@end smallexample

@item Required_Switches

Specifies the minimum options to be used when invoking the default linker.

@end itemize

@ifset useindex
@c  --------------------------------------------------------------------------
@node Index
@unnumbered Index
@c  --------------------------------------------------------------------------

@printindex cp
@end ifset

@contents

@bye

