diff options
| author | charlet <charlet@138bc75d-0d04-0410-961f-82ee72b054a4> | 2015-10-16 12:25:58 +0000 |
|---|---|---|
| committer | charlet <charlet@138bc75d-0d04-0410-961f-82ee72b054a4> | 2015-10-16 12:25:58 +0000 |
| commit | 4ee78e36cae7d5cd417403f298464dbf3adfc909 (patch) | |
| tree | b977087bad143c37e8583e90aa75bc7979ea8b65 | |
| parent | 849fc00e181d8fa6bddbdb6ff0fc5f3df4736b1f (diff) | |
| download | gcc-4ee78e36cae7d5cd417403f298464dbf3adfc909.tar.gz | |
2015-10-16 Arnaud Charlet <charlet@adacore.com>
* checks.adb: Fix typo.
* s-osinte-linux.ads: Add header.
* projects.texi: Removed, no longer used.
* s-multip.adb: Minor: fix header.
* sem_ch3.adb, exp_ch7.adb, g-dirope.ads, sinfo.ads, types.ads,
a-textio.adb, s-exctra.adb, ali.adb, back_end.ads, exp_intr.adb,
a-tigeli.adb, exp_ch3.adb, s-os_lib.ads: Remove further references to
.NET.
* gnatlink.adb, opt.ads, exp_aggr.adb, s-solita.adb: Minor comment
updates.
git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@228880 138bc75d-0d04-0410-961f-82ee72b054a4
| -rw-r--r-- | gcc/ada/ChangeLog | 13 | ||||
| -rw-r--r-- | gcc/ada/a-textio.adb | 4 | ||||
| -rw-r--r-- | gcc/ada/a-tigeli.adb | 4 | ||||
| -rw-r--r-- | gcc/ada/ali.adb | 2 | ||||
| -rw-r--r-- | gcc/ada/back_end.ads | 5 | ||||
| -rw-r--r-- | gcc/ada/checks.adb | 2 | ||||
| -rw-r--r-- | gcc/ada/exp_aggr.adb | 3 | ||||
| -rw-r--r-- | gcc/ada/exp_ch3.adb | 5 | ||||
| -rw-r--r-- | gcc/ada/exp_ch7.adb | 11 | ||||
| -rw-r--r-- | gcc/ada/exp_intr.adb | 3 | ||||
| -rw-r--r-- | gcc/ada/g-dirope.ads | 8 | ||||
| -rw-r--r-- | gcc/ada/gnatlink.adb | 4 | ||||
| -rw-r--r-- | gcc/ada/opt.ads | 15 | ||||
| -rw-r--r-- | gcc/ada/projects.texi | 5101 | ||||
| -rw-r--r-- | gcc/ada/s-exctra.adb | 4 | ||||
| -rw-r--r-- | gcc/ada/s-multip.adb | 4 | ||||
| -rw-r--r-- | gcc/ada/s-os_lib.ads | 3 | ||||
| -rw-r--r-- | gcc/ada/s-osinte-linux.ads | 6 | ||||
| -rw-r--r-- | gcc/ada/s-solita.adb | 5 | ||||
| -rw-r--r-- | gcc/ada/sem_ch3.adb | 3 | ||||
| -rw-r--r-- | gcc/ada/sinfo.ads | 2 | ||||
| -rw-r--r-- | gcc/ada/types.ads | 5 |
22 files changed, 49 insertions, 5163 deletions
diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog index c016f670596..e7e6001b483 100644 --- a/gcc/ada/ChangeLog +++ b/gcc/ada/ChangeLog @@ -1,3 +1,16 @@ +2015-10-16 Arnaud Charlet <charlet@adacore.com> + + * checks.adb: Fix typo. + * s-osinte-linux.ads: Add header. + * projects.texi: Removed, no longer used. + * s-multip.adb: Minor: fix header. + * sem_ch3.adb, exp_ch7.adb, g-dirope.ads, sinfo.ads, types.ads, + a-textio.adb, s-exctra.adb, ali.adb, back_end.ads, exp_intr.adb, + a-tigeli.adb, exp_ch3.adb, s-os_lib.ads: Remove further references to + .NET. + * gnatlink.adb, opt.ads, exp_aggr.adb, s-solita.adb: Minor comment + updates. + 2015-10-16 Gary Dismukes <dismukes@adacore.com> * exp_ch9.adb (Build_Simple_Entry_Call): Set_Is_Internal on diff --git a/gcc/ada/a-textio.adb b/gcc/ada/a-textio.adb index 2ebec616c6d..df5e18a7ee1 100644 --- a/gcc/ada/a-textio.adb +++ b/gcc/ada/a-textio.adb @@ -6,7 +6,7 @@ -- -- -- B o d y -- -- -- --- Copyright (C) 1992-2014, Free Software Foundation, Inc. -- +-- Copyright (C) 1992-2015, Free Software Foundation, Inc. -- -- -- -- GNAT is free software; you can redistribute it and/or modify it under -- -- terms of the GNU General Public License as published by the Free Soft- -- @@ -695,7 +695,7 @@ package body Ada.Text_IO is -- The implementation of Ada.Text_IO.Get_Line is split into a subunit so -- that different implementations can be used on different systems. In -- particular the standard implementation uses low level stuff that is - -- not appropriate for the JVM and .NET implementations. + -- not appropriate for the VMs. procedure Get_Line (Item : out String; diff --git a/gcc/ada/a-tigeli.adb b/gcc/ada/a-tigeli.adb index c23cd347869..8273b050775 100644 --- a/gcc/ada/a-tigeli.adb +++ b/gcc/ada/a-tigeli.adb @@ -6,7 +6,7 @@ -- -- -- B o d y -- -- -- --- Copyright (C) 1992-2010, Free Software Foundation, Inc. -- +-- Copyright (C) 1992-2015, Free Software Foundation, Inc. -- -- -- -- GNAT is free software; you can redistribute it and/or modify it under -- -- terms of the GNU General Public License as published by the Free Soft- -- @@ -32,7 +32,7 @@ -- The implementation of Ada.Text_IO.Get_Line is split into a subunit so that -- different implementations can be used on different systems. This is the -- standard implementation (it uses low level features not suitable for use --- in the JVM or .NET implementations). +-- on virtual machines). with System; use System; with System.Storage_Elements; use System.Storage_Elements; diff --git a/gcc/ada/ali.adb b/gcc/ada/ali.adb index 83bf2b99065..c777d39d569 100644 --- a/gcc/ada/ali.adb +++ b/gcc/ada/ali.adb @@ -385,7 +385,7 @@ package body ALI is Write_Str ("make sure you are using consistent versions " & -- Split the following line so that it can easily be transformed for - -- e.g. JVM/.NET back-ends where the compiler has a different name. + -- other back-ends where the compiler might have a different name. "of gcc/gnatbind"); diff --git a/gcc/ada/back_end.ads b/gcc/ada/back_end.ads index c58f0805f20..ee8ab456a66 100644 --- a/gcc/ada/back_end.ads +++ b/gcc/ada/back_end.ads @@ -82,8 +82,7 @@ package Back_End is -- -- This is a no-op with the gcc back-end (the object file is generated by -- the assembler afterwards), but is needed for back-ends that directly - -- generate the final object file (such as the .NET backend) so that the - -- object file's timestamp is correct when compared with the corresponding - -- ali file by gnatmake. + -- generate the final object file so that the object file's timestamp is + -- correct when compared with the corresponding ali file by gnatmake. end Back_End; diff --git a/gcc/ada/checks.adb b/gcc/ada/checks.adb index 929bdc535d9..8703bf74b47 100644 --- a/gcc/ada/checks.adb +++ b/gcc/ada/checks.adb @@ -3231,7 +3231,7 @@ package body Checks is Rewrite (R_Cno, Make_Null_Statement (Loc)); end if; - -- The range check raises Constrant_Error explicitly + -- The range check raises Constraint_Error explicitly else Install_Static_Check (R_Cno, Loc); diff --git a/gcc/ada/exp_aggr.adb b/gcc/ada/exp_aggr.adb index cbb15811075..5f4234a1078 100644 --- a/gcc/ada/exp_aggr.adb +++ b/gcc/ada/exp_aggr.adb @@ -650,7 +650,8 @@ package body Exp_Aggr is -- component associations that actually need tag adjustment, similar -- to the test in Component_Not_OK_For_Backend for record aggregates -- with tagged components, but not clear whether it's worthwhile ???; - -- in the case of the JVM, object tags are handled implicitly) + -- in the case of virtual machines (no Tagged_Type_Expansion), object + -- tags are handled implicitly). if Is_Tagged_Type (Component_Type (Typ)) and then Tagged_Type_Expansion diff --git a/gcc/ada/exp_ch3.adb b/gcc/ada/exp_ch3.adb index bddb6e402c7..edbca032d53 100644 --- a/gcc/ada/exp_ch3.adb +++ b/gcc/ada/exp_ch3.adb @@ -10420,10 +10420,7 @@ package body Exp_Ch3 is -- we don't want an abstract version created because types derived from -- the abstract type may not even have Input available (for example if -- derived from a private view of the abstract type that doesn't have - -- a visible Input), but a VM such as .NET or the Java VM can treat the - -- operation as inherited anyway, and we don't want an abstract function - -- to be (implicitly) inherited in that case because it can lead to a VM - -- exception. + -- a visible Input). -- Do not generate stream routines for type Finalization_Master because -- a master may never appear in types and therefore cannot be read or diff --git a/gcc/ada/exp_ch7.adb b/gcc/ada/exp_ch7.adb index cc5948195ab..44289952680 100644 --- a/gcc/ada/exp_ch7.adb +++ b/gcc/ada/exp_ch7.adb @@ -3318,7 +3318,7 @@ package body Exp_Ch7 is Expr : Node_Id; begin - -- Standard run-time and .NET/JVM targets use the specialized routine + -- Standard run-time use the specialized routine -- Raise_From_Controlled_Operation. if Exception_Extra_Info @@ -7656,8 +7656,8 @@ package body Exp_Ch7 is -- Procedure call or raise statement begin - -- Standard run-time, .NET/JVM targets: add choice parameter E and pass - -- it to Raise_From_Controlled_Operation so that the original exception + -- Standard run-time: add choice parameter E and pass it to + -- Raise_From_Controlled_Operation so that the original exception -- name and message can be recorded in the exception message for -- Program_Error. @@ -8083,11 +8083,10 @@ package body Exp_Ch7 is Curr_S := Current_Scope; Encl_S := Scope (Curr_S); - -- Insert all actions inluding cleanup generated while analyzing or + -- Insert all actions including cleanup generated while analyzing or -- expanding the transient context back into the tree. Manage the -- secondary stack when the object declaration appears in a library - -- level package [body]. This is not needed for .NET/JVM as those do - -- not support the secondary stack. + -- level package [body]. Insert_Actions_In_Scope_Around (N => N, diff --git a/gcc/ada/exp_intr.adb b/gcc/ada/exp_intr.adb index 282662ba2ca..606f6a59680 100644 --- a/gcc/ada/exp_intr.adb +++ b/gcc/ada/exp_intr.adb @@ -1317,8 +1317,7 @@ package body Exp_Intr is -- Generate: -- if Raised and then not Abort then - -- raise Program_Error; -- for .NET and - -- -- restricted RTS + -- raise Program_Error; -- for restricted RTS -- <or> -- Raise_From_Controlled_Operation (E); -- all other cases -- end if; diff --git a/gcc/ada/g-dirope.ads b/gcc/ada/g-dirope.ads index c3c207f2e99..1b04b94615d 100644 --- a/gcc/ada/g-dirope.ads +++ b/gcc/ada/g-dirope.ads @@ -6,7 +6,7 @@ -- -- -- S p e c -- -- -- --- Copyright (C) 1998-2014, AdaCore -- +-- Copyright (C) 1998-2015, AdaCore -- -- -- -- GNAT is free software; you can redistribute it and/or modify it under -- -- terms of the GNU General Public License as published by the Free Soft- -- @@ -248,12 +248,6 @@ private type Dir_Type_Value is new System.Address; -- Low-level address directory structure as returned by opendir in C - -- - -- Note that we used to define this type in the body of this package, - -- but this was causing troubles in the context of .NET code generation - -- (because Taft amendment types are not fully implemented and cause - -- undefined references to the class), so we moved the type declaration - -- to the spec's private part, which is no problem in any case here. type Dir_Type is access Dir_Type_Value; diff --git a/gcc/ada/gnatlink.adb b/gcc/ada/gnatlink.adb index c90397de880..e94cae9af90 100644 --- a/gcc/ada/gnatlink.adb +++ b/gcc/ada/gnatlink.adb @@ -1861,10 +1861,6 @@ begin -- Now, actually link the program - -- Skip this step for now on JVM since the Java interpreter will do - -- the actual link at run time. We might consider packing all class files - -- in a .zip file during this step. - Link_Step : declare Num_Args : Natural := (Linker_Options.Last - Linker_Options.First + 1) + diff --git a/gcc/ada/opt.ads b/gcc/ada/opt.ads index b768be4075d..992658e47f1 100644 --- a/gcc/ada/opt.ads +++ b/gcc/ada/opt.ads @@ -745,9 +745,8 @@ package Opt is GNAT_Encodings : Int; pragma Import (C, GNAT_Encodings, "gnat_encodings"); -- Constant controlling the balance between GNAT encodings and standard - -- DWARF to emit in the debug information. See jmissing.c and aamissing.c - -- for definitions for dotnet/jgnat and GNAAMP back ends. It accepts the - -- following values. + -- DWARF to emit in the debug information. See aamissing.c for definitions + -- for the GNAAMP back end. It accepts the following values. DWARF_GNAT_Encodings_All : constant Int := 0; DWARF_GNAT_Encodings_GDB : constant Int := 1; @@ -1158,14 +1157,13 @@ package Opt is Optimization_Level : Int; pragma Import (C, Optimization_Level, "optimize"); -- Constant reflecting the optimization level (0,1,2,3 for -O0,-O1,-O2,-O3) - -- See jmissing.c and aamissing.c for definitions for dotnet/jgnat and - -- GNAAMP back ends. + -- See e.g. aamissing.c for definitions for the GNAAMP back end. Optimize_Size : Int; pragma Import (C, Optimize_Size, "optimize_size"); -- Constant reflecting setting of -Os (optimize for size). Set to nonzero - -- in -Os mode and set to zero otherwise. See jmissing.c and aamissing.c - -- for definitions of "optimize_size" for dotnet/jgnat and GNAAMP backends + -- in -Os mode and set to zero otherwise. See aamissing.c for definition + -- of "optimize_size" for the GNAAMP backend. Output_File_Name_Present : Boolean := False; -- GNATBIND, GNAT, GNATMAKE @@ -1431,8 +1429,7 @@ package Opt is -- GNAT -- Set True if tagged types and interfaces should be expanded by the -- front-end. If False, the original tree is left unexpanded for tagged - -- types and dispatching calls, assuming the underlying target supports - -- it (e.g. in the JVM case). + -- types and dispatching calls, assuming the underlying target supports it. Target_Dependent_Info_Read_Name : String_Ptr := null; -- GNAT diff --git a/gcc/ada/projects.texi b/gcc/ada/projects.texi deleted file mode 100644 index 2ca6babc55f..00000000000 --- a/gcc/ada/projects.texi +++ /dev/null @@ -1,5101 +0,0 @@ -@set gprconfig GPRconfig - -@c ------ projects.texi -@c Copyright (C) 2002-2014, 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@emph{projectfile}} and -@option{-X@emph{vbl}=@emph{value}}). - -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 - all OS dependencies in a small number of implementation units. -@end itemize - -@noindent -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/ - pack.ads - pack.adb - proc.adb -@end group -@group -common/obj/ - 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:: -* Duplicate Sources in Projects:: -* Object and Exec Directory:: -* Main Subprograms:: -* Tools Options in Project Files:: -* Compiling with Project Files:: -* Executable File Names:: -* Avoid Duplication With Variables:: -* Naming Schemes:: -* Installation:: -* Distributed support:: -@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. These are 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 -The 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 the 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 paths in - the list ends with "@file{**}", 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 - the directory in which the project file resides. -@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 rooted at subdirectories ".svn". To do that, attribute - @b{Ignore_Source_Sub_Dirs} can be used. It specifies the list of simple - file names for the roots of these undesirable directory subtrees. - -@smallexample - @b{for} Source_Dirs @b{use} ("./**"); - @b{for} Ignore_Source_Sub_Dirs @b{use} (".svn"); -@end smallexample - -@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 searches 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 by default a warning is issued when a project has no sources attached -to it and this is not explicitly indicated in the project file. - -@c --------------------------------------------- -@node Duplicate Sources in Projects -@subsection Duplicate Sources in Projects -@c --------------------------------------------- - -@noindent -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 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 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 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. - -If there are two sources in different directories of the same @code{"/**"} -subtree, one way to resolve the problem is to exclude the directory of the -file that should not be used as 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 across -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 subsystems -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 the source file of a 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 builder knows enough of the -semantics of the languages to build and 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 - gprbuild -Pbuild -@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{gprbuild} 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 might want more control. This section shows 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 in 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 are not subject to command line overflows. - -Several tools participate to the creation of an executable: the compiler -produces object files from the source files; the binder (in the Ada case) -creates a "source" file that takes care, among other things, of elaboration -issues and global variable initialization; and the linker gathers everything -into a single executable that users can execute. All these tools are known to -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 the 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 switch - @option{-O2}, 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 - package Compiler is - for Default_Switches ("Ada") - use ("-O2"); - for Switches ("proc.adb") - use ("-O0"); - end Compiler; - @end smallexample - - @noindent - @code{Switches} may take a pattern as an index, such as in: - - @smallexample - package Compiler is - for Default_Switches ("Ada") - use ("-O2"); - for Switches ("pkg*") - use ("-O0"); - 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 -@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 -@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 - @b{project} Build @b{is} - ... --@i{ same as before} - @b{package} Builder @b{is} - @b{for} Executable ("proc.adb") @b{use} "proc1"; - @b{end} Builder - @b{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 replaces 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 -@b{project} C_Main @b{is} - @b{for} Languages @b{use} ("Ada", "C"); - @b{for} Source_Dirs @b{use} ("common"); - @b{for} Object_Dir @b{use} "obj"; - @b{for} Main @b{use} ("main.c"); - @b{package} Compiler @b{is} - C_Switches := ("-pedantic"); - @b{for} Default_Switches ("C") @b{use} C_Switches; - @b{for} Default_Switches ("Ada") @b{use} ("-gnaty"); - @b{for} Switches ("main.c") @b{use} C_Switches & ("-g"); - @b{end} Compiler; -@b{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 - @b{for} Switches ("c_main.c") @b{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. - -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 the value of the attribute is the empty string, it indicates to the - Project Manager that the only specifications/header files for the language - are those specified with attributes @code{Spec} or - @code{Specification_Exceptions}. - - If @code{Spec_Suffix ("Ada")} is not specified, then the default is - @code{".ads"}. - - A non empty value must satisfy the following requirements: - - @itemize - - @item It must include at least one dot - @item If @code{Dot_Replacement} is a single dot, then it cannot include - more than 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. - - For each language of a project, one of these two attributes need to be - specified, either in the project itself or in the configuration project file. - - If the value of the attribute is the empty string, it indicates to the - Project Manager that the only source files for the language - are those specified with attributes @code{Body} or - @code{Implementation_Exceptions}. - - 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"}. - - 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")} - or a spec if the longest suffix is @code{Spec_Suffix ("Ada")}. - - If the suffix does not start with a '.', a file with a name exactly equal to - the suffix will also be part of the project (for instance if you define the - suffix as @code{Makefile.in}, a file called @file{Makefile.in} will be part - of the project. This capability is usually not interesting when building. - However, it might become useful when a project is also used to - find the list of source files in an editor, like the GNAT Programming System - (GPS). - -@item @b{Separate_Suffix}: -@cindex @code{Separate_Suffix} - This attribute is specific to Ada. It denotes the suffix used in file names - that contain separate bodies. If it is not specified, then it defaults to - same value as @code{Body_Suffix ("Ada")}. - - The value of this attribute cannot be the empty string. - - Otherwise, the same rules apply as for the - @code{Body_Suffix} attribute. The only accepted index is "Ada". - -@item @b{Spec} or @b{Specification}: -@cindex @code{Spec} -@cindex @code{Specification} - This attribute @code{Spec} can be used to define the source file name for a - given Ada compilation unit's spec. The index is the literal name of the Ada - unit (case insensitive). The value is the literal base name of the file that - contains this unit's spec (case sensitive or insensitive depending on the - operating system). This attribute allows the definition of exceptions to the - general naming scheme, in case some files do not follow the usual - convention. - - When a source file contains several units, the relative position of the unit - can be indicated. The first unit in the file is at position 1 - - @smallexample @c projectfile - for Spec ("MyPack.MyChild") use "mypack.mychild.spec"; - for Spec ("top") use "foo.a" at 1; - for Spec ("foo") use "foo.a" at 2; - @end smallexample - -@item @b{Body} or @b{Implementation}: -@cindex @code{Body} -@cindex @code{Implementation} - These attribute play the same role as @emph{Spec} for Ada bodies. - -@item @b{Specification_Exceptions} and @b{Implementation_Exceptions}: -@cindex @code{Specification_Exceptions} -@cindex @code{Implementation_Exceptions} - These attributes define exceptions to the naming scheme for languages - other than Ada. They are indexed on the language name, and contain - a list of file names respectively for headers and source code. - -@end table - -@set unw -For example, the following package models the Apex file naming rules: - -@smallexample @c projectfile -@group - @b{package} Naming @b{is} - @b{for} Casing @b{use} "lowercase"; - @b{for} Dot_Replacement @b{use} "."; - @b{for} Spec_Suffix ("Ada") @b{use} ".1.ada"; - @b{for} Body_Suffix ("Ada") @b{use} ".2.ada"; - @b{end} Naming; -@end group -@end smallexample - - -@c --------------------------------------------- -@node Installation -@subsection Installation -@c --------------------------------------------- - -@noindent -After building an application or a library it is often required to -install it into the development environment. For instance this step is -required if the library is to be used by another application. -The @command{gprinstall} tool provides an easy way to install -libraries, executable or object code generated during the build. The -@b{Install} package can be used to change the default locations. - -The following attributes can be defined in package @code{Install}: - -@table @asis - -@item @b{Active} - -Whether the project is to be installed, values are @code{true} -(default) or @code{false}. - -@item @b{Artifacts} -@cindex @code{Artifacts} - -An array attribute to declare a set of files not part of the sources -to be installed. The array discriminant is the directory where the -file is to be installed. If a relative directory then Prefix (see -below) is prepended. - -@item @b{Prefix}: -@cindex @code{Prefix} - -Root directory for the installation. - -@item @b{Exec_Subdir} - -Subdirectory of @b{Prefix} where executables are to be -installed. Default is @b{bin}. - -@item @b{Lib_Subdir} - -Subdirectory of @b{Prefix} where directory with the library or object -files is to be installed. Default is @b{lib}. - -@item @b{Sources_Subdir} - -Subdirectory of @b{Prefix} where directory with sources is to be -installed. Default is @b{include}. - -@item @b{Project_Subdir} - -Subdirectory of @b{Prefix} where the generated project file is to be -installed. Default is @b{share/gpr}. - -@item @b{Mode} - -The installation mode, it is either @b{dev} (default) or @b{usage}. -See @b{gprbuild} user's guide for details. - -@item @b{Install_Name} - -Specify the name to use for recording the installation. The default is -the project name without the extension. -@end table - -@c --------------------------------------------- -@node Distributed support -@subsection Distributed support -@c --------------------------------------------- - -@noindent -For large projects the compilation time can become a limitation in -the development cycle. To cope with that, GPRbuild supports -distributed compilation. - -The following attributes can be defined in package @code{Remote}: - -@table @asis - -@item @b{Root_Dir}: -@cindex @code{Root_Dir} - -Root directory of the project's sources. The default value is the -project's directory. - -@end table - -@c --------------------------------------------- -@node Organizing Projects into Subsystems -@section Organizing Projects into Subsystems -@c --------------------------------------------- - -@noindent -A @b{subsystem} is a coherent part of the complete system to be built. It is -represented by a set of sources and one single object directory. A system can -be composed of a single subsystem when it is simple as we have seen in the -first section. Complex systems are usually composed of several interdependent -subsystems. A subsystem is dependent on another subsystem if knowledge of the -other one is required to build it, and in particular if visibility on some of -the sources of this other subsystem is required. Each subsystem is usually -represented by its own project file. - -In this section, the previous example is being extended. Let's assume some -sources of our @code{Build} project depend on other sources. -For instance, when building a graphical interface, it is usual to depend upon -a graphical library toolkit such as GtkAda. Furthermore, we also need -sources from a logging module we had previously written. - -@menu -* Project Dependencies:: -* Cyclic Project Dependencies:: -* Sharing Between Projects:: -* Global Attributes:: -@end menu - -@c --------------------------------------------- -@node Project Dependencies -@subsection Project Dependencies -@c --------------------------------------------- - -@noindent -GtkAda comes with its own project file (appropriately called -@file{gtkada.gpr}), and we will assume we have already built a project -called @file{logging.gpr} for the logging module. With the information provided -so far in @file{build.gpr}, building the application would fail with an error -indicating that the gtkada and logging units that are relied upon by the sources -of this project cannot be found. - -This is solved by adding the following @b{with} clauses at the beginning of our -project: - -@smallexample @c projectfile - @b{with} "gtkada.gpr"; - @b{with} "a/b/logging.gpr"; - @b{project} Build @b{is} - ... --@i{ as before} - @b{end} Build; -@end smallexample - -@noindent -@cindex @code{Externally_Built} -When such a project is compiled, @command{gprbuild} will automatically check -the other projects and recompile their sources when needed. It will also -recompile the sources from @code{Build} when needed, and finally create the -executable. In some cases, the implementation units needed to recompile a -project are not available, or come from some third party and you do not want to -recompile it yourself. In this case, set the attribute @b{Externally_Built} to -"true", indicating to the builder that this project can be assumed to be -up-to-date, and should not be considered for recompilation. In Ada, if the -sources of this externally built project were compiled with another version of -the compiler or with incompatible options, the binder will issue an error. - -The project's @code{with} clause has several effects. It provides source -visibility between projects during the compilation process. It also guarantees -that the necessary object files from @code{Logging} and @code{GtkAda} are -available when linking @code{Build}. - -As can be seen in this example, the syntax for importing projects is similar -to the syntax for importing compilation units in Ada. However, project files -use literal strings instead of names, and the @code{with} clause identifies -project files rather than packages. - -Each literal string after @code{with} is the path -(absolute or relative) to a project file. The @code{.gpr} extension is -optional, although we recommend adding it. If no extension is specified, -and no project file with the @file{.gpr} extension is found, then -the file is searched for exactly as written in the @code{with} clause, -that is with no extension. - -As mentioned above, the path after a @code{with} has to be a literal -string, and you cannot use concatenation, or lookup the value of external -variables to change the directories from which a project is loaded. -A solution if you need something like this is to use aggregate projects -(@pxref{Aggregate Projects}). - -@cindex project path -When a relative path or a base name is used, the -project files are searched relative to each of the directories in the -@b{project path}. This path includes all the directories found with the -following algorithm, in this order; the first matching file is used: - -@itemize @bullet -@item First, the file is searched relative to the directory that contains the - current project file. - -@item -@cindex @code{GPR_PROJECT_PATH_FILE} -@cindex @code{GPR_PROJECT_PATH} -@cindex @code{ADA_PROJECT_PATH} - Then it is searched relative to all the directories specified in the - environment variables @b{GPR_PROJECT_PATH_FILE}, - @b{GPR_PROJECT_PATH} and @b{ADA_PROJECT_PATH} (in that order) if they exist. - The value of @b{GPR_PROJECT_PATH_FILE}, when defined, is the path name of - a text file that contains project directory path names, one per line. - @b{GPR_PROJECT_PATH} and @b{ADA_PROJECT_PATH}, when defined, contain - project directory path names separated by directory separators. - @b{ADA_PROJECT_PATH} is used for compatibility, it is recommended to - use @b{GPR_PROJECT_PATH_FILE} or @b{GPR_PROJECT_PATH}. - -@item Finally, it is searched relative to the default project directories. - Such directories depend on the tool used. The locations searched in the - specified order are: - - @itemize @bullet - @item @file{<prefix>/<target>/lib/gnat} - (for @command{gnatmake} in all cases, and for @command{gprbuild} if option - @option{--target} is specified) - @item @file{<prefix>/<target>/share/gpr} - (for @command{gnatmake} in all cases, and for @command{gprbuild} if option - @option{--target} is specified) - @item @file{<prefix>/share/gpr/} - (for @command{gnatmake} and @command{gprbuild}) - @item @file{<prefix>/lib/gnat/} - (for @command{gnatmake} and @command{gprbuild}) - @end itemize - - In our example, @file{gtkada.gpr} is found in the predefined directory if - it was installed at the same root as GNAT. -@end itemize - -@noindent -Some tools also support extending the project path from the command line, -generally through the @option{-aP}. You can see the value of the project -path by using the @command{gnatls -v} command. - -Any symbolic link will be fully resolved in the directory of the -importing project file before the imported project file is examined. - -Any source file in the imported project can be used by the sources of the -importing project, transitively. -Thus if @code{A} imports @code{B}, which imports @code{C}, the sources of -@code{A} may depend on the sources of @code{C}, even if @code{A} does not -import @code{C} explicitly. However, this is not recommended, because if -and when @code{B} ceases to import @code{C}, some sources in @code{A} will -no longer compile. @command{gprbuild} has a switch @option{--no-indirect-imports} -that will report such indirect dependencies. - -One very important aspect of a project hierarchy is that -@b{a given source can only belong to one project} (otherwise the project manager -would not know which settings apply to it and when to recompile it). It means -that different project files do not usually share source directories or -when they do, they need to specify precisely which project owns which sources -using attribute @code{Source_Files} or equivalent. By contrast, 2 projects -can each own a source with the same base file name as long as they live in -different directories. The latter is not true for Ada Sources because of the -correlation between source files and Ada units. - -@c --------------------------------------------- -@node Cyclic Project Dependencies -@subsection Cyclic Project Dependencies -@c --------------------------------------------- - -@noindent -Cyclic dependencies are mostly forbidden: -if @code{A} imports @code{B} (directly or indirectly) then @code{B} -is not allowed to import @code{A}. However, there are cases when cyclic -dependencies would be beneficial. For these cases, another form of import -between projects exists: the @b{limited with}. A project @code{A} that -imports a project @code{B} with a straight @code{with} may also be imported, -directly or indirectly, by @code{B} through a @code{limited with}. - -The difference between straight @code{with} and @code{limited with} is that -the name of a project imported with a @code{limited with} cannot be used in the -project importing it. In particular, its packages cannot be renamed and -its variables cannot be referred to. - -@smallexample @c 0projectfile -with "b.gpr"; -with "c.gpr"; -project A is - For Exec_Dir use B'Exec_Dir; -- ok -end A; - -limited with "a.gpr"; -- Cyclic dependency: A -> B -> A -project B is - For Exec_Dir use A'Exec_Dir; -- not ok -end B; - -with "d.gpr"; -project C is -end C; - -limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A -project D is - For Exec_Dir use A'Exec_Dir; -- not ok -end D; -@end smallexample - -@c --------------------------------------------- -@node Sharing Between Projects -@subsection Sharing Between Projects -@c --------------------------------------------- - -@noindent -When building an application, it is common to have similar needs in several of -the projects corresponding to the subsystems under construction. For instance, -they will all have the same compilation switches. - -As seen before (@pxref{Tools Options in Project Files}), setting compilation -switches for all sources of a subsystem is simple: it is just a matter of -adding a @code{Compiler.Default_Switches} attribute to each project files with -the same value. Of course, that means duplication of data, and both places need -to be changed in order to recompile the whole application with different -switches. It can become a real problem if there are many subsystems and thus -many project files to edit. - -There are two main approaches to avoiding this duplication: - -@itemize @bullet -@item Since @file{build.gpr} imports @file{logging.gpr}, we could change it - to reference the attribute in Logging, either through a package renaming, - or by referencing the attribute. The following example shows both cases: - - @smallexample @c projectfile - project Logging is - package Compiler is - for Switches ("Ada") - use ("-O2"); - end Compiler; - package Binder is - for Switches ("Ada") - use ("-E"); - end Binder; - end Logging; - - with "logging.gpr"; - project Build is - package Compiler renames Logging.Compiler; - package Binder is - for Switches ("Ada") use Logging.Binder'Switches ("Ada"); - end Binder; - end Build; - @end smallexample - - @noindent - The solution used for @code{Compiler} gets the same value for all - attributes of the package, but you cannot modify anything from the - package (adding extra switches or some exceptions). The second - version is more flexible, but more verbose. - - If you need to refer to the value of a variable in an imported - project, rather than an attribute, the syntax is similar but uses - a "." rather than an apostrophe. For instance: - - @smallexample @c projectfile - with "imported"; - project Main is - Var1 := Imported.Var; - end Main; - @end smallexample - -@item The second approach is to define the switches in a third project. - That project is set up without any sources (so that, as opposed to - the first example, none of the project plays a special role), and - will only be used to define the attributes. Such a project is - typically called @file{shared.gpr}. - - @smallexample @c projectfile - abstract project Shared is - for Source_Files use (); -- no sources - package Compiler is - for Switches ("Ada") - use ("-O2"); - end Compiler; - end Shared; - - with "shared.gpr"; - project Logging is - package Compiler renames Shared.Compiler; - end Logging; - - with "shared.gpr"; - project Build is - package Compiler renames Shared.Compiler; - end Build; - @end smallexample - - @noindent - As for the first example, we could have chosen to set the attributes - one by one rather than to rename a package. The reason we explicitly - indicate that @code{Shared} has no sources is so that it can be created - in any directory and we are sure it shares no sources with @code{Build} - or @code{Logging}, which of course would be invalid. - -@cindex project qualifier - Note the additional use of the @b{abstract} qualifier in @file{shared.gpr}. - This qualifier is optional, but helps convey the message that we do not - intend this project to have sources (@pxref{Qualified Projects} for - more qualifiers). -@end itemize - -@c --------------------------------------------- -@node Global Attributes -@subsection Global Attributes -@c --------------------------------------------- - -@noindent -We have already seen many examples of attributes used to specify a special -option of one of the tools involved in the build process. Most of those -attributes are project specific. That it to say, they only affect the invocation -of tools on the sources of the project where they are defined. - -There are a few additional attributes that apply to all projects in a -hierarchy as long as they are defined on the "main" project. -The main project is the project explicitly mentioned on the command-line. -The project hierarchy is the "with"-closure of the main project. - -Here is a list of commonly used global attributes: - -@table @asis -@item @b{Builder.Global_Configuration_Pragmas}: -@cindex @code{Global_Configuration_Pragmas} - This attribute points to a file that contains configuration pragmas - to use when building executables. These pragmas apply for all - executables built from this project hierarchy. As we have seen before, - additional pragmas can be specified on a per-project basis by setting the - @code{Compiler.Local_Configuration_Pragmas} attribute. - -@item @b{Builder.Global_Compilation_Switches}: -@cindex @code{Global_Compilation_Switches} - This attribute is a list of compiler switches to use when compiling any - source file in the project hierarchy. These switches are used in addition - to the ones defined in the @code{Compiler} package, which only apply to - the sources of the corresponding project. This attribute is indexed on - the name of the language. - -@end table - -Using such global capabilities is convenient. It can also lead to unexpected -behavior. Especially when several subsystems are shared among different main -projects and the different global attributes are not -compatible. Note that using aggregate projects can be a safer and more powerful -replacement to global attributes. - -@c --------------------------------------------- -@node Scenarios in Projects -@section Scenarios in Projects -@c --------------------------------------------- - -@noindent -Various aspects of the projects can be modified based on @b{scenarios}. These -are user-defined modes that change the behavior of a project. Typical -examples are the setup of platform-specific compiler options, or the use of -a debug and a release mode (the former would activate the generation of debug -information, while the second will focus on improving code optimization). - -Let's enhance our example to support debug and release modes. The issue is to -let the user choose what kind of system he is building: use @option{-g} as -compiler switches in debug mode and @option{-O2} in release mode. We will also -set up the projects so that we do not share the same object directory in both -modes; otherwise switching from one to the other might trigger more -recompilations than needed or mix objects from the two modes. - -One naive approach is to create two different project files, say -@file{build_debug.gpr} and @file{build_release.gpr}, that set the appropriate -attributes as explained in previous sections. This solution does not scale -well, because in the presence of multiple projects depending on each other, you -will also have to duplicate the complete hierarchy and adapt the project files -to point to the right copies. - -@cindex scenarios -Instead, project files support the notion of scenarios controlled -by external values. Such values can come from several sources (in decreasing -order of priority): - -@table @asis -@item @b{Command line}: -@cindex @option{-X} - When launching @command{gnatmake} or @command{gprbuild}, the user can pass - extra @option{-X} switches to define the external value. In - our case, the command line might look like - - @smallexample - gnatmake -Pbuild.gpr -Xmode=debug - or gnatmake -Pbuild.gpr -Xmode=release - @end smallexample - -@item @b{Environment variables}: - When the external value does not come from the command line, it can come from - the value of environment variables of the appropriate name. - In our case, if an environment variable called "mode" - exists, its value will be taken into account. - -@item @b{External function second parameter}. - -@end table - -@cindex @code{external} -We now need to get that value in the project. The general form is to use -the predefined function @b{external} which returns the current value of -the external. For instance, we could set up the object directory to point to -either @file{obj/debug} or @file{obj/release} by changing our project to - -@smallexample @c projectfile - @b{project} Build @b{is} - @b{for} Object_Dir @b{use} "obj/" & @b{external} ("mode", "debug"); - ... --@i{ as before} - @b{end} Build; -@end smallexample - -@noindent -The second parameter to @code{external} is optional, and is the default -value to use if "mode" is not set from the command line or the environment. - -In order to set the switches according to the different scenarios, other -constructs have to be introduced such as typed variables and case constructions. - -@cindex typed variable -@cindex case construction -A @b{typed variable} is a variable that -can take only a limited number of values, similar to an enumeration in Ada. -Such a variable can then be used in a @b{case construction} and create conditional -sections in the project. The following example shows how this can be done: - -@smallexample @c projectfile - @b{project} Build @b{is} - @b{type} Mode_Type @b{is} ("debug", "release"); --@i{ all possible values} - Mode : Mode_Type := @b{external} ("mode", "debug"); --@i{ a typed variable} - - @b{package} Compiler @b{is} - @b{case} Mode @b{is} - @b{when} "debug" => - @b{for} Switches ("Ada") - @b{use} ("-g"); - @b{when} "release" => - @b{for} Switches ("Ada") - @b{use} ("-O2"); - @b{end} @b{case}; - @b{end} Compiler; - @b{end} Build; -@end smallexample - -@noindent -The project has suddenly grown in size, but has become much more flexible. -@code{Mode_Type} defines the only valid values for the @code{mode} variable. If -any other value is read from the environment, an error is reported and the -project is considered as invalid. - -The @code{Mode} variable is initialized with an external value -defaulting to @code{"debug"}. This default could be omitted and that would -force the user to define the value. Finally, we can use a case construction to set the -switches depending on the scenario the user has chosen. - -Most aspects of the projects can depend on scenarios. The notable exception -are project dependencies (@code{with} clauses), which cannot depend on a scenario. - -Scenarios work the same way with @b{project hierarchies}: you can either -duplicate a variable similar to @code{Mode} in each of the project (as long -as the first argument to @code{external} is always the same and the type is -the same), or simply set the variable in the @file{shared.gpr} project -(@pxref{Sharing Between Projects}). - -@c --------------------------------------------- -@node Library Projects -@section Library Projects -@c --------------------------------------------- - -@noindent -So far, we have seen examples of projects that create executables. However, -it is also possible to create libraries instead. A @b{library} is a specific -type of subsystem where, for convenience, objects are grouped together -using system-specific means such as archives or windows DLLs. - -Library projects provide a system- and language-independent way of building both @b{static} -and @b{dynamic} libraries. They also support the concept of @b{standalone -libraries} (SAL) which offer two significant properties: the elaboration -(e.g. initialization) of the library is either automatic or very simple; -a change in the -implementation part of the library implies minimal post-compilation actions on -the complete system and potentially no action at all for the rest of the -system in the case of dynamic SALs. - -There is a restriction on shared library projects: by default, they are only -allowed to import other shared library projects. They are not allowed to -import non library projects or static library projects. - -The GNAT Project Manager takes complete care of the library build, rebuild and -installation tasks, including recompilation of the source files for which -objects do not exist or are not up to date, assembly of the library archive, and -installation of the library (i.e., copying associated source, object and -@file{ALI} files to the specified location). - -@menu -* Building Libraries:: -* Using Library Projects:: -* Stand-alone Library Projects:: -* Installing a library with project files:: -@end menu - -@c --------------------------------------------- -@node Building Libraries -@subsection Building Libraries -@c --------------------------------------------- - -@noindent -Let's enhance our example and transform the @code{logging} subsystem into a -library. In order to do so, a few changes need to be made to -@file{logging.gpr}. Some attributes need to be defined: at least -@code{Library_Name} and @code{Library_Dir}; in addition, some other attributes -can be used to specify specific aspects of the library. For readability, it is -also recommended (although not mandatory), to use the qualifier @code{library} -in front of the @code{project} keyword. - -@table @asis -@item @b{Library_Name}: -@cindex @code{Library_Name} - This attribute is the name of the library to be built. There is no - restriction on the name of a library imposed by the project manager, except - for stand-alone libraries whose names must follow the syntax of Ada - identifiers; however, there may be system-specific restrictions on the name. - In general, it is recommended to stick to alphanumeric characters (and - possibly single underscores) to help portability. - -@item @b{Library_Dir}: -@cindex @code{Library_Dir} - This attribute is the path (absolute or relative) of the directory where - the library is to be installed. In the process of building a library, - the sources are compiled, the object files end up in the explicit or - implicit @code{Object_Dir} directory. When all sources of a library - are compiled, some of the compilation artifacts, including the library itself, - are copied to the library_dir directory. This directory must exist and be - writable. It must also be different from the object directory so that cleanup - activities in the Library_Dir do not affect recompilation needs. - -@end table - -Here is the new version of @file{logging.gpr} that makes it a library: - -@smallexample @c projectfile -library @b{project} Logging @b{is} --@i{ "library" is optional} - @b{for} Library_Name @b{use} "logging"; --@i{ will create "liblogging.a" on Unix} - @b{for} Object_Dir @b{use} "obj"; - @b{for} Library_Dir @b{use} "lib"; --@i{ different from object_dir} -@b{end} Logging; -@end smallexample - -@noindent -Once the above two attributes are defined, the library project is valid and -is enough for building a library with default characteristics. -Other library-related attributes can be used to change the defaults: - -@table @asis -@item @b{Library_Kind}: -@cindex @code{Library_Kind} - The value of this attribute must be either @code{"static"}, @code{"dynamic"} or - @code{"relocatable"} (the latter is a synonym for dynamic). It indicates - which kind of library should be built (the default is to build a - static library, that is an archive of object files that can potentially - be linked into a static executable). When the library is set to be dynamic, - a separate image is created that will be loaded independently, usually - at the start of the main program execution. Support for dynamic libraries is - very platform specific, for instance on Windows it takes the form of a DLL - while on GNU/Linux, it is a dynamic elf image whose suffix is usually - @file{.so}. Library project files, on the other hand, can be written in - a platform independent way so that the same project file can be used to build - a library on different operating systems. - - If you need to build both a static and a dynamic library, it is recommended - to use two different object directories, since in some cases some extra code - needs to be generated for the latter. For such cases, one can either define - two different project files, or a single one that uses scenarios to indicate - the various kinds of library to be built and their corresponding object_dir. - -@cindex @code{Library_ALI_Dir} -@item @b{Library_ALI_Dir}: - This attribute may be specified to indicate the directory where the ALI - files of the library are installed. By default, they are copied into the - @code{Library_Dir} directory, but as for the executables where we have a - separate @code{Exec_Dir} attribute, you might want to put them in a separate - directory since there can be hundreds of them. The same restrictions as for - the @code{Library_Dir} attribute apply. - -@cindex @code{Library_Version} -@item @b{Library_Version}: - This attribute is platform dependent, and has no effect on Windows. - On Unix, it is used only for dynamic libraries as the internal - name of the library (the @code{"soname"}). If the library file name (built - from the @code{Library_Name}) is different from the @code{Library_Version}, - then the library file will be a symbolic link to the actual file whose name - will be @code{Library_Version}. This follows the usual installation schemes - for dynamic libraries on many Unix systems. - -@smallexample @c projectfile -@group - @b{project} Logging @b{is} - Version := "1"; - @b{for} Library_Dir @b{use} "lib"; - @b{for} Library_Name @b{use} "logging"; - @b{for} Library_Kind @b{use} "dynamic"; - @b{for} Library_Version @b{use} "liblogging.so." & Version; - @b{end} Logging; -@end group -@end smallexample - - @noindent - After the compilation, the directory @file{lib} will contain both a - @file{libdummy.so.1} library and a symbolic link to it called - @file{libdummy.so}. - -@cindex @code{Library_GCC} -@item @b{Library_GCC}: - This attribute is the name of the tool to use instead of "gcc" to link shared - libraries. A common use of this attribute is to define a wrapper script that - accomplishes specific actions before calling gcc (which itself calls the - linker to build the library image). - -@item @b{Library_Options}: -@cindex @code{Library_Options} - This attribute may be used to specify additional switches (last switches) - when linking a shared library. - - It may also be used to add foreign object files to a static library. - Each string in Library_Options is an absolute or relative path of an object - file. When a relative path, it is relative to the object directory. - -@item @b{Leading_Library_Options}: -@cindex @code{Leading_Library_Options} - This attribute, that is taken into account only by @command{gprbuild}, may be - used to specified leading options (first switches) when linking a shared - library. - -@cindex @code{Linker_Options} -@item @b{Linker.Linker_Options}: - This attribute specifies additional switches to be given to the linker when - linking an executable. It is ignored when defined in the main project and - taken into account in all other projects that are imported directly or - indirectly. These switches complement the @code{Linker.Switches} - defined in the main project. This is useful when a particular subsystem - depends on an external library: adding this dependency as a - @code{Linker_Options} in the project of the subsystem is more convenient than - adding it to all the @code{Linker.Switches} of the main projects that depend - upon this subsystem. -@end table - -@c --------------------------------------------- -@node Using Library Projects -@subsection Using Library Projects -@c --------------------------------------------- - -@noindent -When the builder detects that a project file is a library project file, it -recompiles all sources of the project that need recompilation and rebuild the -library if any of the sources have been recompiled. It then groups all object -files into a single file, which is a shared or a static library. This library -can later on be linked with multiple executables. Note that the use -of shard libraries reduces the size of the final executable and can also reduce -the memory footprint at execution time when the library is shared among several -executables. - -It is also possible to build @b{multi-language libraries}. When using -@command{gprbuild} as a builder, multi-language library projects allow naturally -the creation of multi-language libraries . @command{gnatmake}, does not try to -compile non Ada sources. However, when the project is multi-language, it will -automatically link all object files found in the object directory, whether or -not they were compiled from an Ada source file. This specific behavior does not -apply to Ada-only projects which only take into account the objects -corresponding to the sources of the project. - -A non-library project can import a library project. When the builder is invoked -on the former, the library of the latter is only rebuilt when absolutely -necessary. For instance, if a unit of the library is not up-to-date but none of -the executables need this unit, then the unit is not recompiled and the library -is not reassembled. For instance, let's assume in our example that logging has -the following sources: @file{log1.ads}, @file{log1.adb}, @file{log2.ads} and -@file{log2.adb}. If @file{log1.adb} has been modified, then the library -@file{liblogging} will be rebuilt when compiling all the sources of -@code{Build} only if @file{proc.ads}, @file{pack.ads} or @file{pack.adb} -include a @code{"with Log1"}. - -To ensure that all the sources in the @code{Logging} library are -up to date, and that all the sources of @code{Build} are also up to date, -the following two commands need to be used: - -@smallexample -gnatmake -Plogging.gpr -gnatmake -Pbuild.gpr -@end smallexample - -@noindent -All @file{ALI} files will also be copied from the object directory to the -library directory. To build executables, @command{gnatmake} will use the -library rather than the individual object files. - -Library projects can also be useful to describe a library that needs to be used -but, for some reason, cannot be rebuilt. For instance, it is the case when some -of the library sources are not available. Such library projects need to use the -@code{Externally_Built} attribute as in the example below: - -@smallexample @c projectfile -library @b{project} Extern_Lib @b{is} - @b{for} Languages @b{use} ("Ada", "C"); - @b{for} Source_Dirs @b{use} ("lib_src"); - @b{for} Library_Dir @b{use} "lib2"; - @b{for} Library_Kind @b{use} "dynamic"; - @b{for} Library_Name @b{use} "l2"; - @b{for} Externally_Built @b{use} "true"; --@i{ <<<<} -@b{end} Extern_Lib; -@end smallexample - -@noindent -In the case of externally built libraries, the @code{Object_Dir} -attribute does not need to be specified because it will never be -used. - -The main effect of using such an externally built library project is mostly to -affect the linker command in order to reference the desired library. It can -also be achieved by using @code{Linker.Linker_Options} or @code{Linker.Switches} -in the project corresponding to the subsystem needing this external library. -This latter method is more straightforward in simple cases but when several -subsystems depend upon the same external library, finding the proper place -for the @code{Linker.Linker_Options} might not be easy and if it is -not placed properly, the final link command is likely to present ordering issues. -In such a situation, it is better to use the externally built library project -so that all other subsystems depending on it can declare this dependency thanks -to a project @code{with} clause, which in turn will trigger the builder to find -the proper order of libraries in the final link command. - -@c --------------------------------------------- -@node Stand-alone Library Projects -@subsection Stand-alone Library Projects -@c --------------------------------------------- - -@noindent -@cindex standalone libraries -A @b{stand-alone library} is a library that contains the necessary code to -elaborate the Ada units that are included in the library. A stand-alone -library is a convenient way to add an Ada subsystem to a more global system -whose main is not in Ada since it makes the elaboration of the Ada part mostly -transparent. However, stand-alone libraries are also useful when the main is in -Ada: they provide a means for minimizing relinking & redeployment of complex -systems when localized changes are made. - -The name of a stand-alone library, specified with attribute -@code{Library_Name}, must have the syntax of an Ada identifier. - -The most prominent characteristic of a stand-alone library is that it offers a -distinction between interface units and implementation units. Only the former -are visible to units outside the library. A stand-alone library project is thus -characterised by a third attribute, usually @b{Library_Interface}, in addition -to the two attributes that make a project a Library Project -(@code{Library_Name} and @code{Library_Dir}). This third attribute may also be -@b{Interfaces}. @b{Library_Interface} only works when the interface is in Ada -and takes a list of units as parameter. @b{Interfaces} works for any supported -language and takes a list of sources as parameter. - -@table @asis -@item @b{Library_Interface}: -@cindex @code{Library_Interface} - This attribute defines an explicit subset of the units of the project. Units - from projects importing this library project may only "with" units whose - sources are listed in the @code{Library_Interface}. Other sources are - considered implementation units. - -@smallexample @c projectfile -@group - @b{for} Library_Dir @b{use} "lib"; - @b{for} Library_Name @b{use} "logging"; - @b{for} Library_Interface @b{use} ("lib1", "lib2"); --@i{ unit names} -@end group -@end smallexample - -@item @b{Interfaces} - This attribute defines an explicit subset of the source files of a project. - Sources from projects importing this project, can only depend on sources from - this subset. This attribute can be used on non library projects. It can also - be used as a replacement for attribute @code{Library_Interface}, in which - case, units have to be replaced by source files. For multi-language library - projects, it is the only way to make the project a Stand-Alone Library project - whose interface is not purely Ada. - -@item @b{Library_Standalone}: -@cindex @code{Library_Standalone} - This attribute defines the kind of standalone library to - build. Values are either @code{standard} (the default), @code{no} or - @code{encapsulated}. When @code{standard} is used the code to elaborate and - finalize the library is embedded, when @code{encapsulated} is used the - library can furthermore depend only on static libraries (including - the GNAT runtime). This attribute can be set to @code{no} to make it clear - that the library should not be standalone in which case the - @code{Library_Interface} should not defined. Note that this attribute - only applies to shared libraries, so @code{Library_Kind} must be set - to @code{dynamic}. - -@smallexample @c projectfile -@group - @b{for} Library_Dir @b{use} "lib"; - @b{for} Library_Name @b{use} "logging"; - @b{for} Library_Kind @b{use} "dynamic"; - @b{for} Library_Interface @b{use} ("lib1", "lib2"); --@i{ unit names} - @b{for} Library_Standalone @b{use} "encapsulated"; -@end group -@end smallexample - -@end table - -In order to include the elaboration code in the stand-alone library, the binder -is invoked on the closure of the library units creating a package whose name -depends on the library name (b~logging.ads/b in the example). -This binder-generated package includes @b{initialization} and @b{finalization} -procedures whose names depend on the library name (@code{logginginit} and -@code{loggingfinal} in the example). The object corresponding to this package is -included in the library. - -@table @asis -@item @b{Library_Auto_Init}: -@cindex @code{Library_Auto_Init} - A dynamic stand-alone Library is automatically initialized - if automatic initialization of Stand-alone Libraries is supported on the - platform and if attribute @b{Library_Auto_Init} is not specified or - is specified with the value "true". A static Stand-alone Library is never - automatically initialized. Specifying "false" for this attribute - prevents automatic initialization. - - When a non-automatically initialized stand-alone library is used in an - executable, its initialization procedure must be called before any service of - the library is used. When the main subprogram is in Ada, it may mean that the - initialization procedure has to be called during elaboration of another - package. - -@item @b{Library_Dir}: -@cindex @code{Library_Dir} - For a stand-alone library, only the @file{ALI} files of the interface units - (those that are listed in attribute @code{Library_Interface}) are copied to - the library directory. As a consequence, only the interface units may be - imported from Ada units outside of the library. If other units are imported, - the binding phase will fail. - -@item @b{Binder.Default_Switches}: - When a stand-alone library is bound, the switches that are specified in - the attribute @b{Binder.Default_Switches ("Ada")} are - used in the call to @command{gnatbind}. - -@item @b{Library_Src_Dir}: -@cindex @code{Library_Src_Dir} - This attribute defines the location (absolute or relative to the project - directory) where the sources of the interface units are copied at - installation time. - These sources includes the specs of the interface units along with the - closure of sources necessary to compile them successfully. That may include - bodies and subunits, when pragmas @code{Inline} are used, or when there are - generic units in specs. This directory cannot point to the object directory - or one of the source directories, but it can point to the library directory, - which is the default value for this attribute. - -@item @b{Library_Symbol_Policy}: -@cindex @code{Library_Symbol_Policy} - This attribute controls the export of symbols and, on some platforms (like - VMS) that have the notions of major and minor IDs built in the library - files, it controls the setting of these IDs. It is not supported on all - platforms (where it will just have no effect). It may have one of the - following values: - - @itemize - - @item @code{"autonomous"} or @code{"default"}: exported symbols are not controlled - @item @code{"compliant"}: if attribute @b{Library_Reference_Symbol_File} - is not defined, then it is equivalent to policy "autonomous". If there - are exported symbols in the reference symbol file that are not in the - object files of the interfaces, the major ID of the library is increased. - If there are symbols in the object files of the interfaces that are not - in the reference symbol file, these symbols are put at the end of the list - in the newly created symbol file and the minor ID is increased. - @item @code{"controlled"}: the attribute @b{Library_Reference_Symbol_File} must be - defined. The library will fail to build if the exported symbols in the - object files of the interfaces do not match exactly the symbol in the - symbol file. - @item @code{"restricted"}: The attribute @b{Library_Symbol_File} must be defined. - The library will fail to build if there are symbols in the symbol file that - are not in the exported symbols of the object files of the interfaces. - Additional symbols in the object files are not added to the symbol file. - @item @code{"direct"}: The attribute @b{Library_Symbol_File} must be defined and - must designate an existing file in the object directory. This symbol file - is passed directly to the underlying linker without any symbol processing. - - @end itemize - -@item @b{Library_Reference_Symbol_File} -@cindex @code{Library_Reference_Symbol_File} - This attribute may define the path name of a reference symbol file that is - read when the symbol policy is either "compliant" or "controlled", on - platforms that support symbol control, such as VMS, when building a - stand-alone library. The path may be an absolute path or a path relative - to the project directory. - -@item @b{Library_Symbol_File} -@cindex @code{Library_Symbol_File} - This attribute may define the name of the symbol file to be created when - building a stand-alone library when the symbol policy is either "compliant", - "controlled" or "restricted", on platforms that support symbol control, - such as VMS. When symbol policy is "direct", then a file with this name - must exist in the object directory. -@end table - -@c --------------------------------------------- -@node Installing a library with project files -@subsection Installing a library with project files -@c --------------------------------------------- - -@noindent -When using project files, a usable version of the library is created in the -directory specified by the @code{Library_Dir} attribute of the library -project file. Thus no further action is needed in order to make use of -the libraries that are built as part of the general application build. - -You may want to install a library in a context different from where the library -is built. This situation arises with third party suppliers, who may want -to distribute a library in binary form where the user is not expected to be -able to recompile the library. The simplest option in this case is to provide -a project file slightly different from the one used to build the library, by -using the @code{externally_built} attribute. @ref{Using Library Projects} - -Another option is to use @command{gprinstall} to install the library in a -different context than the build location. @command{gprinstall} automatically -generates a project to use this library, and also copies the minimum set of -sources needed to use the library to the install location. -@ref{Installation} - -@c --------------------------------------------- -@node Project Extension -@section Project Extension -@c --------------------------------------------- - -@noindent -During development of a large system, it is sometimes necessary to use -modified versions of some of the source files, without changing the original -sources. This can be achieved through the @b{project extension} facility. - -Suppose for instance that our example @code{Build} project is built every night -for the whole team, in some shared directory. A developer usually needs to work -on a small part of the system, and might not want to have a copy of all the -sources and all the object files (mostly because that would require too much -disk space, time to recompile everything). He prefers to be able to override -some of the source files in his directory, while taking advantage of all the -object files generated at night. - -Another example can be taken from large software systems, where it is common to have -multiple implementations of a common interface; in Ada terms, multiple -versions of a package body for the same spec. For example, one implementation -might be safe for use in tasking programs, while another might be used only -in sequential applications. This can be modeled in GNAT using the concept -of @emph{project extension}. If one project (the ``child'') @emph{extends} -another project (the ``parent'') then by default all source files of the -parent project are inherited by the child, but the child project can -override any of the parent's source files with new versions, and can also -add new files or remove unnecessary ones. -This facility is the project analog of a type extension in -object-oriented programming. Project hierarchies are permitted (an extending -project may itself be extended), and a project that -extends a project can also import other projects. - -A third example is that of using project extensions to provide different -versions of the same system. For instance, assume that a @code{Common} -project is used by two development branches. One of the branches has now -been frozen, and no further change can be done to it or to @code{Common}. -However, the other development branch still needs evolution of @code{Common}. -Project extensions provide a flexible solution to create a new version -of a subsystem while sharing and reusing as much as possible from the original -one. - -A project extension implicitly inherits all the sources and objects from the -project it extends. It is possible to create a new version of some of the -sources in one of the additional source directories of the extending -project. Those new versions hide the original versions. Adding new sources or -removing existing ones is also possible. Here is an example on how to extend -the project @code{Build} from previous examples: - -@smallexample @c projectfile - @b{project} Work @b{extends} "../bld/build.gpr" @b{is} - @b{end} Work; -@end smallexample - -@noindent -The project after @b{extends} is the one being extended. As usual, it can be -specified using an absolute path, or a path relative to any of the directories -in the project path (@pxref{Project Dependencies}). This project does not -specify source or object directories, so the default values for these -attributes will be used that is to say the current directory (where project -@code{Work} is placed). We can compile that project with - -@smallexample - gprbuild -Pwork -@end smallexample - -@noindent -If no sources have been placed in the current directory, this command -won't do anything, since this project does not change the -sources it inherited from @code{Build}, therefore all the object files -in @code{Build} and its dependencies are still valid and are reused -automatically. - -Suppose we now want to supply an alternate version of @file{pack.adb} but use -the existing versions of @file{pack.ads} and @file{proc.adb}. We can create -the new file in Work's current directory (likely by copying the one from the -@code{Build} project and making changes to it. If new packages are needed at -the same time, we simply create new files in the source directory of the -extending project. - -When we recompile, @command{gprbuild} will now automatically recompile -this file (thus creating @file{pack.o} in the current directory) and -any file that depends on it (thus creating @file{proc.o}). Finally, the -executable is also linked locally. - -Note that we could have obtained the desired behavior using project import -rather than project inheritance. A @code{base} project would contain the -sources for @file{pack.ads} and @file{proc.adb}, and @code{Work} would -import @code{base} and add @file{pack.adb}. In this scenario, @code{base} -cannot contain the original version of @file{pack.adb} otherwise there would be -2 versions of the same unit in the closure of the project and this is not -allowed. Generally speaking, it is not recommended to put the spec and the -body of a unit in different projects since this affects their autonomy and -reusability. - -In a project file that extends another project, it is possible to -indicate that an inherited source is @b{not part} of the sources of the -extending project. This is necessary sometimes when a package spec has -been overridden and no longer requires a body: in this case, it is -necessary to indicate that the inherited body is not part of the sources -of the project, otherwise there will be a compilation error -when compiling the spec. - -@cindex @code{Excluded_Source_Files} -@cindex @code{Excluded_Source_List_File} -For that purpose, the attribute @b{Excluded_Source_Files} is used. -Its value is a list of file names. -It is also possible to use attribute @code{Excluded_Source_List_File}. -Its value is the path of a text file containing one file name per -line. - -@smallexample @c @projectfile -project Work extends "../bld/build.gpr" is - for Source_Files use ("pack.ads"); - -- New spec of Pkg does not need a completion - for Excluded_Source_Files use ("pack.adb"); -end Work; -@end smallexample - -@noindent -All packages that are not declared in the extending project are inherited from -the project being extended, with their attributes, with the exception of -@code{Linker'Linker_Options} which is never inherited. In particular, an -extending project retains all the switches specified in the project being -extended. - -At the project level, if they are not declared in the extending project, some -attributes are inherited from the project being extended. They are: -@code{Languages}, @code{Main} (for a root non library project) and -@code{Library_Name} (for a project extending a library project). - -@menu -* Project Hierarchy Extension:: -@end menu - -@c --------------------------------------------- -@node Project Hierarchy Extension -@subsection Project Hierarchy Extension -@c --------------------------------------------- - -@noindent -One of the fundamental restrictions in project extension is the following: -@b{A project is not allowed to import directly or indirectly at the same time an -extending project and one of its ancestors}. - -By means of example, consider the following hierarchy of projects. - -@smallexample - a.gpr contains package A1 - b.gpr, imports a.gpr and contains B1, which depends on A1 - c.gpr, imports b.gpr and contains C1, which depends on B1 -@end smallexample - -@noindent -If we want to locally extend the packages @code{A1} and @code{C1}, we need to -create several extending projects: - -@smallexample - a_ext.gpr which extends a.gpr, and overrides A1 - b_ext.gpr which extends b.gpr and imports a_ext.gpr - c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1 -@end smallexample - -@noindent -@smallexample @c projectfile - @b{project} A_Ext @b{extends} "a.gpr" @b{is} - @b{for} Source_Files @b{use} ("a1.adb", "a1.ads"); - @b{end} A_Ext; - - @b{with} "a_ext.gpr"; - @b{project} B_Ext @b{extends} "b.gpr" @b{is} - @b{end} B_Ext; - - @b{with} "b_ext.gpr"; - @b{project} C_Ext @b{extends} "c.gpr" @b{is} - @b{for} Source_Files @b{use} ("c1.adb"); - @b{end} C_Ext; -@end smallexample - -@noindent -The extension @file{b_ext.gpr} is required, even though we are not overriding -any of the sources of @file{b.gpr} because otherwise @file{c_expr.gpr} would -import @file{b.gpr} which itself knows nothing about @file{a_ext.gpr}. - -@cindex extends all -When extending a large system spanning multiple projects, it is often -inconvenient to extend every project in the hierarchy that is impacted by a -small change introduced in a low layer. In such cases, it is possible to create -an @b{implicit extension} of an entire hierarchy using @b{extends all} -relationship. - -When the project is extended using @code{extends all} inheritance, all projects -that are imported by it, both directly and indirectly, are considered virtually -extended. That is, the project manager creates implicit projects -that extend every project in the hierarchy; all these implicit projects do not -control sources on their own and use the object directory of -the "extending all" project. - -It is possible to explicitly extend one or more projects in the hierarchy -in order to modify the sources. These extending projects must be imported by -the "extending all" project, which will replace the corresponding virtual -projects with the explicit ones. - -When building such a project hierarchy extension, the project manager will -ensure that both modified sources and sources in implicit extending projects -that depend on them are recompiled. - -Thus, in our example we could create the following projects instead: - -@smallexample - a_ext.gpr, extends a.gpr and overrides A1 - c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1 - -@end smallexample - -@noindent -@smallexample @c projectfile - @b{project} A_Ext @b{extends} "a.gpr" @b{is} - @b{for} Source_Files @b{use} ("a1.adb", "a1.ads"); - @b{end} A_Ext; - - @b{with} "a_ext.gpr"; - @b{project} C_Ext @b{extends} @b{all} "c.gpr" @b{is} - @b{for} Source_Files @b{use} ("c1.adb"); - @b{end} C_Ext; -@end smallexample - -@noindent -When building project @file{c_ext.gpr}, the entire modified project space is -considered for recompilation, including the sources of @file{b.gpr} that are -impacted by the changes in @code{A1} and @code{C1}. - -@c --------------------------------------------- -@node Aggregate Projects -@section Aggregate Projects -@c --------------------------------------------- - -@noindent - -Aggregate projects are an extension of the project paradigm, and are -meant to solve a few specific use cases that cannot be solved directly -using standard projects. This section will go over a few of these use -cases to try to explain what you can use aggregate projects for. - -@menu -* Building all main programs from a single project tree:: -* Building a set of projects with a single command:: -* Define a build environment:: -* Performance improvements in builder:: -* Syntax of aggregate projects:: -* package Builder in aggregate projects:: -@end menu - -@c ----------------------------------------------------------- -@node Building all main programs from a single project tree -@subsection Building all main programs from a single project tree -@c ----------------------------------------------------------- - -Most often, an application is organized into modules and submodules, -which are very conveniently represented as a project tree or graph -(the root project A @code{with}s the projects for each modules (say B and C), -which in turn @code{with} projects for submodules. - -Very often, modules will build their own executables (for testing -purposes for instance), or libraries (for easier reuse in various -contexts). - -However, if you build your project through @command{gnatmake} or -@command{gprbuild}, using a syntax similar to - -@smallexample - gprbuild -PA.gpr -@end smallexample - -this will only rebuild the main programs of project A, not those of the -imported projects B and C. Therefore you have to spawn several -@command{gnatmake} commands, one per project, to build all executables. -This is a little inconvenient, but more importantly is inefficient -because @command{gnatmake} needs to do duplicate work to ensure that sources are -up-to-date, and cannot easily compile things in parallel when using -the -j switch. - -Also libraries are always rebuilt when building a project. - -You could therefore define an aggregate project Agg that groups A, B -and C. Then, when you build with - -@smallexample - gprbuild -PAgg.gpr -@end smallexample - -this will build all mains from A, B and C. - -@smallexample @c projectfile - aggregate @b{project} Agg @b{is} - @b{for} Project_Files @b{use} ("a.gpr", "b.gpr", "c.gpr"); - @b{end} Agg; -@end smallexample - -If B or C do not define any main program (through their Main -attribute), all their sources are built. When you do not group them -in the aggregate project, only those sources that are needed by A -will be built. - -If you add a main to a project P not already explicitly referenced in the -aggregate project, you will need to add "p.gpr" in the list of project -files for the aggregate project, or the main will not be built when -building the aggregate project. - -Aggregate projects are supported only with @command{gprbuild}, not with -@command{gnatmake}. - -@c --------------------------------------------------------- -@node Building a set of projects with a single command -@subsection Building a set of projects with a single command -@c --------------------------------------------------------- - -One other case is when you have multiple applications and libraries -that are built independently from each other (but can be built in -parallel). For instance, you have a project tree rooted at A, and -another one (which might share some subprojects) rooted at B. - -Using only @command{gprbuild}, you could do - -@smallexample - gprbuild -PA.gpr - gprbuild -PB.gpr -@end smallexample - -to build both. But again, @command{gprbuild} has to do some duplicate work for -those files that are shared between the two, and cannot truly build -things in parallel efficiently. - -If the two projects are really independent, share no sources other -than through a common subproject, and have no source files with a -common basename, you could create a project C that imports A and -B. But these restrictions are often too strong, and one has to build -them independently. An aggregate project does not have these -limitations and can aggregate two project trees that have common -sources. - -This scenario is particularly useful in environments like VxWorks 653 -where the applications running in the multiple partitions can be built -in parallel through a single @command{gprbuild} command. This also works nicely -with Annex E. - -@c --------------------------------------------- -@node Define a build environment -@subsection Define a build environment -@c --------------------------------------------- - -The environment variables at the time you launch @command{gprbuild} -will influence the view these tools have of the project -(PATH to find the compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the -projects, environment variables that are referenced in project files -through the "external" built-in function, ...). Several command line switches -can be used to override those (-X or -aP), but on some systems and -with some projects, this might make the command line too long, and on -all systems often make it hard to read. - -An aggregate project can be used to set the environment for all -projects built through that aggregate. One of the nice aspects is that -you can put the aggregate project under configuration management, and -make sure all your user have a consistent environment when -building. The syntax looks like - -@smallexample @c projectfile - aggregate @b{project} Agg @b{is} - @b{for} Project_Files @b{use} ("A.gpr", "B.gpr"); - @b{for} Project_Path @b{use} ("../dir1", "../dir1/dir2"); - @b{for} External ("BUILD") @b{use} "PRODUCTION"; - - @b{package} Builder @b{is} - @b{for} Switches ("Ada") @b{use} ("-q"); - @b{end} Builder; - @b{end} Agg; -@end smallexample - -One of the often requested features in projects is to be able to -reference external variables in @code{with} declarations, as in - -@smallexample @c projectfile - @b{with} @b{external}("SETUP") & "path/prj.gpr"; --@i{ ILLEGAL} - @b{project} MyProject @b{is} - ... - @b{end} MyProject; -@end smallexample - -For various reasons, this is not allowed. But using aggregate projects provide -an elegant solution. For instance, you could use a project file like: - -@smallexample @c projectfile -aggregate @b{project} Agg @b{is} - @b{for} Project_Path @b{use} (@b{external}("SETUP") & "path"); - @b{for} Project_Files @b{use} ("myproject.gpr"); -@b{end} Agg; - -@b{with} "prj.gpr"; --@i{ searched on Agg'Project_Path} -@b{project} MyProject @b{is} - ... -@b{end} MyProject; -@end smallexample - -@c -------------------------------------------- -@node Performance improvements in builder -@subsection Performance improvements in builder -@c -------------------------------------------- - -The loading of aggregate projects is optimized in @command{gprbuild}, -so that all files are searched for only once on the disk -(thus reducing the number of system calls and contributing to faster -compilation times, especially on systems with sources on remote -servers). As part of the loading, @command{gprbuild} -computes how and where a source file should be compiled, and even if it is -found several times in the aggregated projects it will be compiled only -once. - -Since there is no ambiguity as to which switches should be used, files -can be compiled in parallel (through the usual -j switch) and this can -be done while maximizing the use of CPUs (compared to launching -multiple @command{gprbuild} and @command{gnatmake} commands in parallel). - -@c ------------------------------------- -@node Syntax of aggregate projects -@subsection Syntax of aggregate projects -@c ------------------------------------- - -An aggregate project follows the general syntax of project files. The -recommended extension is still @file{.gpr}. However, a special -@code{aggregate} qualifier must be put before the keyword -@code{project}. - -An aggregate project cannot @code{with} any other project (standard or -aggregate), except an abstract project which can be used to share attribute -values. Also, aggregate projects cannot be extended or imported though a -@code{with} clause by any other project. Building other aggregate projects from -an aggregate project is done through the Project_Files attribute (see below). - -An aggregate project does not have any source files directly (only -through other standard projects). Therefore a number of the standard -attributes and packages are forbidden in an aggregate project. Here is the -(non exhaustive) list: - -@itemize @bullet -@item Languages -@item Source_Files, Source_List_File and other attributes dealing with - list of sources. -@item Source_Dirs, Exec_Dir and Object_Dir -@item Library_Dir, Library_Name and other library-related attributes -@item Main -@item Roots -@item Externally_Built -@item Inherit_Source_Path -@item Excluded_Source_Dirs -@item Locally_Removed_Files -@item Excluded_Source_Files -@item Excluded_Source_List_File -@item Interfaces -@end itemize - -The only package that is authorized (albeit optional) is -Builder. Other packages (in particular Compiler, Binder and Linker) -are forbidden. - -The following three attributes can be used only in an aggregate project: - -@table @asis -@item @b{Project_Files}: -@cindex @code{Project_Files} - -This attribute is compulsory (or else we are not aggregating any project, -and thus not doing anything). It specifies a list of @file{.gpr} files -that are grouped in the aggregate. The list may be empty. The project -files can be either other aggregate projects, or standard projects. When -grouping standard projects, you can have both the root of a project tree -(and you do not need to specify all its imported projects), and any project -within the tree. - -Basically, the idea is to specify all those projects that have -main programs you want to build and link, or libraries you want to -build. You can even specify projects that do not use the Main -attribute nor the @code{Library_*} attributes, and the result will be to -build all their source files (not just the ones needed by other -projects). - -The file can include paths (absolute or relative). Paths are relative to -the location of the aggregate project file itself (if you use a base name, -we expect to find the .gpr file in the same directory as the aggregate -project file). The environment variables @code{ADA_PROJECT_PATH}, -@code{GPR_PROJECT_PATH} and @code{GPR_PROJECT_PATH_FILE} are not used to find -the project files. The extension @file{.gpr} is mandatory, since this attribute -contains file names, not project names. - -Paths can also include the @code{"*"} and @code{"**"} globbing patterns. The -latter indicates that any subdirectory (recursively) will be -searched for matching files. The latter (@code{"**"}) can only occur at the -last position in the directory part (ie @code{"a/**/*.gpr"} is supported, but -not @code{"**/a/*.gpr"}). Starting the pattern with @code{"**"} is equivalent -to starting with @code{"./**"}. - -For now, the pattern @code{"*"} is only allowed in the filename part, not -in the directory part. This is mostly for efficiency reasons to limit the -number of system calls that are needed. - -Here are a few valid examples: - -@smallexample @c projectfile - @b{for} Project_Files @b{use} ("a.gpr", "subdir/b.gpr"); - --@i{ two specific projects relative to the directory of agg.gpr} - - @b{for} Project_Files @b{use} ("**/*.gpr"); - --@i{ all projects recursively} -@end smallexample - -@item @b{Project_Path}: -@cindex @code{Project_Path} - -This attribute can be used to specify a list of directories in -which to look for project files in @code{with} declarations. - -When you specify a project in Project_Files (say @code{x/y/a.gpr}), and -@code{a.gpr} imports a project @code{b.gpr}, only @code{b.gpr} is searched in -the project path. @code{a.gpr} must be exactly at -@code{<dir of the aggregate>/x/y/a.gpr}. - -This attribute, however, does not affect the search for the aggregated -project files specified with @code{Project_Files}. - -Each aggregate project has its own @code{Project_Path} (that is if -@code{agg1.gpr} includes @code{agg2.gpr}, they can potentially both have a -different @code{Project_Path}). - -This project path is defined as the concatenation, in that order, of: - -@itemize @bullet -@item the current directory; -@item followed by the command line -aP switches; -@item then the directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH environment -variables; -@item then the directories from the Project_Path attribute; -@item and finally the predefined directories. -@end itemize - -In the example above, agg2.gpr's project path is not influenced by -the attribute agg1'Project_Path, nor is agg1 influenced by -agg2'Project_Path. - -This can potentially lead to errors. In the following example: - -@smallexample - +---------------+ +----------------+ - | Agg1.gpr |-=--includes--=-->| Agg2.gpr | - | 'project_path| | 'project_path | - | | | | - +---------------+ +----------------+ - : : - includes includes - : : - v v - +-------+ +---------+ - | P.gpr |<---------- withs --------| Q.gpr | - +-------+---------\ +---------+ - | | - withs | - | | - v v - +-------+ +---------+ - | R.gpr | | R'.gpr | - +-------+ +---------+ -@end smallexample - -When looking for p.gpr, both aggregates find the same physical file on -the disk. However, it might happen that with their different project -paths, both aggregate projects would in fact find a different r.gpr. -Since we have a common project (p.gpr) "with"ing two different r.gpr, -this will be reported as an error by the builder. - -Directories are relative to the location of the aggregate project file. - -Example: - -@smallexample @c projectfile - @b{for} Project_Path @b{use} ("/usr/local/gpr", "gpr/"); -@end smallexample - -@item @b{External}: -@cindex @code{External} - -This attribute can be used to set the value of environment -variables as retrieved through the @code{external} function -in projects. It does not affect the environment variables -themselves (so for instance you cannot use it to change the value -of your PATH as seen from the spawned compiler). - -This attribute affects the external values as seen in the rest of -the aggregate project, and in the aggregated projects. - -The exact value of external a variable comes from one of three -sources (each level overrides the previous levels): - -@itemize @bullet -@item An External attribute in aggregate project, for instance - @code{for External ("BUILD_MODE") use "DEBUG"}; - -@item Environment variables - -These override the value given by the attribute, so that -users can override the value set in the (presumably shared -with others team members) aggregate project. - -@item The -X command line switch to @command{gprbuild} - -This always takes precedence. - -@end itemize - -This attribute is only taken into account in the main aggregate -project (i.e. the one specified on the command line to @command{gprbuild}), -and ignored in other aggregate projects. It is invalid -in standard projects. -The goal is to have a consistent value in all -projects that are built through the aggregate, which would not -be the case in the diamond case: A groups the aggregate -projects B and C, which both (either directly or indirectly) -build the project P. If B and C could set different values for -the environment variables, we would have two different views of -P, which in particular might impact the list of source files in P. - -@end table - -@c ---------------------------------------------- -@node package Builder in aggregate projects -@subsection package Builder in aggregate projects -@c ---------------------------------------------- - -As we mentioned before, only the package Builder can be specified in -an aggregate project. In this package, only the following attributes -are valid: - -@table @asis -@item @b{Switches}: -@cindex @code{Switches} -This attribute gives the list of switches to use for @command{gprbuild}. -Because no mains can be specified for aggregate projects, the only possible -index for attribute @code{Switches} is @code{others}. All other indexes will -be ignored. - -Example: - -@smallexample @c projectfile -@b{for} Switches (@b{others}) @b{use} ("-v", "-k", "-j8"); -@end smallexample - -These switches are only read from the main aggregate project (the -one passed on the command line), and ignored in all other aggregate -projects or projects. - -It can only contain builder switches, not compiler switches. - -@item @b{Global_Compilation_Switches} -@cindex @code{Global_Compilation_Switches} - -This attribute gives the list of compiler switches for the various -languages. For instance, - -@smallexample @c projectfile -@b{for} Global_Compilation_Switches ("Ada") @b{use} ("O1", "-g"); -@b{for} Global_Compilation_Switches ("C") @b{use} ("-O2"); -@end smallexample - -This attribute is only taken into account in the aggregate project -specified on the command line, not in other aggregate projects. - -In the projects grouped by that aggregate, the attribute -Builder.Global_Compilation_Switches is also ignored. However, the -attribute Compiler.Default_Switches will be taken into account (but -that of the aggregate have higher priority). The attribute -Compiler.Switches is also taken into account and can be used to -override the switches for a specific file. As a result, it always -has priority. - -The rules are meant to avoid ambiguities when compiling. For -instance, aggregate project Agg groups the projects A and B, that -both depend on C. Here is an extra for all of these projects: - -@smallexample @c projectfile - aggregate @b{project} Agg @b{is} - @b{for} Project_Files @b{use} ("a.gpr", "b.gpr"); - @b{package} Builder @b{is} - @b{for} Global_Compilation_Switches ("Ada") @b{use} ("-O2"); - @b{end} Builder; - @b{end} Agg; - - @b{with} "c.gpr"; - @b{project} A @b{is} - @b{package} Builder @b{is} - @b{for} Global_Compilation_Switches ("Ada") @b{use} ("-O1"); - --@i{ ignored} - @b{end} Builder; - - @b{package} Compiler @b{is} - @b{for} Default_Switches ("Ada") - @b{use} ("-O1", "-g"); - @b{for} Switches ("a_file1.adb") - @b{use} ("-O0"); - @b{end} Compiler; - @b{end} A; - - @b{with} "c.gpr"; - @b{project} B @b{is} - @b{package} Compiler @b{is} - @b{for} Default_Switches ("Ada") @b{use} ("-O0"); - @b{end} Compiler; - @b{end} B; - - @b{project} C @b{is} - @b{package} Compiler @b{is} - @b{for} Default_Switches ("Ada") - @b{use} ("-O3", - "-gnatn"); - @b{for} Switches ("c_file1.adb") - @b{use} ("-O0", "-g"); - @b{end} Compiler; - @b{end} C; -@end smallexample - -then the following switches are used: - -@itemize @bullet -@item all files from project A except a_file1.adb are compiled - with "-O2 -g", since the aggregate project has priority. -@item the file a_file1.adb is compiled with - "-O0", since the Compiler.Switches has priority -@item all files from project B are compiled with - "-O2", since the aggregate project has priority -@item all files from C are compiled with "-O2 -gnatn", except for - c_file1.adb which is compiled with "-O0 -g" -@end itemize - -Even though C is seen through two paths (through A and through -B), the switches used by the compiler are unambiguous. - -@item @b{Global_Configuration_Pragmas} -@cindex @code{Global_Configuration_Pragmas} - -This attribute can be used to specify a file containing -configuration pragmas, to be passed to the Ada compiler. Since we -ignore the package Builder in other aggregate projects and projects, -only those pragmas defined in the main aggregate project will be -taken into account. - -Projects can locally add to those by using the -@code{Compiler.Local_Configuration_Pragmas} attribute if they need. - -@item @b{Global_Config_File} -@cindex @code{Global_Config_File} - -This attribute, indexed with a language name, can be used to specify a config -when compiling sources of the language. For Ada, these files are configuration -pragmas files. - -@end table - -For projects that are built through the aggregate, the package Builder -is ignored, except for the Executable attribute which specifies the -name of the executables resulting from the link of the main programs, and -for the Executable_Suffix. - -@c --------------------------------------------- -@node Aggregate Library Projects -@section Aggregate Library Projects -@c --------------------------------------------- - -@noindent - -Aggregate library projects make it possible to build a single library -using object files built using other standard or library -projects. This gives the flexibility to describe an application as -having multiple modules (a GUI, database access, ...) using different -project files (so possibly built with different compiler options) and -yet create a single library (static or relocatable) out of the -corresponding object files. - -@menu -* Building aggregate library projects:: -* Syntax of aggregate library projects:: -@end menu - -@c --------------------------------------------- -@node Building aggregate library projects -@subsection Building aggregate library projects -@c --------------------------------------------- - -For example, we can define an aggregate project Agg that groups A, B -and C: - -@smallexample @c projectfile - aggregate library @b{project} Agg @b{is} - @b{for} Project_Files @b{use} ("a.gpr", "b.gpr", "c.gpr"); - @b{for} Library_Name @b{use} ("agg"); - @b{for} Library_Dir @b{use} ("lagg"); - @b{end} Agg; -@end smallexample - -Then, when you build with: - -@smallexample - gprbuild agg.gpr -@end smallexample - -This will build all units from projects A, B and C and will create a -static library named @file{libagg.a} in the @file{lagg} -directory. An aggregate library project has the same set of -restriction as a standard library project. - -Note that a shared aggregate library project cannot aggregate a -static library project. In platforms where a compiler option is -required to create relocatable object files, a Builder package in the -aggregate library project may be used: - -@smallexample @c projectfile - aggregate library @b{project} Agg @b{is} - @b{for} Project_Files @b{use} ("a.gpr", "b.gpr", "c.gpr"); - @b{for} Library_Name @b{use} ("agg"); - @b{for} Library_Dir @b{use} ("lagg"); - @b{for} Library_Kind @b{use} "relocatable"; - - @b{package} Builder @b{is} - @b{for} Global_Compilation_Switches ("Ada") @b{use} ("-fPIC"); - @b{end} Builder; - @b{end} Agg; -@end smallexample - -With the above aggregate library Builder package, the @code{-fPIC} -option will be passed to the compiler when building any source code -from projects @file{a.gpr}, @file{b.gpr} and @file{c.gpr}. - -@c --------------------------------------------- -@node Syntax of aggregate library projects -@subsection Syntax of aggregate library projects -@c --------------------------------------------- - -An aggregate library project follows the general syntax of project -files. The recommended extension is still @file{.gpr}. However, a special -@code{aggregate library} qualifier must be put before the keyword -@code{project}. - -An aggregate library project cannot @code{with} any other project -(standard or aggregate), except an abstract project which can be used -to share attribute values. - -An aggregate library project does not have any source files directly (only -through other standard projects). Therefore a number of the standard -attributes and packages are forbidden in an aggregate library -project. Here is the (non exhaustive) list: - -@itemize @bullet -@item Languages -@item Source_Files, Source_List_File and other attributes dealing with - list of sources. -@item Source_Dirs, Exec_Dir and Object_Dir -@item Main -@item Roots -@item Externally_Built -@item Inherit_Source_Path -@item Excluded_Source_Dirs -@item Locally_Removed_Files -@item Excluded_Source_Files -@item Excluded_Source_List_File -@item Interfaces -@end itemize - -The only package that is authorized (albeit optional) is Builder. - -The Project_Files attribute (See @pxref{Aggregate Projects}) is used to -described the aggregated projects whose object files have to be -included into the aggregate library. The environment variables -@code{ADA_PROJECT_PATH}, @code{GPR_PROJECT_PATH} and -@code{GPR_PROJECT_PATH_FILE} are not used to find the project files. - -@c --------------------------------------------- -@node Project File Reference -@section Project File Reference -@c --------------------------------------------- - -@noindent -This section describes the syntactic structure of project files, the various -constructs that can be used. Finally, it ends with a summary of all available -attributes. - -@menu -* Project Declaration:: -* Qualified Projects:: -* Declarations:: -* Packages:: -* Expressions:: -* External Values:: -* Typed String Declaration:: -* Variables:: -* Case Constructions:: -* Attributes:: -@end menu - -@c --------------------------------------------- -@node Project Declaration -@subsection Project Declaration -@c --------------------------------------------- - -@noindent -Project files have an Ada-like syntax. The minimal project file is: - -@smallexample @c projectfile -@group -@b{project} Empty @b{is} -@b{end} Empty; -@end group -@end smallexample - -@noindent -The identifier @code{Empty} is the name of the project. -This project name must be present after the reserved -word @code{end} at the end of the project file, followed by a semi-colon. - -@b{Identifiers} (i.e.@: the user-defined names such as project or variable names) -have the same syntax as Ada identifiers: they must start with a letter, -and be followed by zero or more letters, digits or underscore characters; -it is also illegal to have two underscores next to each other. Identifiers -are always case-insensitive ("Name" is the same as "name"). - -@smallexample -simple_name ::= identifier -name ::= simple_name @{ . simple_name @} -@end smallexample - -@noindent -@b{Strings} are used for values of attributes or as indexes for these -attributes. They are in general case sensitive, except when noted -otherwise (in particular, strings representing file names will be case -insensitive on some systems, so that "file.adb" and "File.adb" both -represent the same file). - -@b{Reserved words} are the same as for standard Ada 95, and cannot -be used for identifiers. In particular, the following words are currently -used in project files, but others could be added later on. In bold are the -extra reserved words in project files: @code{all, at, case, end, for, is, -limited, null, others, package, renames, type, use, when, with, @b{extends}, -@b{external}, @b{project}}. - -@b{Comments} in project files have the same syntax as in Ada, two consecutive -hyphens through the end of the line. - -A project may be an @b{independent project}, entirely defined by a single -project file. Any source file in an independent project depends only -on the predefined library and other source files in the same project. -But a project may also depend on other projects, either by importing them -through @b{with clauses}, or by @b{extending} at most one other project. Both -types of dependency can be used in the same project. - -A path name denotes a project file. It can be absolute or relative. -An absolute path name includes a sequence of directories, in the syntax of -the host operating system, that identifies uniquely the project file in the -file system. A relative path name identifies the project file, relative -to the directory that contains the current project, or relative to a -directory listed in the environment variables ADA_PROJECT_PATH and -GPR_PROJECT_PATH. Path names are case sensitive if file names in the host -operating system are case sensitive. As a special case, the directory -separator can always be "/" even on Windows systems, so that project files -can be made portable across architectures. -The syntax of the environment variables ADA_PROJECT_PATH and -GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and -semicolons on Windows. - -A given project name can appear only once in a context clause. - -It is illegal for a project imported by a context clause to refer, directly -or indirectly, to the project in which this context clause appears (the -dependency graph cannot contain cycles), except when one of the with clauses -in the cycle is a @b{limited with}. -@c ??? Need more details here - -@smallexample @c projectfile -@b{with} "other_project.gpr"; -@b{project} My_Project @b{extends} "extended.gpr" @b{is} -@b{end} My_Project; -@end smallexample - -@noindent -These dependencies form a @b{directed graph}, potentially cyclic when using -@b{limited with}. The subgraph reflecting the @b{extends} relations is a tree. - -A project's @b{immediate sources} are the source files directly defined by -that project, either implicitly by residing in the project source directories, -or explicitly through any of the source-related attributes. -More generally, a project's @b{sources} are the immediate sources of the -project together with the immediate sources (unless overridden) of any project -on which it depends directly or indirectly. - -A @b{project hierarchy} can be created, where projects are children of -other projects. The name of such a child project must be @code{Parent.Child}, -where @code{Parent} is the name of the parent project. In particular, this -makes all @code{with} clauses of the parent project automatically visible -in the child project. - -@smallexample -project ::= context_clause project_declaration - -context_clause ::= @{with_clause@} -with_clause ::= @i{with} path_name @{ , path_name @} ; -path_name ::= string_literal - -project_declaration ::= simple_project_declaration | project_extension -simple_project_declaration ::= - @i{project} @i{<project_>}name @i{is} - @{declarative_item@} - @i{end} <project_>simple_name; -@end smallexample - -@c --------------------------------------------- -@node Qualified Projects -@subsection Qualified Projects -@c --------------------------------------------- - -@noindent -Before the reserved @code{project}, there may be one or two @b{qualifiers}, that -is identifiers or reserved words, to qualify the project. -The current list of qualifiers is: - -@table @asis -@item @b{abstract}: qualifies a project with no sources. Such a - project must either have no declaration of attributes @code{Source_Dirs}, - @code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of - @code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared - as empty. If it extends another project, the project it extends must also be a - qualified abstract project. -@item @b{standard}: a standard project is a non library project with sources. - This is the default (implicit) qualifier. -@item @b{aggregate}: a project whose sources are aggregated from other -project files. -@item @b{aggregate library}: a library whose sources are aggregated -from other project or library project files. -@item @b{library}: a library project must declare both attributes - @code{Library_Name} and @code{Library_Dir}. -@item @b{configuration}: a configuration project cannot be in a project tree. - It describes compilers and other tools to @command{gprbuild}. -@end table - -@c --------------------------------------------- -@node Declarations -@subsection Declarations -@c --------------------------------------------- - -@noindent -Declarations introduce new entities that denote types, variables, attributes, -and packages. Some declarations can only appear immediately within a project -declaration. Others can appear within a project or within a package. - -@smallexample -declarative_item ::= simple_declarative_item - | typed_string_declaration - | package_declaration - -simple_declarative_item ::= variable_declaration - | typed_variable_declaration - | attribute_declaration - | case_construction - | empty_declaration - -empty_declaration ::= @i{null} ; -@end smallexample - -@noindent -An empty declaration is allowed anywhere a declaration is allowed. It has -no effect. - -@c --------------------------------------------- -@node Packages -@subsection Packages -@c --------------------------------------------- - -@noindent -A project file may contain @b{packages}, that group attributes (typically -all the attributes that are used by one of the GNAT tools). - -A package with a given name may only appear once in a project file. -The following packages are currently supported in project files -(See @pxref{Attributes} for the list of attributes that each can contain). - -@table @code -@item Binder - This package specifies characteristics useful when invoking the binder either - directly via the @command{gnat} driver or when using a builder such as - @command{gnatmake} or @command{gprbuild}. @xref{Main Subprograms}. -@item Builder - This package specifies the compilation options used when building an - executable or a library for a project. Most of the options should be - set in one of @code{Compiler}, @code{Binder} or @code{Linker} packages, - but there are some general options that should be defined in this - package. @xref{Main Subprograms}, and @pxref{Executable File Names} in - particular. -@ifclear FSFEDITION -@item Check - This package specifies the options used when calling the checking tool - @command{gnatcheck} via the @command{gnat} driver. Its attribute - @b{Default_Switches} has the same semantics as for the package - @code{Builder}. The first string should always be @code{-rules} to specify - that all the other options belong to the @code{-rules} section of the - parameters to @command{gnatcheck}. -@end ifclear -@item Clean - This package specifies the options used when cleaning a project or a project - tree using the tools @command{gnatclean} or @command{gprclean}. -@item Compiler - This package specifies the compilation options used by the compiler for - each languages. @xref{Tools Options in Project Files}. -@item Cross_Reference - This package specifies the options used when calling the library tool - @command{gnatxref} via the @command{gnat} driver. Its attributes - @b{Default_Switches} and @b{Switches} have the same semantics as for the - package @code{Builder}. -@ifclear FSFEDITION -@item Eliminate - This package specifies the options used when calling the tool - @command{gnatelim} via the @command{gnat} driver. Its attributes - @b{Default_Switches} and @b{Switches} have the same semantics as for the - package @code{Builder}. -@end ifclear -@item Finder - This package specifies the options used when calling the search tool - @command{gnatfind} via the @command{gnat} driver. Its attributes - @b{Default_Switches} and @b{Switches} have the same semantics as for the - package @code{Builder}. -@item Gnatls - This package specifies the options to use when invoking @command{gnatls} - via the @command{gnat} driver. -@ifclear FSFEDITION -@item Gnatstub - This package specifies the options used when calling the tool - @command{gnatstub} via the @command{gnat} driver. Its attributes - @b{Default_Switches} and @b{Switches} have the same semantics as for the - package @code{Builder}. -@end ifclear -@item IDE - This package specifies the options used when starting an integrated - development environment, for instance @command{GPS} or @command{Gnatbench}. -@item Install - This package specifies the options used when installing a project - with @command{gprinstall}. @xref{Installation}. -@item Linker - This package specifies the options used by the linker. - @xref{Main Subprograms}. -@ifclear FSFEDITION -@item Metrics - This package specifies the options used when calling the tool - @command{gnatmetric} via the @command{gnat} driver. Its attributes - @b{Default_Switches} and @b{Switches} have the same semantics as for the - package @code{Builder}. -@end ifclear -@item Naming - This package specifies the naming conventions that apply - to the source files in a project. In particular, these conventions are - used to automatically find all source files in the source directories, - or given a file name to find out its language for proper processing. - @xref{Naming Schemes}. -@ifclear FSFEDITION -@item Pretty_Printer - This package specifies the options used when calling the formatting tool - @command{gnatpp} via the @command{gnat} driver. Its attributes - @b{Default_Switches} and @b{Switches} have the same semantics as for the - package @code{Builder}. -@end ifclear -@item Remote - This package is used by @command{gprbuild} to describe how distributed - compilation should be done. -@item Stack - This package specifies the options used when calling the tool - @command{gnatstack} via the @command{gnat} driver. Its attributes - @b{Default_Switches} and @b{Switches} have the same semantics as for the - package @code{Builder}. -@item Synchronize - This package specifies the options used when calling the tool - @command{gnatsync} via the @command{gnat} driver. - -@end table - -In its simplest form, a package may be empty: - -@smallexample @c projectfile -@group -@b{project} Simple @b{is} - @b{package} Builder @b{is} - @b{end} Builder; -@b{end} Simple; -@end group -@end smallexample - -@noindent -A package may contain @b{attribute declarations}, -@b{variable declarations} and @b{case constructions}, as will be -described below. - -When there is ambiguity between a project name and a package name, -the name always designates the project. To avoid possible confusion, it is -always a good idea to avoid naming a project with one of the -names allowed for packages or any name that starts with @code{gnat}. - -A package can also be defined by a @b{renaming declaration}. The new package -renames a package declared in a different project file, and has the same -attributes as the package it renames. The name of the renamed package -must be the same as the name of the renaming package. The project must -contain a package declaration with this name, and the project -must appear in the context clause of the current project, or be its parent -project. It is not possible to add or override attributes to the renaming -project. If you need to do so, you should use an @b{extending declaration} -(see below). - -Packages that are renamed in other project files often come from project files -that have no sources: they are just used as templates. Any modification in the -template will be reflected automatically in all the project files that rename -a package from the template. This is a very common way to share settings -between projects. - -Finally, a package can also be defined by an @b{extending declaration}. This is -similar to a @b{renaming declaration}, except that it is possible to add or -override attributes. - -@smallexample -package_declaration ::= package_spec | package_renaming | package_extension -package_spec ::= - @i{package} @i{<package_>}simple_name @i{is} - @{simple_declarative_item@} - @i{end} package_identifier ; -package_renaming ::== - @i{package} @i{<package_>}simple_name @i{renames} @i{<project_>}simple_name.package_identifier ; -package_extension ::== - @i{package} @i{<package_>}simple_name @i{extends} @i{<project_>}simple_name.package_identifier @i{is} - @{simple_declarative_item@} - @i{end} package_identifier ; -@end smallexample - -@c --------------------------------------------- -@node Expressions -@subsection Expressions -@c --------------------------------------------- - -@noindent -An expression is any value that can be assigned to an attribute or a -variable. It is either a literal value, or a construct requiring runtime -computation by the project manager. In a project file, the computed value of -an expression is either a string or a list of strings. - -A string value is one of: -@itemize @bullet -@item A literal string, for instance @code{"comm/my_proj.gpr"} -@item The name of a variable that evaluates to a string (@pxref{Variables}) -@item The name of an attribute that evaluates to a string (@pxref{Attributes}) -@item An external reference (@pxref{External Values}) -@item A concatenation of the above, as in @code{"prefix_" & Var}. - -@end itemize - -@noindent -A list of strings is one of the following: - -@itemize @bullet -@item A parenthesized comma-separated list of zero or more string expressions, for - instance @code{(File_Name, "gnat.adc", File_Name & ".orig")} or @code{()}. -@item The name of a variable that evaluates to a list of strings -@item The name of an attribute that evaluates to a list of strings -@item A concatenation of a list of strings and a string (as defined above), for - instance @code{("A", "B") & "C"} -@item A concatenation of two lists of strings - -@end itemize - -@noindent -The following is the grammar for expressions - -@smallexample -string_literal ::= "@{string_element@}" -- Same as Ada -string_expression ::= string_literal - | @i{variable_}name - | external_value - | attribute_reference - | ( string_expression @{ & string_expression @} ) -string_list ::= ( string_expression @{ , string_expression @} ) - | @i{string_variable}_name - | @i{string_}attribute_reference -term ::= string_expression | string_list -expression ::= term @{ & term @} -- Concatenation -@end smallexample - -@noindent -Concatenation involves strings and list of strings. As soon as a list of -strings is involved, the result of the concatenation is a list of strings. The -following Ada declarations show the existing operators: - -@smallexample @c ada - @b{function} "&" (X : String; Y : String) @b{return} String; - @b{function} "&" (X : String_List; Y : String) @b{return} String_List; - @b{function} "&" (X : String_List; Y : String_List) @b{return} String_List; -@end smallexample - -@noindent -Here are some specific examples: - -@smallexample @c projectfile -@group - List := () & File_Name; --@i{ One string in this list} - List2 := List & (File_Name & ".orig"); --@i{ Two strings} - Big_List := List & Lists2; --@i{ Three strings} - Illegal := "gnat.adc" & List2; --@i{ Illegal, must start with list} -@end group -@end smallexample - -@c --------------------------------------------- -@node External Values -@subsection External Values -@c --------------------------------------------- - -@noindent -An external value is an expression whose value is obtained from the command -that invoked the processing of the current project file (typically a -@command{gnatmake} or @command{gprbuild} command). - -There are two kinds of external values, one that returns a single string, and -one that returns a string list. - -The syntax of a single string external value is: - -@smallexample -external_value ::= @i{external} ( string_literal [, string_literal] ) -@end smallexample - -@noindent -The first string_literal is the string to be used on the command line or -in the environment to specify the external value. The second string_literal, -if present, is the default to use if there is no specification for this -external value either on the command line or in the environment. - -Typically, the external value will either exist in the -environment variables -or be specified on the command line through the -@option{-X@emph{vbl}=@emph{value}} switch. If both -are specified, then the command line value is used, so that a user can more -easily override the value. - -The function @code{external} always returns a string. It is an error if the -value was not found in the environment and no default was specified in the -call to @code{external}. - -An external reference may be part of a string expression or of a string -list expression, and can therefore appear in a variable declaration or -an attribute declaration. - -Most of the time, this construct is used to initialize typed variables, which -are then used in @b{case} constructions to control the value assigned to -attributes in various scenarios. Thus such variables are often called -@b{scenario variables}. - -The syntax for a string list external value is: - -@smallexample -external_value ::= @i{external_as_list} ( string_literal , string_literal ) -@end smallexample - -@noindent -The first string_literal is the string to be used on the command line or -in the environment to specify the external value. The second string_literal is -the separator between each component of the string list. - -If the external value does not exist in the environment or on the command line, -the result is an empty list. This is also the case, if the separator is an -empty string or if the external value is only one separator. - -Any separator at the beginning or at the end of the external value is -discarded. Then, if there is no separator in the external value, the result is -a string list with only one string. Otherwise, any string between the beginning -and the first separator, between two consecutive separators and between the -last separator and the end are components of the string list. - -@smallexample - @i{external_as_list} ("SWITCHES", ",") -@end smallexample - -@noindent -If the external value is "-O2,-g", -the result is ("-O2", "-g"). - -If the external value is ",-O2,-g,", -the result is also ("-O2", "-g"). - -if the external value is "-gnatv", -the result is ("-gnatv"). - -If the external value is ",,", the result is (""). - -If the external value is ",", the result is (), the empty string list. - -@c --------------------------------------------- -@node Typed String Declaration -@subsection Typed String Declaration -@c --------------------------------------------- - -@noindent -A @b{type declaration} introduces a discrete set of string literals. -If a string variable is declared to have this type, its value -is restricted to the given set of literals. These are the only named -types in project files. A string type may only be declared at the project -level, not inside a package. - -@smallexample -typed_string_declaration ::= - @i{type} @i{<typed_string_>}_simple_name @i{is} ( string_literal @{, string_literal@} ); -@end smallexample - -@noindent -The string literals in the list are case sensitive and must all be different. -They may include any graphic characters allowed in Ada, including spaces. -Here is an example of a string type declaration: - -@smallexample @c projectfile - @b{type} OS @b{is} ("NT", "nt", "Unix", "GNU/Linux", "other OS"); -@end smallexample - -@noindent -Variables of a string type are called @b{typed variables}; all other -variables are called @b{untyped variables}. Typed variables are -particularly useful in @code{case} constructions, to support conditional -attribute declarations. (@pxref{Case Constructions}). - -A string type may be referenced by its name if it has been declared in the same -project file, or by an expanded name whose prefix is the name of the project -in which it is declared. - -@c --------------------------------------------- -@node Variables -@subsection Variables -@c --------------------------------------------- - -@noindent -@b{Variables} store values (strings or list of strings) and can appear -as part of an expression. The declaration of a variable creates the -variable and assigns the value of the expression to it. The name of the -variable is available immediately after the assignment symbol, if you -need to reuse its old value to compute the new value. Before the completion -of its first declaration, the value of a variable defaults to the empty -string (""). - -A @b{typed} variable can be used as part of a @b{case} expression to -compute the value, but it can only be declared once in the project file, -so that all case constructions see the same value for the variable. This -provides more consistency and makes the project easier to understand. -The syntax for its declaration is identical to the Ada syntax for an -object declaration. In effect, a typed variable acts as a constant. - -An @b{untyped} variable can be declared and overridden multiple times -within the same project. It is declared implicitly through an Ada -assignment. The first declaration establishes the kind of the variable -(string or list of strings) and successive declarations must respect -the initial kind. Assignments are executed in the order in which they -appear, so the new value replaces the old one and any subsequent reference -to the variable uses the new value. - -A variable may be declared at the project file level, or within a package. - -@smallexample -typed_variable_declaration ::= - @i{<typed_variable_>}simple_name : @i{<typed_string_>}name := string_expression; -variable_declaration ::= @i{<variable_>}simple_name := expression; -@end smallexample - -@noindent -Here are some examples of variable declarations: - -@smallexample @c projectfile -@group - This_OS : OS := @b{external} ("OS"); --@i{ a typed variable declaration} - That_OS := "GNU/Linux"; --@i{ an untyped variable declaration} - - Name := "readme.txt"; - Save_Name := Name & ".saved"; - - Empty_List := (); - List_With_One_Element := ("-gnaty"); - List_With_Two_Elements := List_With_One_Element & "-gnatg"; - Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada"); -@end group -@end smallexample - -@noindent -A @b{variable reference} may take several forms: - -@itemize @bullet -@item The simple variable name, for a variable in the current package (if any) - or in the current project -@item An expanded name, whose prefix is a context name. - -@end itemize - -@noindent -A @b{context} may be one of the following: - -@itemize @bullet -@item The name of an existing package in the current project -@item The name of an imported project of the current project -@item The name of an ancestor project (i.e., a project extended by the current - project, either directly or indirectly) -@item An expanded name whose prefix is an imported/parent project name, and - whose selector is a package name in that project. -@end itemize - -@c --------------------------------------------- -@node Case Constructions -@subsection Case Constructions -@c --------------------------------------------- - -@noindent -A @b{case} construction is used in a project file to effect conditional -behavior. Through this construction, you can set the value of attributes -and variables depending on the value previously assigned to a typed -variable. - -All choices in a choice list must be distinct. Unlike Ada, the choice -lists of all alternatives do not need to include all values of the type. -An @code{others} choice must appear last in the list of alternatives. - -The syntax of a @code{case} construction is based on the Ada case construction -(although the @code{null} declaration for empty alternatives is optional). - -The case expression must be a string variable, either typed or not, whose value -is often given by an external reference (@pxref{External Values}). - -Each alternative starts with the reserved word @code{when}, either a list of -literal strings separated by the @code{"|"} character or the reserved word -@code{others}, and the @code{"=>"} token. -When the case expression is a typed string variable, each literal string must -belong to the string type that is the type of the case variable. -After each @code{=>}, there are zero or more declarations. The only -declarations allowed in a case construction are other case constructions, -attribute declarations and variable declarations. String type declarations and -package declarations are not allowed. Variable declarations are restricted to -variables that have already been declared before the case construction. - -@smallexample -case_construction ::= - @i{case} @i{<variable_>}name @i{is} @{case_item@} @i{end case} ; - -case_item ::= - @i{when} discrete_choice_list => - @{case_declaration - | attribute_declaration - | variable_declaration - | empty_declaration@} - -discrete_choice_list ::= string_literal @{| string_literal@} | @i{others} -@end smallexample - -@noindent -Here is a typical example, with a typed string variable: - -@smallexample @c projectfile -@group -@b{project} MyProj @b{is} - @b{type} OS_Type @b{is} ("GNU/Linux", "Unix", "NT", "VMS"); - OS : OS_Type := @b{external} ("OS", "GNU/Linux"); - - @b{package} Compiler @b{is} - @b{case} OS @b{is} - @b{when} "GNU/Linux" | "Unix" => - @b{for} Switches ("Ada") - @b{use} ("-gnath"); - @b{when} "NT" => - @b{for} Switches ("Ada") - @b{use} ("-gnatP"); - @b{when} @b{others} => - @b{null}; - @b{end} @b{case}; - @b{end} Compiler; -@b{end} MyProj; -@end group -@end smallexample - -@c --------------------------------------------- -@node Attributes -@subsection Attributes -@c --------------------------------------------- - -@menu -* Project Level Attributes:: -* Package Binder Attributes:: -* Package Builder Attributes:: -@ifclear FSFEDITION -* Package Check Attributes:: -@end ifclear -* Package Clean Attributes:: -* Package Compiler Attributes:: -* Package Cross_Reference Attributes:: -@ifclear FSFEDITION -* Package Eliminate Attributes:: -@end ifclear -* Package Finder Attributes:: -* Package gnatls Attributes:: -@ifclear FSFEDITION -* Package gnatstub Attributes:: -@end ifclear -* Package IDE Attributes:: -* Package Install Attributes:: -* Package Linker Attributes:: -@ifclear FSFEDITION -* Package Metrics Attribute:: -@end ifclear -* Package Naming Attributes:: -@ifclear FSFEDITION -* Package Pretty_Printer Attributes:: -@end ifclear -* Package Remote Attributes:: -* Package Stack Attributes:: -* Package Synchronize Attributes:: -@end menu - -@noindent -A project (and its packages) may have @b{attributes} that define -the project's properties. Some attributes have values that are strings; -others have values that are string lists. - -@smallexample -attribute_declaration ::= - simple_attribute_declaration | indexed_attribute_declaration -simple_attribute_declaration ::= @i{for} attribute_designator @i{use} expression ; -indexed_attribute_declaration ::= - @i{for} @i{<indexed_attribute_>}simple_name ( string_literal) @i{use} expression ; -attribute_designator ::= - @i{<simple_attribute_>}simple_name - | @i{<indexed_attribute_>}simple_name ( string_literal ) -@end smallexample - -@noindent -There are two categories of attributes: @b{simple attributes} -and @b{indexed attributes}. -Each simple attribute has a default value: the empty string (for string -attributes) and the empty list (for string list attributes). -An attribute declaration defines a new value for an attribute, and overrides -the previous value. The syntax of a simple attribute declaration is similar to -that of an attribute definition clause in Ada. - -Some attributes are indexed. These attributes are mappings whose -domain is a set of strings. They are declared one association -at a time, by specifying a point in the domain and the corresponding image -of the attribute. -Like untyped variables and simple attributes, indexed attributes -may be declared several times. Each declaration supplies a new value for the -attribute, and replaces the previous setting. - -Here are some examples of attribute declarations: - -@smallexample @c projectfile - --@i{ simple attributes} - @b{for} Object_Dir @b{use} "objects"; - @b{for} Source_Dirs @b{use} ("units", "test/drivers"); - - --@i{ indexed attributes} - @b{for} Body ("main") @b{use} "Main.ada"; - @b{for} Switches ("main.ada") - @b{use} ("-v", "-gnatv"); - @b{for} Switches ("main.ada") @b{use} Builder'Switches ("main.ada") & "-g"; - - --@i{ indexed attributes copy (from package Builder in project Default)} - --@i{ The package name must always be specified, even if it is the current} - --@i{ package.} - @b{for} Default_Switches @b{use} Default.Builder'Default_Switches; -@end smallexample - -@noindent -Attributes references may appear anywhere in expressions, and are used -to retrieve the value previously assigned to the attribute. If an attribute -has not been set in a given package or project, its value defaults to the -empty string or the empty list, with some exceptions. - -@smallexample -attribute_reference ::= - attribute_prefix ' @i{<simple_attribute>_}simple_name [ (string_literal) ] -attribute_prefix ::= @i{project} - | @i{<project_>}simple_name - | package_identifier - | @i{<project_>}simple_name . package_identifier -@end smallexample - -@noindent -Examples are: - -@smallexample @c projectfile - @b{project}'Object_Dir - Naming'Dot_Replacement - Imported_Project'Source_Dirs - Imported_Project.Naming'Casing - Builder'Default_Switches ("Ada") -@end smallexample - -The exceptions to the empty defaults are: - -@itemize @bullet -@item Object_Dir: default is "." -@item Exec_Dir: default is 'Object_Dir, that is the value of attribute - Object_Dir in the same project, declared or defaulted. -@item Source_Dirs: default is (".") -@end itemize - -@noindent -The prefix of an attribute may be: - -@itemize @bullet -@item @code{project} for an attribute of the current project -@item The name of an existing package of the current project -@item The name of an imported project -@item The name of a parent project that is extended by the current project -@item An expanded name whose prefix is imported/parent project name, - and whose selector is a package name - -@end itemize - -@noindent - -In the following sections, all predefined attributes are succinctly described, -first the project level attributes, that is those attributes that are not in a -package, then the attributes in the different packages. - -It is possible for different tools to dynamically create new packages with -attributes, or new attributes in predefined packages. These attributes are -not documented here. - -The attributes under Configuration headings are usually found only in -configuration project files. - -The characteristics of each attribute are indicated as follows: - -@itemize @bullet - -@item @b{Type of value} - -The value of an attribute may be a single string, indicated by the word -"single", or a string list, indicated by the word "list". - -@item @b{Read-only} - -When the attribute is read-only, that is when it is not allowed to declare -the attribute, this is indicated by the words "read-only". - -@item @b{Optional index} - -If it is allowed in the value of the attribute (both single and list) to have -an optional index, this is indicated by the words "optional index". - -@item @b{Indexed attribute} - -When an it is an indexed attribute, this is indicated by the word "indexed". - -@item @b{Case-sensitivity of the index} - -For an indexed attribute, if the index is case-insensitive, this is indicated -by the words "case-insensitive index". - -@item @b{File name index} - -For an indexed attribute, when the index is a file name, this is indicated by -the words "file name index". The index may or may not be case-sensitive, -depending on the platform. - -@item @b{others allowed in index} - -For an indexed attribute, if it is allowed to use @b{others} as the index, -this is indicated by the words "others allowed". - -When @b{others} is used as the index of an indexed attribute, the value of -the attribute indexed by @b{others} is used when no other index would apply. - -@end itemize - -@node Project Level Attributes -@subsubsection Project Level Attributes -@noindent - -@itemize @bullet - -@item @b{General} - -@itemize @bullet - -@item @b{Name}: single, read-only - -The name of the project. - -@item @b{Project_Dir}: single, read-only - -The path name of the project directory. - -@item @b{Main}: list, optional index - -The list of main sources for the executables. - -@item @b{Languages}: list - -The list of languages of the sources of the project. - -@item @b{Roots}: list, indexed, file name index - -The index is the file name of an executable source. Indicates the list of units -from the main project that need to be bound and linked with their closures -with the executable. The index is either a file name, a language name or "*". -The roots for an executable source are those in @b{Roots} with an index that -is the executable source file name, if declared. Otherwise, they are those in -@b{Roots} with an index that is the language name of the executable source, -if present. Otherwise, they are those in @b{Roots ("*")}, if declared. If none -of these three possibilities are declared, then there are no roots for the -executable source. - -@item @b{Externally_Built}: single - -Indicates if the project is externally built. -Only case-insensitive values allowed are "true" and "false", the default. - -@end itemize -@noindent - -@item @b{Directories} - -@itemize @bullet - -@item @b{Object_Dir}: single - -Indicates the object directory for the project. - -@item @b{Exec_Dir}: single - -Indicates the exec directory for the project, that is the directory where the -executables are. - -@item @b{Source_Dirs}: list - -The list of source directories of the project. - -@item @b{Inherit_Source_Path}: list, indexed, case-insensitive index - -Index is a language name. Value is a list of language names. Indicates that -in the source search path of the index language the source directories of -the languages in the list should be included. - -Example: - -for Inherit_Source_Path ("C++") use ("C"); - -@item @b{Exclude_Source_Dirs}: list - -The list of directories that are included in Source_Dirs but are not source -directories of the project. - -@item @b{Ignore_Source_Sub_Dirs}: list - -Value is a list of simple names for subdirectories that are removed from the -list of source directories, including theur subdirectories. - -@end itemize - -@item @b{Source Files} - -@itemize @bullet - -@item @b{Source_Files}: list - -Value is a list of source file simple names. - -@item @b{Locally_Removed_Files}: list - -Obsolescent. Equivalent to Excluded_Source_Files. - -@item @b{Excluded_Source_Files}: list - -Value is a list of simple file names that are not sources of the project. -Allows to remove sources that are inherited or found in the source directories -and that match the naming scheme. - -@item @b{Source_List_File}: single - -Value is a text file name that contains a list of source file simple names, -one on each line. - -@item @b{Excluded_Source_List_File}: single - -Value is a text file name that contains a list of file simple names that -are not sources of the project. - -@item @b{Interfaces}: list - -Value is a list of file names that constitutes the interfaces of the project. - -@end itemize - -@item @b{Aggregate Projects} - -@itemize @bullet - -@item @b{Project_Files}: list - -Value is the list of aggregated projects. - -@item @b{Project_Path}: list - -Value is a list of directories that are added to the project search path when -looking for the aggregated projects. - -@item @b{External}: single, indexed - -Index is the name of an external reference. Value is the value of the -external reference to be used when parsing the aggregated projects. - -@end itemize - -@item @b{Libraries} - -@itemize @bullet - -@item @b{Library_Dir}: single - -Value is the name of the library directory. This attribute needs to be -declared for each library project. - -@item @b{Library_Name}: single - -Value is the name of the library. This attribute needs to be declared or -inherited for each library project. - -@item @b{Library_Kind}: single - -Specifies the kind of library: static library (archive) or shared library. -Case-insensitive values must be one of "static" for archives (the default) or -"dynamic" or "relocatable" for shared libraries. - -@item @b{Library_Version}: single - -Value is the name of the library file. - -@item @b{Library_Interface}: list - -Value is the list of unit names that constitutes the interfaces -of a Stand-Alone Library project. - -@item @b{Library_Standalone}: single - -Specifies if a Stand-Alone Library (SAL) is encapsulated or not. -Only authorized case-insensitive values are "standard" for non encapsulated -SALs, "encapsulated" for encapsulated SALs or "no" for non SAL library project. - -@item @b{Library_Encapsulated_Options}: list - -Value is a list of options that need to be used when linking an encapsulated -Stand-Alone Library. - -@item @b{Library_Encapsulated_Supported}: single - -Indicates if encapsulated Stand-Alone Libraries are supported. Only -authorized case-insensitive values are "true" and "false" (the default). - -@item @b{Library_Auto_Init}: single - -Indicates if a Stand-Alone Library is auto-initialized. Only authorized -case-insentive values are "true" and "false". - -@item @b{Leading_Library_Options}: list - -Value is a list of options that are to be used at the beginning of -the command line when linking a shared library. - -@item @b{Library_Options}: list - -Value is a list of options that are to be used when linking a shared library. - -@item @b{Library_Rpath_Options}: list, indexed, case-insensitive index - -Index is a language name. Value is a list of options for an invocation of the -compiler of the language. This invocation is done for a shared library project -with sources of the language. The output of the invocation is the path name -of a shared library file. The directory name is to be put in the run path -option switch when linking the shared library for the project. - -@item @b{Library_Src_Dir}: single - -Value is the name of the directory where copies of the sources of the -interfaces of a Stand-Alone Library are to be copied. - -@item @b{Library_ALI_Dir}: single - -Value is the name of the directory where the ALI files of the interfaces -of a Stand-Alone Library are to be copied. When this attribute is not declared, -the directory is the library directory. - -@item @b{Library_gcc}: single - -Obsolescent attribute. Specify the linker driver used to link a shared library. -Use instead attribute Linker'Driver. - -@item @b{Library_Symbol_File}: single - -Value is the name of the library symbol file. - -@item @b{Library_Symbol_Policy}: single - -Indicates the symbol policy kind. Only authorized case-insensitive values are -"autonomous", "default", "compliant", "controlled" or "direct". - -@item @b{Library_Reference_Symbol_File}: single - -Value is the name of the reference symbol file. - -@end itemize - -@item @b{Configuration - General} - -@itemize @bullet - -@item @b{Default_Language}: single - -Value is the case-insensitive name of the language of a project when attribute -Languages is not specified. - -@item @b{Run_Path_Option}: list - -Value is the list of switches to be used when specifying the run path option -in an executable. - -@item @b{Run_Path_Origin}: single - -Value is the string that may replace the path name of the executable -directory in the run path options. - -@item @b{Separate_Run_Path_Options}: single - -Indicates if there may be several run path options specified when linking an -executable. Only authorized case-insensitive values are "true" or "false" (the -default). - -@item @b{Toolchain_Version}: single, indexed, case-insensitive index - -Index is a language name. Specify the version of a toolchain for a language. - -@item @b{Toolchain_Description}: single, indexed, case-insensitive index - -Obsolescent. No longer used. - -@item @b{Object_Generated}: single, indexed, case-insensitive index - -Index is a language name. Indicates if invoking the compiler for a language -produces an object file. Only authorized case-insensitive values are "false" -and "true" (the default). - -@item @b{Objects_Linked}: single, indexed, case-insensitive index - -Index is a language name. Indicates if the object files created by the compiler -for a language need to be linked in the executable. Only authorized -case-insensitive values are "false" and "true" (the default). - -@item @b{Target}: single - -Value is the name of the target platform. Taken into account only in the main -project. - -@item @b{Runtime}: single, indexed, case-insensitive index - -Index is a language name. Indicates the runtime directory that is to be used -when using the compiler of the language. Taken into account only in the main -project. - -@end itemize - -@item @b{Configuration - Libraries} - -@itemize @bullet - -@item @b{Library_Builder}: single - -Value is the path name of the application that is to be used to build -libraries. Usually the path name of "gprlib". - -@item @b{Library_Support}: single - -Indicates the level of support of libraries. Only authorized case-insensitive -values are "static_only", "full" or "none" (the default). - -@end itemize - -@item @b{Configuration - Archives} - -@itemize @bullet - -@item @b{Archive_Builder}: list - -Value is the name of the application to be used to create a static library -(archive), followed by the options to be used. - -@item @b{Archive_Builder_Append_Option}: list - -Value is the list of options to be used when invoking the archive builder -to add project files into an archive. - -@item @b{Archive_Indexer}: list - -Value is the name of the archive indexer, followed by the required options. - -@item @b{Archive_Suffix}: single - -Value is the extension of archives. When not declared, the extension is ".a". - -@item @b{Library_Partial_Linker}: list - -Value is the name of the partial linker executable, followed by the required -options. - -@end itemize - -@item @b{Configuration - Shared Libraries} - -@itemize @bullet - -@item @b{Shared_Library_Prefix}: single - -Value is the prefix in the name of shared library files. When not declared, -the prefix is "lib". - -@item @b{Shared_Library_Suffix}: single - -Value is the extension of the name of shared library files. When not -declared, the extension is ".so". - -@item @b{Symbolic_Link_Supported}: single - -Indicates if symbolic links are supported on the platform. Only authorized -case-insensitive values are "true" and "false" (the default). - -@item @b{Library_Major_Minor_Id_Supported}: single - -Indicates if major and minor ids for shared library names are supported on -the platform. Only authorized case-insensitive values are "true" and "false" -(the default). - -@item @b{Library_Auto_Init_Supported}: single - -Indicates if auto-initialization of Stand-Alone Libraries is supported. Only -authorized case-insensitive values are "true" and "false" (the default). - -@item @b{Shared_Library_Minimum_Switches}: list - -Value is the list of required switches when linking a shared library. - -@item @b{Library_Version_Switches}: list - -Value is the list of switches to specify a internal name for a shared library. - -@item @b{Library_Install_Name_Option}: single - -Value is the name of the option that needs to be used, concatenated with the -path name of the library file, when linking a shared library. - -@item @b{Runtime_Library_Dir}: single, indexed, case-insensitive index - -Index is a language name. Value is the path name of the directory where the -runtime libraries are located. - -@item @b{Runtime_Source_Dir}: single, indexed, case-insensitive index - -Index is a language name. Value is the path name of the directory where the -sources of runtime libraries are located. - -@end itemize - -@end itemize - -@node Package Binder Attributes -@subsubsection Package Binder Attributes - -@itemize @bullet - -@item @b{General} - -@itemize @bullet - -@item @b{Default_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is the list of switches to be used when binding -code of the language, if there is no applicable attribute Switches. - -@item @b{Switches}: list, optional index, indexed, - case-insensitive index, others allowed - -Index is either a language name or a source file name. Value is the list of -switches to be used when binding code. Index is either the source file name -of the executable to be bound or the language name of the code to be bound. - -@end itemize - -@item @b{Configuration - Binding} - -@itemize @bullet - -@item @b{Driver}: single, indexed, case-insensitive index - -Index is a language name. Value is the name of the application to be used when -binding code of the language. - -@item @b{Required_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is the list of the required switches to be -used when binding code of the language. - -@item @b{Prefix}: single, indexed, case-insensitive index - -Index is a language name. Value is a prefix to be used for the binder exchange -file name for the language. Used to have different binder exchange file names -when binding different languages. - -@item @b{Objects_Path}: single,indexed, case-insensitive index - -Index is a language name. Value is the name of the environment variable that -contains the path for the object directories. - -@item @b{Object_Path_File}: single,indexed, case-insensitive index - -Index is a language name. Value is the name of the environment variable. The -value of the environment variable is the path name of a text file that -contains the list of object directories. - -@end itemize - -@end itemize - -@node Package Builder Attributes -@subsubsection Package Builder Attributes - -@itemize @bullet - -@item @b{Default_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is the list of builder switches to be used when -building an executable of the language, if there is no applicable attribute -Switches. - -@item @b{Switches}: list, optional index, indexed, case-insensitive index, - others allowed - -Index is either a language name or a source file name. Value is the list of -builder switches to be used when building an executable. Index is either the -source file name of the executable to be built or its language name. - -@item @b{Global_Compilation_Switches}: list, optional index, indexed, - case-insensitive index - -Index is either a language name or a source file name. Value is the list of -compilation switches to be used when building an executable. Index is either -the source file name of the executable to be built or its language name. - -@item @b{Executable}: single, indexed, case-insensitive index - -Index is an executable source file name. Value is the simple file name of the -executable to be built. - -@item @b{Executable_Suffix}: single - -Value is the extension of the file names of executable. When not specified, -the extension is the default extension of executables on the platform. - -@item @b{Global_Configuration_Pragmas}: single - -Value is the file name of a configuration pragmas file that is specified to -the Ada compiler when compiling any Ada source in the project tree. - -@item @b{Global_Config_File}: single, indexed, case-insensitive index - -Index is a language name. Value is the file name of a configuration file that -is specified to the compiler when compiling any source of the language in the -project tree. - -@end itemize - -@ifclear FSFEDITION -@node Package Check Attributes -@subsubsection Package Check Attributes - -@itemize @bullet - -@item @b{Default_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is a list of switches to be used when invoking -@code{gnatcheck} for a source of the language, if there is no applicable -attribute Switches. - -@item @b{Switches}: list, optional index, indexed, case-insensitive index, - others allowed - -Index is a source file name. Value is the list of switches to be used when -invoking @code{gnatcheck} for the source. - -@end itemize -@end ifclear - -@node Package Clean Attributes -@subsubsection Package Clean Attributes - -@itemize @bullet - -@item @b{Switches}: list - -Value is a list of switches to be used by the cleaning application. - -@item @b{Source_Artifact_Extensions}: list, indexed, case-insensitive index - -Index is a language names. Value is the list of extensions for file names -derived from object file names that need to be cleaned in the object -directory of the project. - -@item @b{Object_Artifact_Extensions}: list, indexed, case-insensitive index - -Index is a language names. Value is the list of extensions for file names -derived from source file names that need to be cleaned in the object -directory of the project. - -@item @b{Artifacts_In_Object_Dir}: single - -Value is a list of file names expressed as regular expressions that are to be -deleted by gprclean in the object directory of the project. - -@item @b{Artifacts_In_Exec_Dir}: single - -Value is list of file names expressed as regular expressions that are to be -deleted by gprclean in the exec directory of the main project. - -@end itemize - -@node Package Compiler Attributes -@subsubsection Package Compiler Attributes - -@itemize @bullet - -@item @b{General} - -@itemize @bullet - -@item @b{Default_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is a list of switches to be used when invoking -the compiler for the language for a source of the project, if there is no -applicable attribute Switches. - -@item @b{Switches}: list, optional index, indexed, case-insensitive index, - others allowed - -Index is a source file name or a language name. Value is the list of switches -to be used when invoking the compiler for the source or for its language. - -@item @b{Local_Configuration_Pragmas}: single - -Value is the file name of a configuration pragmas file that is specified to -the Ada compiler when compiling any Ada source in the project. - -@item @b{Local_Config_File}: single, indexed, case-insensitive index - -Index is a language name. Value is the file name of a configuration file that -is specified to the compiler when compiling any source of the language in the -project. - -@end itemize - -@item @b{Configuration - Compiling} - -@itemize @bullet - -@item @b{Driver}: single, indexed, case-insensitive index - -Index is a language name. Value is the name of the executable for the compiler -of the language. - -@item @b{Language_Kind}: single, indexed, case-insensitive index - -Index is a language name. Indicates the kind of the language, either file based -or unit based. Only authorized case-insensitive values are "unit_based" and -"file_based" (the default). - -@item @b{Dependency_Kind}: single, indexed, case-insensitive index - -Index is a language name. Indicates how the dependencies are handled for the -language. Only authorized case-insensitive values are "makefile", "ali_file", -"ali_closure" or "none" (the default). - -@item @b{Required_Switches}: list, indexed, case-insensitive index - -Equivalent to attribute Leading_Required_Switches. - -@item @b{Leading_Required_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is the list of the minimum switches to be used -at the beginning of the command line when invoking the compiler for the -language. - -@item @b{Trailing_Required_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is the list of the minimum switches to be used -at the end of the command line when invoking the compiler for the language. - -@item @b{PIC_Option}: list, indexed, case-insensitive index - -Index is a language name. Value is the list of switches to be used when -compiling a source of the language when the project is a shared library -project. - -@item @b{Path_Syntax}: single, indexed, case-insensitive index - -Index is a language name. Value is the kind of path syntax to be used when -invoking the compiler for the language. Only authorized case-insensitive -values are "canonical" and "host" (the default). - -@item @b{Source_File_Switches}: single, indexed, case-insensitive index - -Index is a language name. Value is a list of switches to be used just before -the path name of the source to compile when invoking the compiler for a source -of the language. - -@item @b{Object_File_Suffix}: single, indexed, case-insensitive index - -Index is a language name. Value is the extension of the object files created -by the compiler of the language. When not specified, the extension is the -default one for the platform. - -@item @b{Object_File_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is the list of switches to be used by the -compiler of the language to specify the path name of the object file. When not -specified, the switch used is "-o". - -@item @b{Multi_Unit_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is the list of switches to be used to compile -a unit in a multi unit source of the language. The index of the unit in the -source is concatenated with the last switches in the list. - -@item @b{Multi_Unit_Object_Separator}: single, indexed, case-insensitive index - -Index is a language name. Value is the string to be used in the object file -name before the index of the unit, when compiling a unit in a multi unit source -of the language. - -@end itemize - -@item @b{Configuration - Mapping Files} - -@itemize @bullet - -@item @b{Mapping_File_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is the list of switches to be used to specify -a mapping file when invoking the compiler for a source of the language. - -@item @b{Mapping_Spec_Suffix}: single, indexed, case-insensitive index - -Index is a language name. Value is the suffix to be used in a mapping file -to indicate that the source is a spec. - -@item @b{Mapping_Body_Suffix}: single, indexed, case-insensitive index - -Index is a language name. Value is the suffix to be used in a mapping file -to indicate that the source is a body. - -@end itemize - -@item @b{Configuration - Config Files} - -@itemize @bullet - -@item @b{Config_File_Switches}: list: single, indexed, case-insensitive index - -Index is a language name. Value is the list of switches to specify to the -compiler of the language a configuration file. - -@item @b{Config_Body_File_Name}: single, indexed, case-insensitive index - -Index is a language name. Value is the template to be used to indicate a -configuration specific to a body of the language in a configuration -file. - -@item @b{Config_Body_File_Name_Index}: single, indexed, case-insensitive index - -Index is a language name. Value is the template to be used to indicate a -configuration specific to the body a unit in a multi unit source of the -language in a configuration file. - -@item @b{Config_Body_File_Name_Pattern}: single, indexed, - case-insensitive index - -Index is a language name. Value is the template to be used to indicate a -configuration for all bodies of the languages in a configuration file. - -@item @b{Config_Spec_File_Name}: single, indexed, case-insensitive index - -Index is a language name. Value is the template to be used to indicate a -configuration specific to a spec of the language in a configuration -file. - -@item @b{Config_Spec_File_Name_Index}: single, indexed, case-insensitive index - -Index is a language name. Value is the template to be used to indicate a -configuration specific to the spec a unit in a multi unit source of the -language in a configuration file. - -@item @b{Config_Spec_File_Name_Pattern}: single, indexed, - case-insensitive index - -Index is a language name. Value is the template to be used to indicate a -configuration for all specs of the languages in a configuration file. - -@item @b{Config_File_Unique}: single, indexed, case-insensitive index - -Index is a language name. Indicates if there should be only one configuration -file specified to the compiler of the language. Only authorized -case-insensitive values are "true" and "false" (the default). - -@end itemize - -@item @b{Configuration - Dependencies} - -@itemize @bullet - -@item @b{Dependency_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is the list of switches to be used to specify -to the compiler the dependency file when the dependency kind of the language is -file based, and when Dependency_Driver is not specified for the language. - -@item @b{Dependency_Driver}: list, indexed, case-insensitive index - -Index is a language name. Value is the name of the executable to be used to -create the dependency file for a source of the language, followed by the -required switches. - -@end itemize - -@item @b{Configuration - Search Paths} - -@itemize @bullet - -@item @b{Include_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is the list of switches to specify to the -compiler of the language to indicate a directory to look for sources. - -@item @b{Include_Path}: single, indexed, case-insensitive index - -Index is a language name. Value is the name of an environment variable that -contains the path of all the directories that the compiler of the language -may search for sources. - -@item @b{Include_Path_File}: single, indexed, case-insensitive index - -Index is a language name. Value is the name of an environment variable the -value of which is the path name of a text file that contains the directories -that the compiler of the language may search for sources. - -@item @b{Object_Path_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is the list of switches to specify to the -compiler of the language the name of a text file that contains the list of -object directories. When this attribute is not declared, the text file is -not created. - -@end itemize - -@end itemize - -@node Package Cross_Reference Attributes -@subsubsection Package Cross_Reference Attributes - -@itemize @bullet - -@item @b{Default_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is a list of switches to be used when invoking -@code{gnatxref} for a source of the language, if there is no applicable -attribute Switches. - -@item @b{Switches}: list, optional index, indexed, case-insensitive index, - others allowed - -Index is a source file name. Value is the list of switches to be used when -invoking @code{gnatxref} for the source. - -@end itemize - -@ifclear FSFEDITION -@node Package Eliminate Attributes -@subsubsection Package Eliminate Attributes - -@itemize @bullet - -@item @b{Default_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is a list of switches to be used when invoking -@code{gnatelim} for a source of the language, if there is no applicable -attribute Switches. - -@item @b{Switches}: list, optional index, indexed, case-insensitive index, - others allowed - -Index is a source file name. Value is the list of switches to be used when -invoking @code{gnatelim} for the source. - -@end itemize -@end ifclear - -@node Package Finder Attributes -@subsubsection Package Finder Attributes - -@itemize @bullet - -@item @b{Default_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is a list of switches to be used when invoking -@code{gnatfind} for a source of the language, if there is no applicable -attribute Switches. - -@item @b{Switches}: list, optional index, indexed, case-insensitive index, - others allowed - -Index is a source file name. Value is the list of switches to be used when -invoking @code{gnatfind} for the source. - -@end itemize - -@node Package gnatls Attributes -@subsubsection Package gnatls Attributes - -@itemize @bullet - -@item @b{Switches}: list - -Value is a list of switches to be used when invoking @code{gnatls}. - -@end itemize - -@ifclear FSFEDITION -@node Package gnatstub Attributes -@subsubsection Package gnatstub Attributes - -@itemize @bullet - -@item @b{Default_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is a list of switches to be used when invoking -@code{gnatstub} for a source of the language, if there is no applicable -attribute Switches. - -@item @b{Switches}: list, optional index, indexed, case-insensitive index, - others allowed - -Index is a source file name. Value is the list of switches to be used when -invoking @code{gnatstub} for the source. - -@end itemize -@end ifclear - -@node Package IDE Attributes -@subsubsection Package IDE Attributes - -@itemize @bullet - -@item @b{Default_Switches}: list, indexed - -Index is the name of an external tool that the GNAT Programming System (GPS) -is supporting. Value is a list of switches to use when invoking that tool. - -@item @b{Remote_Host}: single - -Value is a string that designates the remote host in a cross-compilation -environment, to be used for remote compilation and debugging. This attribute -should not be specified when running on the local machine. - -@item @b{Program_Host}: single - -Value is a string that specifies the name of IP address of the embedded target -in a cross-compilation environment, on which the program should execute. - -@item @b{Communication_Protocol}: single - -Value is the name of the protocol to use to communicate with the target -in a cross-compilation environment, for example @code{"wtx"} or -@code{"vxworks"}. - -@item @b{Compiler_Command}: single, indexed, case-insensitive index - -Index is a language Name. Value is a string that denotes the command to be -used to invoke the compiler. The value of @code{Compiler_Command ("Ada")} is -expected to be compatible with @command{gnatmake}, in particular in -the handling of switches. - -@item @b{Debugger_Command}: single - -Value is a string that specifies the name of the debugger to be used, such as -gdb, powerpc-wrs-vxworks-gdb or gdb-4. - -@item @b{gnatlist}: single - -Value is a string that specifies the name of the @command{gnatls} utility -to be used to retrieve information about the predefined path; for example, -@code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}. - -@item @b{VCS_Kind}: single - -Value is a string used to specify the Version Control System (VCS) to be used -for this project, for example "Subversion", "ClearCase". If the -value is set to "Auto", the IDE will try to detect the actual VCS used -on the list of supported ones. - -@item @b{VCS_File_Check}: single - -Value is a string that specifies the command used by the VCS to check -the validity of a file, either when the user explicitly asks for a check, -or as a sanity check before doing the check-in. - -@item @b{VCS_Log_Check}: single - -Value is a string that specifies the command used by the VCS to check -the validity of a log file. - -@item @b{Documentation_Dir}: single - -Value is the directory used to generate the documentation of source code. - -@end itemize - -@node Package Install Attributes -@subsubsection Package Install Attributes - -@itemize @bullet - -@item @b{Artifacts}: list, indexed - -An array attribute to declare a set of files not part of the sources -to be installed. The array discriminant is the directory where the -file is to be installed. If a relative directory then Prefix (see -below) is prepended. - -@item @b{Prefix}: single - -Value is the install destination directory. - -@item @b{Sources_Subdir}: single - -Value is the sources directory or subdirectory of Prefix. - -@item @b{Exec_Subdir}: single - -Value is the executables directory or subdirectory of Prefix. - -@item @b{Lib_Subdir}: single - -Value is library directory or subdirectory of Prefix. - -@item @b{Project_Subdir}: single - -Value is the project directory or subdirectory of Prefix. - -@item @b{Active}: single - -Indicates that the project is to be installed or not. Case-insensitive value -"false" means that the project is not to be installed, all other values mean -that the project is to be installed. - -@item @b{Mode}: single - -Value is the installation mode, it is either @b{dev} (default) or @b{usage}. - -@item @b{Install_Name}: single - -Specify the name to use for recording the installation. The default is -the project name without the extension. - -@end itemize - -@node Package Linker Attributes -@subsubsection Package Linker Attributes - -@itemize @bullet - -@item @b{General} - -@itemize @bullet - -@item @b{Required_Switches}: list - -Value is a list of switches that are required when invoking the linker to link -an executable. - -@item @b{Default_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is a list of switches for the linker when -linking an executable for a main source of the language, when there is no -applicable Switches. - -@item @b{Leading_Switches}: list, optional index, indexed, - case-insensitive index, others allowed - -Index is a source file name or a language name. Value is the list of switches -to be used at the beginning of the command line when invoking the linker to -build an executable for the source or for its language. - -@item @b{Switches}: list, optional index, indexed, case-insensitive index, - others allowed - -Index is a source file name or a language name. Value is the list of switches -to be used when invoking the linker to build an executable for the source or -for its language. - -@item @b{Trailing_Switches}: list, optional index, indexed, - case-insensitive index, others allowed - -Index is a source file name or a language name. Value is the list of switches -to be used at the end of the command line when invoking the linker to -build an executable for the source or for its language. These switches may -override the Required_Switches. - -@item @b{Linker_Options}: list - -Value is a list of switches/options that are to be added when linking an -executable from a project importing the current project directly or indirectly. -Linker_Options are not used when linking an executable from the current -project. - -@item @b{Map_File_Option}: single - -Value is the switch to specify the map file name that the linker needs to -create. - -@end itemize - -@item @b{Configuration - Linking} - -@itemize @bullet - -@item @b{Driver}: single - -Value is the name of the linker executable. - -@end itemize - -@item @b{Configuration - Response Files} - -@itemize @bullet - -@item @b{Max_Command_Line_Length}: single - -Value is the maximum number of character in the command line when invoking -the linker to link an executable. - -@item @b{Response_File_Format}: single - -Indicates the kind of response file to create when the length of the linking -command line is too large. Only authorized case-insensitive values are "none", -"gnu", "object_list", "gcc_gnu", "gcc_option_list" and "gcc_object_list". - -@item @b{Response_File_Switches}: list - -Value is the list of switches to specify a response file to the linker. - -@end itemize - -@end itemize - -@ifclear FSFEDITION -@node Package Metrics Attribute -@subsubsection Package Metrics Attribute - -@itemize @bullet - -@item @b{Default_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is a list of switches to be used when invoking -@code{gnatmetric} for a source of the language, if there is no applicable -attribute Switches. - -@item @b{Switches}: list, optional index, indexed, case-insensitive index, - others allowed - -Index is a source file name. Value is the list of switches to be used when -invoking @code{gnatmetric} for the source. - -@end itemize -@end ifclear - -@node Package Naming Attributes -@subsubsection Package Naming Attributes - -@itemize @bullet - -@item @b{Specification_Suffix}: single, indexed, case-insensitive index - -Equivalent to attribute Spec_Suffix. - -@item @b{Spec_Suffix}: single, indexed, case-insensitive index - -Index is a language name. Value is the extension of file names for specs of -the language. - -@item @b{Implementation_Suffix}: single, indexed, case-insensitive index - -Equivalent to attribute Body_Suffix. - -@item @b{Body_Suffix}: single, indexed, case-insensitive index - -Index is a language name. Value is the extension of file names for bodies of -the language. - -@item @b{Separate_Suffix}: single - -Value is the extension of file names for subunits of Ada. - -@item @b{Casing}: single - -Indicates the casing of sources of the Ada language. Only authorized -case-insensitive values are "lowercase", "uppercase" and "mixedcase". - -@item @b{Dot_Replacement}: single - -Value is the string that replace the dot of unit names in the source file names -of the Ada language. - -@item @b{Specification}: single, optional index, indexed, - case-insensitive index - -Equivalent to attribute Spec. - -@item @b{Spec}: single, optional index, indexed, case-insensitive index - -Index is a unit name. Value is the file name of the spec of the unit. - -@item @b{Implementation}: single, optional index, indexed, - case-insensitive index - -Equivalent to attribute Body. - -@item @b{Body}: single, optional index, indexed, case-insensitive index - -Index is a unit name. Value is the file name of the body of the unit. - -@item @b{Specification_Exceptions}: list, indexed, case-insensitive index - -Index is a language name. Value is a list of specs for the language that do not -necessarily follow the naming scheme for the language and that may or may not -be found in the source directories of the project. - -@item @b{Implementation_Exceptions}: list, indexed, case-insensitive index - -Index is a language name. Value is a list of bodies for the language that do not -necessarily follow the naming scheme for the language and that may or may not -be found in the source directories of the project. - -@end itemize - -@ifclear FSFEDITION -@node Package Pretty_Printer Attributes -@subsubsection Package Pretty_Printer Attributes - -@itemize @bullet - -@item @b{Default_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is a list of switches to be used when invoking -@code{gnatpp} for a source of the language, if there is no applicable -attribute Switches. - -@item @b{Switches}: list, optional index, indexed, case-insensitive index, - others allowed - -Index is a source file name. Value is the list of switches to be used when -invoking @code{gnatpp} for the source. - -@end itemize -@end ifclear - -@node Package Remote Attributes -@subsubsection Package Remote Attributes - -@itemize @bullet - -@item @b{Included_Patterns}: list - -If this attribute is defined it sets the patterns to -synchronized from the master to the slaves. It is exclusive -with Excluded_Patterns, that is it is an error to define -both. - -@item @b{Included_Artifact_Patterns}: list - -If this attribute is defined it sets the patterns of compilation -artifacts to synchronized from the slaves to the build master. -This attribute replace the default hard-coded patterns. - -@item @b{Excluded_Patterns}: list - -Set of patterns to ignore when synchronizing sources from the build -master to the slaves. A set of predefined patterns are supported -(e.g. *.o, *.ali, *.exe, etc.), this attributes make it possible to -add some more patterns. - -@item @b{Root_Dir}: single - -Value is the root directory used by the slave machines. - -@end itemize - -@node Package Stack Attributes -@subsubsection Package Stack Attributes - -@itemize @bullet - -@item @b{Switches}: list - -Value is the list of switches to be used when invoking @code{gnatstack}. - -@end itemize - -@node Package Synchronize Attributes -@subsubsection Package Synchronize Attributes - -@itemize @bullet - -@item @b{Default_Switches}: list, indexed, case-insensitive index - -Index is a language name. Value is a list of switches to be used when invoking -@code{gnatsync} for a source of the language, if there is no applicable -attribute Switches. - -@item @b{Switches}: list, optional index, indexed, case-insensitive index, - others allowed - -Index is a source file name. Value is the list of switches to be used when -invoking @code{gnatsync} for the source. - -@end itemize diff --git a/gcc/ada/s-exctra.adb b/gcc/ada/s-exctra.adb index 1a05cc1efd4..c19807a4bf4 100644 --- a/gcc/ada/s-exctra.adb +++ b/gcc/ada/s-exctra.adb @@ -6,7 +6,7 @@ -- -- -- B o d y -- -- -- --- Copyright (C) 2000-2014, AdaCore -- +-- Copyright (C) 2000-2015, AdaCore -- -- -- -- GNAT is free software; you can redistribute it and/or modify it under -- -- terms of the GNU General Public License as published by the Free Soft- -- @@ -69,8 +69,6 @@ package body System.Exception_Traces is (Traceback : System.Address; Len : Natural) return String is - -- Note: do not use an address clause, which is not supported under .NET - subtype Trace_Array is Traceback_Entries.Tracebacks_Array (1 .. Len); type Trace_Array_Access is access all Trace_Array; diff --git a/gcc/ada/s-multip.adb b/gcc/ada/s-multip.adb index 901cda0c654..239d5e0ee73 100644 --- a/gcc/ada/s-multip.adb +++ b/gcc/ada/s-multip.adb @@ -6,9 +6,9 @@ -- -- -- B o d y -- -- -- --- Copyright (C) 2010-2013, Free Software Foundation, Inc. -- +-- Copyright (C) 2010-2015, Free Software Foundation, Inc. -- -- -- --- GNARL is free software; you can redistribute it and/or modify it under -- +-- GNAT is free software; you can redistribute it and/or modify it under -- -- terms of the GNU General Public License as published by the Free Soft- -- -- ware Foundation; either version 3, or (at your option) any later ver- -- -- sion. GNAT is distributed in the hope that it will be useful, but WITH- -- diff --git a/gcc/ada/s-os_lib.ads b/gcc/ada/s-os_lib.ads index abffa531aa8..142937ea414 100644 --- a/gcc/ada/s-os_lib.ads +++ b/gcc/ada/s-os_lib.ads @@ -48,9 +48,6 @@ -- be used by other predefined packages. User access to this package is via -- a renaming of this package in GNAT.OS_Lib (file g-os_lib.ads). --- Note: a distinct body for this spec is included in the .NET runtime library --- and must be kept in sync with changes made in this file. - pragma Compiler_Unit_Warning; with System; diff --git a/gcc/ada/s-osinte-linux.ads b/gcc/ada/s-osinte-linux.ads index c71bebc8d8a..8dfbbe83044 100644 --- a/gcc/ada/s-osinte-linux.ads +++ b/gcc/ada/s-osinte-linux.ads @@ -7,7 +7,7 @@ -- S p e c -- -- -- -- Copyright (C) 1991-1994, Florida State University -- --- Copyright (C) 1995-2014, Free Software Foundation, Inc. -- +-- Copyright (C) 1995-2015, Free Software Foundation, Inc. -- -- -- -- GNAT is free software; you can redistribute it and/or modify it under -- -- terms of the GNU General Public License as published by the Free Soft- -- @@ -526,6 +526,10 @@ package System.OS_Interface is destructor : destructor_pointer) return int; pragma Import (C, pthread_key_create, "pthread_key_create"); + ---------------- + -- Extensions -- + ---------------- + CPU_SETSIZE : constant := 1_024; -- Size of the cpu_set_t mask on most linux systems (SUSE 11 uses 4_096). -- This is kept for backward compatibility (System.Task_Info uses it), but diff --git a/gcc/ada/s-solita.adb b/gcc/ada/s-solita.adb index a8f101d0fd8..d1ca2c474c7 100644 --- a/gcc/ada/s-solita.adb +++ b/gcc/ada/s-solita.adb @@ -6,7 +6,7 @@ -- -- -- B o d y -- -- -- --- Copyright (C) 2004-2014, Free Software Foundation, Inc. -- +-- Copyright (C) 2004-2015, Free Software Foundation, Inc. -- -- -- -- GNAT is free software; you can redistribute it and/or modify it under -- -- terms of the GNU General Public License as published by the Free Soft- -- @@ -159,8 +159,7 @@ package body System.Soft_Links.Tasking is -- We do not want to enable this check and e.g. call System.OS_Lib.Abort -- here because some restricted run-times may not have System.OS_Lib - -- (e.g. JVM), and calling abort may do more harm than good to the - -- main application. + -- and calling abort may do more harm than good to the main application. pragma Assert (Self_Id = STPO.Environment_Task); diff --git a/gcc/ada/sem_ch3.adb b/gcc/ada/sem_ch3.adb index fc85a5abfb8..8f979292e4b 100644 --- a/gcc/ada/sem_ch3.adb +++ b/gcc/ada/sem_ch3.adb @@ -10024,9 +10024,6 @@ package body Sem_Ch3 is -- operations used in dispatching selects since we always provide -- automatic overridings for these subprograms. - -- Also ignore this rule for convention CIL since .NET libraries - -- do bizarre things with interfaces??? - -- The partial view of T may have been a private extension, for -- which inherited functions dispatching on result are abstract. -- If the full view is a null extension, there is no need for diff --git a/gcc/ada/sinfo.ads b/gcc/ada/sinfo.ads index 968d87def2a..77d0a2dd95e 100644 --- a/gcc/ada/sinfo.ads +++ b/gcc/ada/sinfo.ads @@ -6539,7 +6539,7 @@ package Sinfo is -- For some back ends, such as gcc with ZCX, "at end" is implemented -- entirely in the back end. In this case, a handled sequence of -- statements with an "at end" cannot also have exception handlers. - -- For other back ends, such as gcc with SJLJ and .NET, the + -- For other back ends, such as gcc with front-end SJLJ, the -- implementation is split between the front end and back end; the front -- end implements 3, and the back end implements 1 and 2. In this case, -- if there is an "at end", the front end inserts the appropriate diff --git a/gcc/ada/types.ads b/gcc/ada/types.ads index dc37f152e76..7a19dee126e 100644 --- a/gcc/ada/types.ads +++ b/gcc/ada/types.ads @@ -844,10 +844,7 @@ package Types is -- Note on ordering of references. For the tables in Ada.Exceptions units, -- usually the ordering does not matter, and we use the same ordering as -- is used here (note the requirement in the ordering here that CE/PE/SE - -- codes be kept together, so the subtype declarations work OK). However, - -- there is an important exception, which is in a-except-2005.adb, where - -- ordering of the Rcheck routines must correspond to the ordering of the - -- Rmsg_xx messages. This is required by the .NET scripts. + -- codes be kept together, so the subtype declarations work OK). type RT_Exception_Code is (CE_Access_Check_Failed, -- 00 |