Subversion Repositories openrisc

@set gprconfig GPRconfig

@c ------ projects.texi

@c Copyright (C) 2002-2012, Free Software Foundation, Inc.

@c This file is shared between the GNAT user's guide and gprbuild. It is not

@c compilable on its own, you should instead compile the other two manuals.

@c For that reason, there is no toplevel @menu

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

@node GNAT Project Manager

@chapter GNAT Project Manager

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

@noindent

@menu

* Introduction::

* Building With Projects::

* Organizing Projects into Subsystems::

* Scenarios in Projects::

* Library Projects::

* Project Extension::

* Aggregate Projects::

* Aggregate Library Projects::

* Project File Reference::

@end menu

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

@node Introduction

@section Introduction

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

@noindent

This chapter describes GNAT's @emph{Project Manager}, a facility that allows

you to manage complex builds involving a number of source files, directories,

and options for different system configurations. In particular,

project files allow you to specify:

@itemize @bullet

@item The directory or set of directories containing the source files, and/or the

  names of the specific source files themselves

@item The directory in which the compiler's output

  (@file{ALI} files, object files, tree files, etc.) is to be placed

@item The directory in which the executable programs are to be placed

@item Switch settings for any of the project-enabled tools;

  you can apply these settings either globally or to individual compilation units.

@item The source files containing the main subprogram(s) to be built

@item The source programming language(s)

@item Source file naming conventions; you can specify these either globally or for

  individual compilation units (@pxref{Naming Schemes}).

@item Change any of the above settings depending on external values, thus enabling

  the reuse of the projects in various @b{scenarios} (@pxref{Scenarios

  in Projects}).

@item Automatically build libraries as part of the build process

  (@pxref{Library Projects}).

@end itemize

@noindent

Project files are written in a syntax close to that of Ada, using familiar

notions such as packages, context clauses, declarations, default values,

assignments, and inheritance (@pxref{Project File Reference}).

Project files can be built hierarchically from other project files, simplifying

complex system integration and project reuse (@pxref{Organizing Projects into

Subsystems}).

@itemize @bullet

@item One project can import other projects containing needed source files.

  More generally, the Project Manager lets you structure large development

  efforts into hierarchical subsystems, where build decisions are delegated

  to the subsystem level, and thus different compilation environments

  (switch settings) used for different subsystems.

@item You can organize GNAT projects in a hierarchy: a child project

  can extend a parent project, inheriting the parent's source files and

  optionally overriding any of them with alternative versions

  (@pxref{Project Extension}).

@end itemize

@noindent

Several tools support project files, generally in addition to specifying

the information on the command line itself). They share common switches

to control the loading of the project (in particular

@option{^-P^/PROJECT_FILE=^@emph{projectfile}} and

@option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}}).

@xref{Switches Related to Project Files}.

The Project Manager supports a wide range of development strategies,

for systems of all sizes.  Here are some typical practices that are

easily handled:

@itemize @bullet

@item Using a common set of source files and generating object files in different

  directories via different switch settings. It can be used for instance, for

  generating separate sets of object files for debugging and for production.

@item Using a mostly-shared set of source files with different versions of

  some units or subunits. It can be used for instance, for grouping and hiding

@end itemize

@noindent

all OS dependencies in a small number of implementation units.

Project files can be used to achieve some of the effects of a source

versioning system (for example, defining separate projects for

the different sets of sources that comprise different releases) but the

Project Manager is independent of any source configuration management tool

that might be used by the developers.

The various sections below introduce the different concepts related to

projects. Each section starts with examples and use cases, and then goes into

the details of related project file capabilities.

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

@node Building With Projects

@section Building With Projects

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

@noindent

In its simplest form, a unique project is used to build a single executable.

This section concentrates on such a simple setup. Later sections will extend

this basic model to more complex setups.

The following concepts are the foundation of project files, and will be further

detailed later in this documentation. They are summarized here as a reference.

@table @asis

@item @b{Project file}:

  A text file using an Ada-like syntax, generally using the @file{.gpr}

  extension. It defines build-related characteristics of an application.

  The characteristics include the list of sources, the location of those

  sources, the location for the generated object files, the name of

  the main program, and the options for the various tools involved in the

  build process.

@item @b{Project attribute}:

  A specific project characteristic is defined by an attribute clause. Its

  value is a string or a sequence of strings. All settings in a project

  are defined through a list of predefined attributes with precise

  semantics. @xref{Attributes}.

@item @b{Package in a project}:

  Global attributes are defined at the top level of a project.

  Attributes affecting specific tools are grouped in a

  package whose name is related to tool's function. The most common

  packages are @code{Builder}, @code{Compiler}, @code{Binder},

  and @code{Linker}. @xref{Packages}.

@item @b{Project variables}:

  In addition to attributes, a project can use variables to store intermediate

  values and avoid duplication in complex expressions. It can be initialized

  with a value coming from the environment.

  A frequent use of variables is to define scenarios.

  @xref{External Values}, @xref{Scenarios in Projects}, and @xref{Variables}.

@item @b{Source files} and @b{source directories}:

  A source file is associated with a language through a naming convention. For

  instance, @code{foo.c} is typically the name of a C source file;

  @code{bar.ads} or @code{bar.1.ada} are two common naming conventions for a

  file containing an Ada spec. A compilation unit is often composed of a main

  source file and potentially several auxiliary ones, such as header files in C.

  The naming conventions can be user defined @xref{Naming Schemes}, and will

  drive the builder to call the appropriate compiler for the given source file.

  Source files are searched for in the source directories associated with the

  project through the @b{Source_Dirs} attribute. By default, all the files (in

  these source directories) following the naming conventions associated with the

  declared languages are considered to be part of the project. It is also

  possible to limit the list of source files using the @b{Source_Files} or

  @b{Source_List_File} attributes. Note that those last two attributes only

  accept basenames with no directory information.

@item @b{Object files} and @b{object directory}:

  An object file is an intermediate file produced by the compiler from a

  compilation unit. It is used by post-compilation tools to produce

  final executables or libraries. Object files produced in the context of

  a given project are stored in a single directory that can be specified by the

  @b{Object_Dir} attribute. In order to store objects in

  two or more object directories, the system must be split into

  distinct subsystems with their own project file.

@end table

The following subsections introduce gradually all the attributes of interest

for simple build needs. Here is the simple setup that will be used in the

following examples.

The Ada source files @file{pack.ads}, @file{pack.adb}, and @file{proc.adb} are in

the @file{common/} directory. The file @file{proc.adb} contains an Ada main

subprogram @code{Proc} that @code{with}s package @code{Pack}. We want to compile

these source files with the switch @option{-O2}, and put the resulting files in

the directory @file{obj/}.

@smallexample

@group

^common/^[COMMON]^

  pack.ads

  pack.adb

  proc.adb

@end group

@group

^common/release/^[COMMON.RELEASE]^

  proc.ali, proc.o pack.ali, pack.o

@end group

@end smallexample

@noindent

Our project is to be called @emph{Build}. The name of the

file is the name of the project (case-insensitive) with the

@file{.gpr} extension, therefore the project file name is @file{build.gpr}. This

is not mandatory, but a warning is issued when this convention is not followed.

This is a very simple example, and as stated above, a single project

file is enough for it. We will thus create a new file, that for now

should contain the following code:

@smallexample

@b{project} Build @b{is}

@b{end} Build;

@end smallexample

@menu

* 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::

@end menu

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

@node Source Files and Directories

@subsection Source Files and Directories

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

@noindent

When you create a new project, the first thing to describe is how to find the

corresponding source files. This is the only settings that are needed by all

the tools that will use this project (builder, compiler, binder and linker for

the compilation, IDEs to edit the source files,@dots{}).

@cindex Source directories

First step is to declare the source directories, which are the directories

to be searched to find source files. In the case of the example,

the @file{common} directory is the only source directory.

@cindex @code{Source_Dirs}

There are several ways of defining source directories:

@itemize @bullet

@item When the attribute @b{Source_Dirs} is not used, a project contains a

  single source directory which is the one where the project file itself

  resides. In our example, if @file{build.gpr} is placed in the @file{common}

  directory, the project has the needed implicit source directory.

@item The attribute @b{Source_Dirs} can be set to a list of path names, one

  for each of the source directories. Such paths can either be absolute

  names (for instance @file{"/usr/local/common/"} on UNIX), or relative to the

  directory in which the project file resides (for instance "." if

  @file{build.gpr} is inside @file{common/}, or "common" if it is one level up).

  Each of the source directories must exist and be readable.

@cindex portability

  The syntax for directories is platform specific. For portability, however,

  the project manager will always properly translate UNIX-like path names to

  the native format of specific platform. For instance, when the same project

  file is to be used both on Unix and Windows, "/" should be used as the

  directory separator rather than "\".

@item The attribute @b{Source_Dirs} can automatically include subdirectories

  using a special syntax inspired by some UNIX shells. If any of the path in

  the list ends with @emph{"**"}, then that path and all its subdirectories

  (recursively) are included in the list of source directories. For instance,

  @file{**} and @file{./**} represent the complete directory tree rooted at ".".

@cindex Source directories, recursive

@cindex @code{Excluded_Source_Dirs}

  When using that construct, it can sometimes be convenient to also use the

  attribute @b{Excluded_Source_Dirs}, which is also a list of paths. Each entry

  specifies a directory whose immediate content, not including subdirs, is to

  be excluded. It is also possible to exclude a complete directory subtree

  using the "**" notation.

@cindex @code{Ignore_Source_Sub_Dirs}

  It is often desirable to remove, from the source directories, directory

  subtrees rooted at some subdirectories. An example is the subdirectories

  created by a Version Control System such as Subversion that creates directory

  subtrees .svn/**. To do that, attribute  @b{Ignore_Source_Sub_Dirs} can be

  used. It specifies the list of simple file names for the root of these

  undesirable directory subtrees.

@end itemize

@noindent

When applied to the simple example, and because we generally prefer to have

the project file at the toplevel directory rather than mixed with the sources,

we will create the following file

@smallexample

   build.gpr

   @b{project} Build @b{is}

      @b{for} Source_Dirs @b{use} ("common");  --  <<<<

   @b{end} Build;

@end smallexample

@noindent

Once source directories have been specified, one may need to indicate

source files of interest. By default, all source files present in the source

directories are considered by the project manager. When this is not desired,

it is possible to specify the list of sources to consider explicitly.

In such a case, only source file base names are indicated and not

their absolute or relative path names. The project manager is in charge of

locating the specified source files in the specified source directories.

@itemize @bullet

@item By default, the project manager  search for all source files of all

  specified languages in all the source directories.

  Since the project manager was initially developed for Ada environments, the

  default language is usually Ada and the above project file is complete: it

  defines without ambiguity the sources composing the project: that is to say,

  all the sources in subdirectory "common" for the default language (Ada) using

  the default naming convention.

@cindex @code{Languages}

  However, when compiling a multi-language application, or a pure C

  application, the project manager must be told which languages are of

  interest, which is done by setting the @b{Languages} attribute to a list of

  strings, each of which is the name of a language. Tools like

  @command{gnatmake} only know about Ada, while other tools like

  @command{gprbuild} know about many more languages such as C, C++, Fortran,

  assembly and others can be added dynamically.

@cindex Naming scheme

  Even when using only Ada, the default naming might not be suitable. Indeed,

  how does the project manager recognizes an "Ada file" from any other

  file? Project files can describe the naming scheme used for source files,

  and override the default (@pxref{Naming Schemes}). The default is the

  standard GNAT extension (@file{.adb} for bodies and @file{.ads} for

  specs), which is what is used in our example, explaining why no naming scheme

  is explicitly specified.

  @xref{Naming Schemes}.

@item @code{Source Files}

  @cindex @code{Source_Files}

  In some cases, source directories might contain files that should not be

  included in a project. One can specify the explicit list of file names to

  be considered through the @b{Source_Files} attribute.

  When this attribute is defined, instead of looking at every file in the

  source directories, the project manager takes only those names into

  consideration  reports  errors if they cannot be found in the source

  directories or does not correspond to the naming scheme.

@item For various reasons, it is sometimes useful to have a project with no

  sources (most of the time because the attributes defined in the project

  file will be reused in other projects, as explained in @pxref{Organizing

  Projects into Subsystems}. To do this, the attribute

  @emph{Source_Files} is set to the empty list, i.e. @code{()}. Alternatively,

  @emph{Source_Dirs} can be set to the empty list, with the same

  result.

@item @code{Source_List_File}

@cindex @code{Source_List_File}

  If there is a great number of files, it might be more convenient to use

  the attribute @b{Source_List_File}, which specifies the full path of a file.

  This file must contain a list of source file names (one per line, no

  directory information) that are searched as if they had been defined

  through @emph{Source_Files}. Such a file can easily be created through

  external tools.

  A warning is issued if both attributes @code{Source_Files} and

  @code{Source_List_File} are given explicit values. In this case, the

  attribute @code{Source_Files} prevails.

@item @code{Excluded_Source_Files}

@cindex @code{Excluded_Source_Files}

@cindex @code{Locally_Removed_Files}

@cindex @code{Excluded_Source_List_File}

  Specifying an explicit list of files is not always convenient.It might be

  more convenient to use the default search rules with specific exceptions.

  This can be done thanks to the attribute @b{Excluded_Source_Files}

  (or its synonym @b{Locally_Removed_Files}).

  Its value is the list of file names that should not be taken into account.

  This attribute is often used when extending a project, @xref{Project

  Extension}. A similar attribute @b{Excluded_Source_List_File} plays the same

  role but takes the name of file containing file names similarly to

  @code{Source_List_File}.

@end itemize

@noindent

In most simple cases, such as the above example, the default source file search

behavior provides the expected result, and we do not need to add anything after

setting @code{Source_Dirs}. The project manager automatically finds

@file{pack.ads}, @file{pack.adb} and @file{proc.adb} as source files of the

project.

Note that it is considered an error for a project file to have no sources

attached to it unless explicitly declared as mentioned above.

If the order of the source directories is known statically, that is if

@code{"**"} is not used in the string list @code{Source_Dirs}, then there may

be several files with the same source file name sitting in different

directories of the project. In this case, only the file in the first directory

is considered as a source of the project and the others are hidden. If

@code{"**"} is used in the string list @code{Source_Dirs}, it is an error

to have several files with the same source file name in the same directory

@code{"**"} subtree, since there would be an ambiguity as to which one should

be used. However, two files with the same source file name may exist in two

single directories or directory subtrees. In this case, the one in the first

directory or directory subtree is a source of the project.

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

@node Object and Exec Directory

@subsection Object and Exec Directory

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

@noindent

The next step when writing a project is to indicate where the compiler should

put the object files. In fact, the compiler and other tools might create

several different kind of files (for GNAT, there is the object file and the ALI

file for instance). One of the important concepts in projects is that most

tools may consider source directories as read-only and do not attempt to create

new or temporary files there. Instead, all files are created in the object

directory. It is of course not true for project-aware IDEs, whose purpose it is

to create the source files.

@cindex @code{Object_Dir}

The object directory is specified through the @b{Object_Dir} attribute.

Its value is the path to the object directory, either absolute or

relative to the directory containing the project file. This

directory must already exist and be readable and writable, although

some tools have a switch to create the directory if needed (See

the switch @code{-p} for @command{gnatmake} and @command{gprbuild}).

If the attribute @code{Object_Dir} is not specified, it defaults to

the project directory, that is the directory containing the project file.

For our example, we can specify the object dir in this way:

@smallexample

   @b{project} Build @b{is}

      @b{for} Source_Dirs @b{use} ("common");

      @b{for} Object_Dir @b{use} "obj";   --  <<<<

   @b{end} Build;

@end smallexample

@noindent

As mentioned earlier, there is a single object directory per project. As a

result, if you have an existing system where the object files are spread in

several directories, you can either move all of them into the same directory if

you want to build it with a single project file, or study the section on

subsystems (@pxref{Organizing Projects into Subsystems}) to see how each

separate object directory can be associated with one of the subsystem

constituting the application.

When the @command{linker} is called, it usually creates an executable. By

default, this executable is placed in the object directory of the project. It

might be convenient to store it in its own directory.

@cindex @code{Exec_Dir}

This can be done through the @code{Exec_Dir} attribute, which, like

@emph{Object_Dir} contains a single absolute or relative path and must point to

an existing and writable directory, unless you ask the tool to create it on

your behalf. When not specified, It defaults to the object directory and

therefore to the project file's directory if neither @emph{Object_Dir} nor

@emph{Exec_Dir} was specified.

In the case of the example, let's place the executable in the root

of the hierarchy, ie the same directory as @file{build.gpr}. Hence

the project file is now

@smallexample

   @b{project} Build @b{is}

      @b{for} Source_Dirs @b{use} ("common");

      @b{for} Object_Dir @b{use} "obj";

      @b{for} Exec_Dir @b{use} ".";  --   <<<<

   @b{end} Build;

@end smallexample

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

@node Main Subprograms

@subsection Main Subprograms

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

@noindent

In the previous section, executables were mentioned. The project manager needs

to be taught what they are. In a project file, an executable is indicated by

pointing to source file of the main subprogram. In C this is the file that

contains the @code{main} function, and in Ada the file that contains the main

unit.

There can be any number of such main files within a given project, and thus

several executables can be built in the context of a single project file. Of

course, one given executable might not (and in fact will not) need all the

source files referenced by the project. As opposed to other build environments

such as @command{makefile}, one does not need to specify the list of

dependencies of each executable, the project-aware builders knows enough of the

semantics of the languages to build ands link only the necessary elements.

@cindex @code{Main}

The list of main files is specified via the @b{Main} attribute. It contains

a list of file names (no directories). If a project defines this

attribute, it is not necessary to identify  main files on the

command line when invoking a builder, and editors like

@command{GPS} will be able to create extra menus to spawn or debug the

corresponding executables.

@smallexample

   @b{project} Build @b{is}

      @b{for} Source_Dirs @b{use} ("common");

      @b{for} Object_Dir @b{use} "obj";

      @b{for} Exec_Dir @b{use} ".";

      @b{for} Main @b{use} ("proc.adb");  --   <<<<

   @b{end} Build;

@end smallexample

@noindent

If this attribute is defined in the project, then spawning the builder

with a command such as

@smallexample

   gnatmake ^-Pbuild^/PROJECT_FILE=build^

@end smallexample

@noindent

automatically builds all the executables corresponding to the files

listed in the @emph{Main} attribute. It is possible to specify one

or more executables on the command line to build a subset of them.

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

@node Tools Options in Project Files

@subsection Tools Options in Project Files

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

@noindent

We now have a project file that fully describes our environment, and can be

used to build the application with a simple @command{gnatmake} command as seen

in the previous section. In fact, the empty project we showed immediately at

the beginning (with no attribute at all) could already fulfill that need if it

was put in the @file{common} directory.

Of course, we always want more control. This section will show you how to

specify the compilation switches that the various tools involved in the

building of the executable should use.

@cindex command line length

Since source names and locations are described into the project file, it is not

necessary to use switches on the command line for this purpose (switches such

as -I for gcc). This removes a major source of command line length overflow.

Clearly, the builders will have to communicate this information one way or

another to the underlying compilers and tools they call but they usually use

response files for this and thus should not be subject to command line

overflows.

Several tools are participating to the creation of an executable: the compiler

produces object files from the source files; the binder (in the Ada case)

creates an source file that takes care, among other things, of elaboration

issues and global variables initialization; and the linker gathers everything

into a single executable that users can execute. All these tools are known by

the project manager and will be called with user defined switches from the

project files. However, we need to introduce a new project file concept to

express which switches to be used for any of the tools involved in the build.

@cindex project file packages

A project file is subdivided into zero or more @b{packages}, each of which

contains the attributes specific to one tool (or one set of tools). Project

files use an Ada-like syntax for packages. Package names permitted in project

files are restricted to a predefined set (@pxref{Packages}), and the contents

of packages are limited to a small set of constructs and attributes

(@pxref{Attributes}).

Our example project file can be extended with the following empty packages. At

this stage, they could all be omitted since they are empty, but they show which

packages would be involved in the build process.

@smallexample

   @b{project} Build @b{is}

      @b{for} Source_Dirs @b{use} ("common");

      @b{for} Object_Dir @b{use} "obj";

      @b{for} Exec_Dir @b{use} ".";

      @b{for} Main @b{use} ("proc.adb");

      @b{package} Builder @b{is}  --<<<  for gnatmake and gprbuild

      @b{end} Builder;

      @b{package} Compiler @b{is} --<<<  for the compiler

      @b{end} Compiler;

      @b{package} Binder @b{is}   --<<<  for the binder

      @b{end} Binder;

      @b{package} Linker @b{is}   --<<<  for the linker

      @b{end} Linker;

   @b{end} Build;

@end smallexample

@noindent

Let's first examine the compiler switches. As stated in the initial description

of the example, we want to compile all files with @option{-O2}. This is a

compiler switch, although it is usual, on the command line, to pass it to the

builder which then passes it to the compiler. It is recommended to use directly

the right package, which will make the setup easier to understand for other

people.

Several attributes can be used to specify the switches:

@table @asis

@item @b{Default_Switches}:

@cindex @code{Default_Switches}

  This is the first mention in this manual of an @b{indexed attribute}. When

  this attribute is defined, one must supply an @emph{index} in the form of a

  literal string.

  In the case of @emph{Default_Switches}, the index is the name of the

  language to which the switches apply (since a different compiler will

  likely be used for each language, and each compiler has its own set of

  switches). The value of the attribute is a list of switches.

  In this example, we want to compile all Ada source files with the

  @option{-O2} switch, and the resulting project file is as follows

  (only the @code{Compiler} package is shown):

  @smallexample

  @b{package} Compiler @b{is}

    @b{for} Default_Switches ("Ada") @b{use} ("-O2");

  @b{end} Compiler;

  @end smallexample

@item @b{Switches}:

@cindex @code{Switches}

  in some cases, we might want to use specific switches

  for one or more files. For instance, compiling @file{proc.adb} might not be

  possible at high level of optimization because of a compiler issue.

  In such a case, the @emph{Switches}

  attribute (indexed on the file name) can be used and will override the

  switches defined by @emph{Default_Switches}. Our project file would

  become:

  @smallexample

  @b{package} Compiler @b{is}

    @b{for} Default_Switches ("Ada") @b{use} ("-O2");

    @b{for} Switches ("proc.adb") @b{use} ("-O0");

  @b{end} Compiler;

  @end smallexample

  @noindent

  @code{Switches} may take a pattern as an index, such as in:

  @smallexample

  @b{package} Compiler @b{is}

    @b{for} Default_Switches ("Ada") @b{use} ("-O2");

    @b{for} Switches ("pkg*") @b{use} ("-O0");

  @b{end} Compiler;

  @end smallexample

  @noindent

  Sources @file{pkg.adb} and @file{pkg-child.adb} would be compiled with -O0,

  not -O2.

  @noindent

  @code{Switches} can also be given a language name as index instead of a file

  name in which case it has the same semantics as @emph{Default_Switches}.

  However, indexes with wild cards are never valid for language name.

@item @b{Local_Configuration_Pragmas}:

@cindex @code{Local_Configuration_Pragmas}

  this attribute may specify the path

  of a file containing configuration pragmas for use by the Ada compiler,

  such as @code{pragma Restrictions (No_Tasking)}. These pragmas will be

  used for all the sources of the project.

@end table

The switches for the other tools are defined in a similar manner through the

@b{Default_Switches} and @b{Switches} attributes, respectively in the

@emph{Builder} package (for @command{gnatmake} and @command{gprbuild}),

the @emph{Binder} package (binding Ada executables) and the @emph{Linker}

package (for linking executables).

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

@node Compiling with Project Files

@subsection Compiling with Project Files

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

@noindent

Now that our project files are written, let's build our executable.

Here is the command we would use from the command line:

@smallexample

   gnatmake ^-Pbuild^/PROJECT_FILE=build^

@end smallexample

@noindent

This will automatically build the executables specified through the

@emph{Main} attribute: for each, it will compile or recompile the

sources for which the object file does not exist or is not up-to-date; it

will then run the binder; and finally run the linker to create the

executable itself.

@command{gnatmake} only knows how to handle Ada files. By using

@command{gprbuild} as a builder, you could automatically manage C files the

same way: create the file @file{utils.c} in the @file{common} directory,

set the attribute @emph{Languages} to @code{"(Ada, C)"}, and run

@smallexample

   gprbuild ^-Pbuild^/PROJECT_FILE=build^

@end smallexample

@noindent

Gprbuild knows how to recompile the C files and will

recompile them only if one of their dependencies has changed. No direct

indication on how to build the various elements is given in the

project file, which describes the project properties rather than a

set of actions to be executed. Here is the invocation of

@command{gprbuild} when building a multi-language program:

@smallexample

$ gprbuild -Pbuild

gcc -c proc.adb

gcc -c pack.adb

gcc -c utils.c

gprbind proc

...

gcc proc.o -o proc

@end smallexample

@noindent

Notice the three steps described earlier:

@itemize @bullet

@item The first three gcc commands correspond to the compilation phase.

@item The gprbind command corresponds to the post-compilation phase.

@item The last gcc command corresponds to the final link.

@end itemize

@noindent

@cindex @option{-v} option (for GPRbuild)

The default output of GPRbuild's execution is kept reasonably simple and easy

to understand. In particular, some of the less frequently used commands are not

shown, and some parameters are abbreviated. So it is not possible to rerun the

effect of the @command{gprbuild} command by cut-and-pasting its output.

GPRbuild's option @code{-v} provides a much more verbose output which includes,

among other information, more complete compilation, post-compilation and link

commands.

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

@node Executable File Names

@subsection Executable File Names

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

@noindent

@cindex @code{Executable}

By default, the executable name corresponding to a main file is

computed from the main source file name. Through the attribute

@b{Builder.Executable}, it is possible to change this default.

For instance, instead of building @command{proc} (or @command{proc.exe}

on Windows), we could configure our project file to build "proc1"

(resp proc1.exe) with the following addition:

@smallexample @c projectfile

   project Build is

      ...  --  same as before

      package Builder is

         for Executable ("proc.adb") use "proc1";

      end Builder

   end Build;

@end smallexample

@noindent

@cindex @code{Executable_Suffix}

Attribute @b{Executable_Suffix}, when specified, may change the suffix

of the executable files, when no attribute @code{Executable} applies:

its value replace the platform-specific executable suffix.

The default executable suffix is empty on UNIX and ".exe" on Windows.

It is also possible to change the name of the produced executable by using the

command line switch @option{-o}. When several mains are defined in the project,

it is not possible to use the @option{-o} switch and the only way to change the

names of the executable is provided by Attributes @code{Executable} and

@code{Executable_Suffix}.

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

@node Avoid Duplication With Variables

@subsection Avoid Duplication With Variables

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

@noindent

To illustrate some other project capabilities, here is a slightly more complex

project using similar sources and a main program in C:

@smallexample @c projectfile

project C_Main is

   for Languages    use ("Ada", "C");

   for Source_Dirs  use ("common");

   for Object_Dir   use  "obj";

   for Main         use ("main.c");

   package Compiler is

      C_Switches := ("-pedantic");

      for Default_Switches ("C")   use C_Switches;

      for Default_Switches ("Ada") use ("-gnaty");

      for Switches ("main.c") use C_Switches & ("-g");

   end Compiler;

end C_Main;

@end smallexample

@noindent

This project has many similarities with the previous one.

As expected, its @code{Main} attribute now refers to a C source.

The attribute @emph{Exec_Dir} is now omitted, thus the resulting

executable will be put in the directory @file{obj}.

The most noticeable difference is the use of a variable in the

@emph{Compiler} package to store settings used in several attributes.

This avoids text duplication, and eases maintenance (a single place to

modify if we want to add new switches for C files). We will revisit

the use of variables in the context of scenarios (@pxref{Scenarios in

Projects}).

In this example, we see how the file @file{main.c} can be compiled with

the switches used for all the other C files, plus @option{-g}.

In this specific situation the use of a variable could have been

replaced by a reference to the @code{Default_Switches} attribute:

@smallexample @c projectfile

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

@end smallexample

@noindent

Note the tick (@emph{'}) used to refer to attributes defined in a package.

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

@smallexample

$gprbuild -Pc_main

gcc -c -pedantic -g main.c

gcc -c -gnaty proc.adb

gcc -c -gnaty pack.adb

gcc -c -pedantic utils.c

gprbind main.bexch

...

gcc main.o -o main

@end smallexample

@noindent

The default switches for Ada sources,

the default switches for C sources (in the compilation of @file{lib.c}),

and the specific switches for @file{main.c} have all been taken into

account.

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

@node Naming Schemes

@subsection Naming Schemes

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

@noindent

Sometimes an Ada software system is ported from one compilation environment to

another (say GNAT), and the file are not named using the default GNAT

conventions. Instead of changing all the file names, which for a variety of

reasons might not be possible, you can define the relevant file naming scheme

in the @b{Naming} package of your project file.

The naming scheme has two distinct goals for the project manager: it

allows finding of source files when searching in the source

directories, and given a source file name it makes it possible to guess

the associated language, and thus the compiler to use.

Note that the use by the Ada compiler of pragmas Source_File_Name is not

supported when using project files. You must use the features described in this

paragraph. You can however specify other configuration pragmas

(@pxref{Specifying Configuration Pragmas}).

The following attributes can be defined in package @code{Naming}:

@table @asis

@item @b{Casing}:

@cindex @code{Casing}

  Its value must be one of @code{"lowercase"} (the default if

  unspecified), @code{"uppercase"} or @code{"mixedcase"}. It describes the

  casing of file names with regards to the Ada unit name. Given an Ada unit

  My_Unit, the file name will respectively be @file{my_unit.adb} (lowercase),

  @file{MY_UNIT.ADB} (uppercase) or @file{My_Unit.adb} (mixedcase).

  On Windows, file names are case insensitive, so this attribute is

  irrelevant.

@item @b{Dot_Replacement}:

@cindex @code{Dot_Replacement}

  This attribute specifies the string that should replace the "." in unit

  names. Its default value is @code{"-"} so that a unit

  @code{Parent.Child} is expected to be found in the file

  @file{parent-child.adb}. The replacement string must satisfy the following

  requirements to avoid ambiguities in the naming scheme:

  @itemize -

  @item It must not be empty

  @item It cannot start or end with an alphanumeric character

  @item It cannot be a single underscore

  @item It cannot start with an underscore followed by an alphanumeric

  @item It cannot contain a dot @code{'.'} except if the entire string

     is @code{"."}

  @end itemize

@item @b{Spec_Suffix} and @b{Specification_Suffix}:

@cindex @code{Spec_Suffix}

@cindex @code{Specification_Suffix}

  For Ada, these attributes give the suffix used in file names that contain

  specifications. For other languages, they give the extension for files

  that contain declaration (header files in C for instance). The attribute

  is indexed on the language.

  The two attributes are equivalent, but the latter is obsolescent.

  If @code{Spec_Suffix ("Ada")} is not specified, then the default is

  @code{"^.ads^.ADS^"}.

  The value must satisfy the following requirements:

  @itemize -

  @item It must not be empty

  @item It cannot start with an alphanumeric character

  @item It cannot start with an underscore followed by an alphanumeric character

  @item It must include at least one dot

  @end itemize

@item @b{Body_Suffix} and @b{Implementation_Suffix}:

@cindex @code{Body_Suffix}

@cindex @code{Implementation_Suffix}

  These attributes give the extension used for file names that contain

  code (bodies in Ada). They are indexed on the language. The second

  version is obsolescent and fully replaced by the first attribute.

  These attributes must satisfy the same requirements as @code{Spec_Suffix}.

  In addition, they must be different from any of the values in

  @code{Spec_Suffix}.

  If @code{Body_Suffix ("Ada")} is not specified, then the default is

  @code{"^.adb^.ADB^"}.

  If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the

  same string, then a file name that ends with the longest of these two

  suffixes will be a body if the longest suffix is @code{Body_Suffix ("Ada")}