\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-2012, AdaCore                      o
@c                                                                            o
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo

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

@set gprconfig GPRconfig

@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

@macro PROJECTFILE{TXT}
@CODESAMPLE{\TXT\}
@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
@c @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
@c @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
@c @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

@titlepage
@title GPRbuild User's Guide
@subtitle Document identifier: $Rev:: 187710 $
@subtitle Date: $Date:: 2012-03-28#$
@author AdaCore

@page
@vskip 0pt plus 1filll

Copyright @copyright{} 2007-2011, AdaCore

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being ``GNU Free Documentation License'', with the
Front-Cover Texts being
``GPRbuild User's Guide'',
and with no Back-Cover Texts.
A copy of the license is included in the section entitled
``GNU Free Documentation License''.

@end titlepage

@ifnottex
@node Top
@top GPRBUILD User's Guide

@noindent

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being ``GNU Free Documentation License'', with the
Front-Cover Texts being
``GPRbuild User's Guide'',
and with no Back-Cover Texts.
A copy of the license is included in the section entitled
``GNU Free Documentation License''.

@menu
* GNAT Project Manager::
* Tools Supporting Project Files::
* Gprbuild::
* GNU Free Documentation License::
* Index::

@detailmenu
--- The Detailed Contents ---

GNAT Project Manager
* Introduction::
* Building With Projects::
* Organizing Projects into Subsystems::
* Scenarios in Projects::
* Library Projects::
* Project Extension::
* Project File Reference::

Building With Projects
* Source Files and Directories::
* Object and Exec Directory::
* Main Subprograms::
* Tools Options in Project Files::
* Compiling with Project Files::
* Executable File Names::
* Avoid Duplication With Variables::
* Naming Schemes::

Organizing Projects into Subsystems
* Project Dependencies::
* Cyclic Project Dependencies::
* Sharing Between Projects::
* Global Attributes::

Library Projects
* Building Libraries::
* Using Library Projects::
* Stand-alone Library Projects::
* Installing a library with project files::

Project Extension
* Project Hierarchy Extension::

Project File Reference
* Project Declaration::
* Qualified Projects::
* Declarations::
* Packages::
* Expressions::
* External Values::
* Typed String Declaration::
* Variables::
* Attributes::
* Case Statements::

Tools Supporting Project Files
* gnatmake and Project Files::
* The GNAT Driver and Project Files::
* The Development Environments::
* Cleaning up with GPRclean::

gnatmake and Project Files
* Switches Related to Project Files::
* Switches and Project Files::
* Specifying Configuration Pragmas::
* Project Files and Main Subprograms::
* Library Project Files::

Cleaning up with GPRclean
* Switches for GPRclean::

Gprbuild
* Building with GPRbuild::
* Configuring with GPRconfig::
* Configuration File Reference::

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

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

The GPRconfig knowledge base
* General file format::
* Compiler description::
* GPRconfig external values::
* GPRconfig variable substitution::
* Configurations::

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

Project Level Attributes
* General Attributes::
* General Library Related Attributes::
* Archive Related Attributes::
* Shared Library Related Attributes::

Package Compiler
* General Compilation Attributes::
* Mapping File Related Attributes::
* Config File Related Attributes::
* Dependency Related Attributes::
* Search Path Related Attributes::
@end detailmenu
@end menu
@end ifnottex

@include projects_unw.texi

@c ---------------------------------------------
@node Gprbuild
@chapter Gprbuild
@c ---------------------------------------------

@noindent
@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++ and Fortran.

@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
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 @bullet
@item the default source naming conventions for each language,
@item the compiler name, location and required options,
@item how to compute inter-unit dependencies,
@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.

@menu
* Building with GPRbuild::
* Configuring with GPRconfig::
* Configuration File Reference::
* Cleaning up with GPRclean::
@end menu

@c ---------------------------------------------
@node Building with GPRbuild
@section Building with GPRbuild
@c ---------------------------------------------

@noindent


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

@c ---------------------------------------------
@node Command Line
@subsection Command Line
@c ---------------------------------------------

@noindent
Three elements can optionally be specified on GPRbuild's command line:

@itemize @bullet
@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, 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.
It is also possible to specify absolute file names, or file names relative
to the current directory. Finally, it is possible to specify Ada unit names
(and gprbuild automatically looks up the corresponding file name in the
project).

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{--target=<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, when linking an executable.

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

@item @option{-margs}

  Equivalent to @option{-gargs}, provided for compatibility with
  @command{gnatmake}.
@end itemize


@c ---------------------------------------------
@node Switches
@subsection Switches
@c ---------------------------------------------

GPRbuild takes into account switches that may be specified on the command
line or in attributes Switches(<main or language>) or Default_Switches
(<language) in package Builder of the main project.

When there are a single main (specified on the command line or in
attribute Main in the main project), the switches that are taken into account
in package Builder of the main project are Switches (<main>), if declared, or
Switches (<language of main>), if declared.

When there are several mains, if there are sources of the same language, then
Switches (<language of main>) is taken into account, if specified.

When there are no main specified, if there is only one compiled language
(that is a language with a non empty Compiler Driver), then
Switches (<single language>) is taken into account, if specified.

@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{--no-object-check}

  Do not check if an object has been created after compilation.

@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{--unchecked-shared-lib-imports}

  Allow shared library projects to import projects that are not shared
  library projects.

@item @option{--source-info=<source info file>}

  Specify a source info file. If the source info file is specified as a
  relative path, then it is relative to the object directory of the main
  project. If the source info file does not exist, then after the Project
  Manager has successfully parsed and processed the project files and found
  the sources, it creates the source info file. If the source info file
  already exists and can be read successfully, then the Project Manager will
  get all the needed information about the sources from the source info file
  and will not look for them. This reduces the time to process the project
  files, especially when looking for sources that take a long time. If the
  source info file exists but cannot be parsed successfully, the Project
  Manager will attempt to recreate it. If the Project Manager fails to create
  the source info file, a message is issued, but GPRbuild does not fail.

@item @option{--restricted-to-languages=<list of language names>}

  Restrict the sources to be compiled to one or several languages. Each
  language name in the list is separated from the next by a comma, without any
  space.

  Example: @option{--restricted-to-languages=Ada,C}

  When this switch is used, switches @option{-c}, @option{-b} and
  @option{-l} are ignored. Only the compilation phase is performed and the
  sources that are not in the list of restricted languages are not compiled,
  including mains specified in package Builder of the main project.

@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{-Inn} (Index of main unit in multi-unit source file)
  Indicate the index of the main unit in a multi-unit source file.
  The index must be a positive number and there should be one and only
  one main source file name on the command line.

@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{-eS} (no effect)

  This switch is only accepted for compatibility with gnatmake, but it has
  no effect. For gnatmake, it means: echo commands to standard output instead
  of standard error, but for gprbuild, commands are always echoed to standard
  output.

@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{-m} (Minimum Ada recompilation)

  Do not recompile Ada code if timestamps are different but checksums are the
  same.

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

  Specify the file name of the executable. Switch @option{-o} can
  be used only if there is exactly one executable being built;
  that is, there is exactly one main on the command line,
  or there are no mains on the command line and exactly one
  main in attribute @code{Main} of the main project.

@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{-r} (Recursive)

  This switch has an effect only when @option{-c} or @option{-u} is also
  specified and there are no mains: it means that all sources of all projects
  need to be compiled or recompiled.

@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

@noindent
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{--create-map-file}

  When linking an executable, if supported by the platform, create a map file
  with the same name as the executable, but with suffix @file{.map}.

@item @option{--create-map-file=<map file>}

  When linking an executable, if supported by the platform, create a map file
  with file name @file{<map file>}.

@item @option{--no-indirect-imports}

  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{--indirect-imports}

  This indicates that sources of a project can import sources or header files
  from directly or indirectly imported projects. This is the default behavior.
  This switch is provided to cancel a previous switch
  @option{--no-indirect-imports} on the command line.

@item @option{--no-split-units}

  Forbid the sources of the same Ada unit to be in different projects.

@item @option{--single-compile-per-obj-dir}

  Disallow several simultaneous compilations for the same object directory.

@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. On a multi-processor system,
  @option{-j<num>} can greatly speed up the build process.

@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{-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. Note that these switches may be
  specified in package Builder of the main project, but they are useless there
  as either the directories already exist or the processing of the project
  files has failed before the evaluation of the Builder switches, because there
  is at least one missing directory.

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

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

@item @option{-R} (no run path option)

  Do not use a run path option to link executables or shared libraries,
  even when attribute Run_Path_Option is specified.

@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{-vl} (Verbose output, low level)

  Verbose output. Some verbose messages are not displayed.

@item @option{-vm} (Verbose output, medium level)

  Verbose output. Some verbose messages may not be displayed.

@item @option{-vh} (Verbose output, high level)

  Equivalent to @option{-v}.

@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

@noindent
Switches that are accepted for compatibility with gnatmake, either on the
command line or in the Builder Ada switches in the main project file:

@itemize @bullet
@item @option{-nostdinc}
@item @option{-nostdlib}
@item @option{-fstack-check}
@item @option{-fno-inline}
@item @option{-g*} Any switch starting with @option{-g}
@item @option{-O*} Any switch starting with @option{-O}

@end itemize

@noindent
These switches are passed to the Ada compiler.

@c ---------------------------------------------
@node Initialization
@subsection Initialization
@c ---------------------------------------------

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

@c ---------------------------------------------
@node Compilation of one or several sources
@subsection Compilation of one or several sources
@c ---------------------------------------------

@noindent
If GPRbuild is invoked with @option{-u} or @option{-U} 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 @option{-f} is
also specified. Then GPRbuild will stop its execution.

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

If GPRbuild is invoked with @option{-u} and no source file name is specified
on the command line, GPRbuild will compile or recompile all the sources of the
@emph{main} project and then stop.

In contrast, if GPRbuild is invoked with @option{-U}, and again no source file name is specified
on the command line, GPRbuild will compile or recompile all the sources of @emph{all
the projects in the project tree} and then stop.

@c ---------------------------------------------
@node Compilation Phase
@subsection Compilation Phase
@c ---------------------------------------------

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

@itemize @bullet
@item all the sources in languages other than Ada

@item if there are no main specified, all the Ada sources

@item if there is a non Ada main, but no attribute @code{Roots} specified for
  this main, all the Ada sources

@item if there is a main with an attribute @code{Roots} specified, all
  the Ada sources in the closures of these Roots.

@item if there is an Ada main specified, all the Ada sources in the closure
  of the main

@end itemize

@noindent
Attribute Roots takes as an index a main and a string list value. Each string
in the list is the name of an Ada library unit.

Example:

@smallexample
   for Roots ("main.c") use ("pkga", "pkgb");
@end smallexample

@noindent
Package PkgA and PkgB will be considered, and all the Ada units in their
closure will also be considered.

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 When @option{-s} is used: the switch file does not exist

@item When @option{-s} is used: 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 if switch @option{-s} is used

@end itemize

@noindent
The compiler for the language corresponding to the source file name 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

@noindent
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.

@c ---------------------------------------------
@node Post-Compilation Phase
@subsection Post-Compilation Phase
@c ---------------------------------------------

@noindent
The post-compilation phase has two parts: library building and program binding.

If there are libraries that need to be built or rebuilt, @emph{gprbuild} will
call the library builder, specified by attribute @code{Library_Builder}.
This is generally the tool @emph{gprlib}, provided with GPRbuild. If gprbuild
can determine that a library is already up to date, then the library builder
will not be called.

If there are mains specified, and for these mains there are sources of
languages with a binder driver (specified by attribute Binder'Driver
(<language>), then the binder driver is called for each such main, but only
if it needs to.

For Ada, the binder driver is normally @emph{gprbind}, which will call
the appropriate version of @emph{gnatbind}, that either the one in the same
directory as the Ada compiler or the fist one found on the path.
When neither of those is appropriate, it is possible to specify to
@emph{gprbind} the full path of @emph{gnatbind}, using the Binder switch
@code{--gnatbind_path=}.

Example:

@smallexample
   package Binder is
      for Switches ("Ada") use ("--gnatbind_path=/toto/gnatbind");
   end Binder;
@end smallexample

@noindent
If gprbuild can determine that the artifacts from a previous
post-compilation phase are already up to date, the binder driver is not called.

If there are no libraries and no binder drivers, then the post-compilation
phase is empty.

@c ---------------------------------------------
@node Linking Phase
@subsection Linking Phase
@c ---------------------------------------------

@noindent
When there are mains specified, either in attribute Main or on the command
line, and these mains are not up to date, the linker is invoked for each main,
with all the specified or implied options, including the object files generated
during the post-compilation phase by the binder drivers.

@c ---------------------------------------------
@node Incompatibilities with gnatmake
@subsection Incompatibilities with gnatmake
@c ---------------------------------------------

@noindent
Here is a list of incompatibilities between gnatmake invoked with a
project file and gprbuild:

@itemize @bullet
@item gprbuild never recompiles the runtime sources.

@item gnatmake switches that are not recognized by gprbuild:

  @itemize -
  @item -a (Consider all files, even readonly ali files)
  @item -M (List object file dependences for Makefile)
  @item -n (Check objects up to date, output next file to compile if not)
  @item -x (Allow compilation of needed units external to the projects)
  @item -z No main subprogram (zero main)
  @item --GCC=command
  @item --GNATBIND=command
  @item --GNATLINK=command
  @item -aLdir (Skip missing library sources if ali in dir)
  @item -Adir (like -aLdir -aIdir)
  @item -aOdir (Specify library/object files search path)
  @item -aIdir (Specify source files search path)
  @item -Idir (Like -aIdir -aOdir)
  @item -I- (Don't look for sources & library files in the default directory)
  @item -Ldir (Look for program libraries also in dir)

  @end itemize

@item The switches that are not directly recognized by gprbuild and passed to
  the Ada compiler are only:

  @itemize -
  @item -nostdlib
  @item -nostdinc
  @item -fstack-check
  @item -fno-inline
  @item -Oxxx (any switch starting with -O)
  @item -gxxx (any switch starting with -g)
  @end itemize

@end itemize


@c ---------------------------------------------
@node Configuring with GPRconfig
@section Configuring with GPRconfig
@c ---------------------------------------------

@noindent


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

@c ---------------------------------------------
@node Configuration
@subsection Configuration
@c ---------------------------------------------

@noindent
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. The following tests are performed in the specified order, and the
first that matches provides the configuration file to use.

@itemize @bullet
@item If a file has a base names that matches @code{<target>-<rts>.cgpr},
  @code{<target.cgpr}, @code{<rts>.cgpr} or @code{default.cgpr} is found in
  the default configuration files directory, this file is used. The target
  and rts parameters are specified via the @code{--target} and @code{--RTS}
  switches of @code{gprbuild}. The default directory is is @file{share/gpr}
  in the installation directory of @code{gprbuild}

@item If not found, the environment variable @code{GPR_CONFIG} is tested
  to check whether it contains the name of a valid configuration file. This
  can either be an absolute path name or a base name that will be searched
  in the same default directory as above.

@item If still not found and you used the @code{--autoconf} switch, then
  a new configuration file is automatically generated based on the specified
  target and on the list of languages specified in your projects.

  GPRbuild assumes 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

@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 @bullet
@item The following command triggers interactive mode. The configuration will be
  generated in GPRbuild's default location, @code{./default.cgpr)}, unless
  @option{-o} is used.

  @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


@c ---------------------------------------------
@node Using GPRconfig
@subsection Using GPRconfig
@c ---------------------------------------------

@noindent
@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}

  @noindent
  @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 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}.

  Another possible more frequent use of @option{name} is to specify the base
  name of an executable. For instance, if you prefer to use a diab C compiler
  (executable is called @file{dcc}) instead of @file{gcc}, even if the latter
  appears first in the path, you could specify @file{dcc} as the name parameter.

  @CODESAMPLE{gprconfig --config Ada,,,/usr/bin       # automatic parameters@NL{}
  gprconfig --config C,,,/usr/bin,GCC     # automatic version@NL{}
  gprconfig --config C,,,/usr/bin,gcc     # same as above, with exec name}

  @noindent
  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 user
  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
@subsection 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}.}

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::
* GPRconfig external values::
* GPRconfig variable substitution::
* Configurations::
@end menu

@c ---------------------------------------------
@node General file format
@subsubsection 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 file, or split across several files.

@c ---------------------------------------------
@node Compiler description
@subsubsection 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 optional
  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

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

  @noindent
  @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.

  If this isn't specified, the compiler will always be considered as matching
  on the current target.

@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 names 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>}.

  As a special case, gprconfig will merge two runtimes if the XML nodes
  refer to the same directories after normalization and resolution of
  links. As such, on Unix systems, the "adalib" link to "rts-native/adalib"
  (or similar) will be ignored and only the "native" runtime will be
  displayed.

@end table

@c ---------------------------------------------
@node GPRconfig external values
@subsubsection GPRconfig 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>}

  @noindent
  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 a @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>}

  @noindent
  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" contents="">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 or file name, not a subdirectory. Remember to quote special
  characters, including ``.'', if you do not mean to use a regexp.

  The optional attribute @var{contents} can be used to indicate that the
  contents of the file should be read. The first line that matches the regular
  expression given by @var{contents} will be used as a file path instead of
  the file matched by @var{regexp}. This is in general used on platforms that
  do not have symbolic links, and a file is used instead of a symbolic link.
  In general, this will work better than @var{group} specifies a string rather
  than a parenthesis group, since the latter will match the path matched by
  @var{regexp}, not the one read in the file.

  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>}

  @noindent
  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>}

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


@c ---------------------------------------------
@node GPRconfig variable substitution
@subsubsection GPRconfig 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 variables 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.

The variables are used in two contexts: either in a
@code{<compiler_description>} node, in which case the variable refers to
the compiler we are describing, or within a @code{<configuration>} node.
In the latter case, and since there might be several compilers selected,
you need to further specify the variable by adding in parenthesis the
language of the compiler you are interested in.

For instance, the following is invalid:

@CODESAMPLE{
 <configuration>
  <compilers>
   <compiler name="GNAT" />
  </compilers>
  <targets negate="true">
    <target name="^powerpc-elf$"/>
  </targets>
  <config>
    package Compiler is
       for Driver ("Ada") use "$@{PATH@}gcc";   --  Invalid !
    end Compiler;
  </config>
 </configuration>
}

The trouble with the above is that if you are using multiple languages
like C and Ada, both compilers will match the "negate" part, and therefore
there is an ambiguity for the value of @code{$@{PATH@}}. To prevent such
issues, you need to use the following syntax instead when inside a
@code{<configuration>} node:

@CODESAMPLE{
    for Driver ("Ada") use "$@{PATH(ada)@}gcc";   --  Correct
}

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.

This variable takes the language of the compiler as an optional index when
in a @code{<configuration>} block: if the language is specified, the target
returned by that specific compiler is used; otherwise, the normalized target
common to all the selected compilers will be returned (target normalization
is also described in the knowledge base's XML files).

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

@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.
This variable never takes a language in parameter, even within a
@code{<configuration>} node.

@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
@subsubsection 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. Note that
the regexp might match a substring of the host name, so you might want
to surround it with "^" and "$" so that it only matches the whole host
name (for instance, "elf" would match "powerpc-elf", but "^elf$" would
not).

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
@section Configuration File Reference
@c ---------------------------------------------

@noindent
@c ??? From the "Important concepts" section
  A text file using the project file syntax. It defines languages and
  their characteristics as well as toolchains for those languages and their
  characteristics.
@c ??? end

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 @option{--config=} or @option{--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.

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

@c ---------------------------------------------
@node Project Level Attributes
@subsection Project Level Attributes
@c ---------------------------------------------

@noindent


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

@c ---------------------------------------------
@node General Attributes
@subsubsection General Attributes
@c ---------------------------------------------

@noindent
@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

  @noindent
  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


@c ---------------------------------------------
@node General Library Related Attributes
@subsubsection General Library Related Attributes
@c ---------------------------------------------

@noindent
@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


@c ---------------------------------------------
@node Archive Related Attributes
@subsubsection Archive Related Attributes
@c ---------------------------------------------

@noindent
@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


@c ---------------------------------------------
@node Shared Library Related Attributes
@subsubsection Shared Library Related Attributes
@c ---------------------------------------------

@noindent
@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 a 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

  @noindent
  This attribute is used by GPRlib to link shared libraries with Ada code.
@end itemize


@c ---------------------------------------------
@node Package Naming
@subsection Package Naming
@c ---------------------------------------------

@noindent
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


@c ---------------------------------------------
@node Package Builder
@subsection Package Builder
@c ---------------------------------------------

@noindent
@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


@c ---------------------------------------------
@node Package Compiler
@subsection Package Compiler
@c ---------------------------------------------

@noindent


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

@c ---------------------------------------------
@node General Compilation Attributes
@subsubsection General Compilation Attributes
@c ---------------------------------------------

@noindent
@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


@c ---------------------------------------------
@node Mapping File Related Attributes
@subsubsection Mapping File Related Attributes
@c ---------------------------------------------

@noindent
@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


@c ---------------------------------------------
@node Config File Related Attributes
@subsubsection Config File Related Attributes
@c ---------------------------------------------

@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

@noindent
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


@c ---------------------------------------------
@node Dependency Related Attributes
@subsubsection Dependency Related Attributes
@c ---------------------------------------------

@noindent
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

  @noindent
  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

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


@c ---------------------------------------------
@node Search Path Related Attributes
@subsubsection Search Path Related Attributes
@c ---------------------------------------------

@noindent
@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

  @noindent
  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

  @noindent
  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 contains 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


@c ---------------------------------------------
@node Package Binder
@subsection Package Binder
@c ---------------------------------------------

@noindent
@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 contains 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


@c ---------------------------------------------
@node Package Linker
@subsection Package Linker
@c ---------------------------------------------

@noindent
@itemize @bullet
@item Driver

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

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

@item Required_Switches

  Specifies the minimum options to be used when invoking the linker. Those
  options are happened at the end of the link command so that potentially
  conflicting user options take precedence.

@item Map_File_Option

  Specifies the option to be used when the linker is asked to produce
  a map file.

  @smallexample
   for Map_File_Option use "-Wl,-Map,";
  @end smallexample

@item Max_Command_Line_Length

  Specifies the maximum length of the command line to invoke the linker.
  If this maximum length is reached, a response file will be used to shorten
  the length of the command line. This is only taken into account when
  attribute Response_File_Format is specified.

  @smallexample
   for Max_Command_Line_Length use "8000";
  @end smallexample

@item Response_File_Format

  Specifies the format of the response file to be generated when the maximum
  length of the command line to invoke the linker is reached. This is only
  taken into account when attribute Max_Command_Line_Length is specified.

  The allowed case-insensitive values are:

    @itemize @bullet

    @item "GNU"
     Used when the underlying linker is gnu ld.

    @item "Object_List"
     Used when the response file is a list of object files, one per line.

    @item "GCC_GNU"
     Used with recent version of gcc when the underlined linker is gnu ld.

    @item "GCC_Object_List"
     Used with recent version of gcc when the underlying linker is not gnu ld.
    @end itemize

  @smallexample
   for Response_File_Format use "GCC_GNU";
  @end smallexample

@item Response_File_Switches
  Specifies the option(s) that must precede the response file name when
  when invoking the linker. This is only taken into account when both
  attributes Max_Command_Line_Length and Response_File_Format are specified.

  @smallexample
    for Response_File_Switches  use ("-Wl,-f,");
  @end smallexample
@end itemize

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

@noindent
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

@menu
* Switches for GPRclean::
@end menu

@c ---------------------------------------------
@node Switches for GPRclean
@subsection Switches for GPRclean
@c ---------------------------------------------

@noindent
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

@include gfdl.texi

@c ---------------------------------------------
@node Index
@unnumbered Index
@c ---------------------------------------------

@noindent
@printindex cp


@contents

@bye

