@set gprconfig GPRconfig
@c ------ projects.texi
+@c Copyright (C) 2002-2012, Free Software Foundation, Inc.
@c This file is shared between the GNAT user's guide and gprbuild. It is not
@c compilable on its own, you should instead compile the other two manuals.
@c For that reason, there is no toplevel @menu
* Library Projects::
* Project Extension::
* Aggregate Projects::
+* Aggregate Library Projects::
* Project File Reference::
@end menu
@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}).
+ 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}).
@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
+ 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.
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
+ 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}.
be several files with the same source file name sitting in different
directories of the project. In this case, only the file in the first directory
is considered as a source of the project and the others are hidden. If
-@code{"**"} is not used in the string list @code{Source_Dirs}, it is an error
+@code{"**"} is used in the string list @code{Source_Dirs}, it is an error
to have several files with the same source file name in the same directory
@code{"**"} subtree, since there would be an ambiguity as to which one should
-be used. However, two files with the same source file name may 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.
+be used. However, two files with the same source file name may exist in two
+single directories or directory subtrees. In this case, the one in the first
+directory or directory subtree is a source of the project.
@c ---------------------------------------------
@node Object and Exec Directory
@b{for} Object_Dir @b{use} "obj";
@b{for} Exec_Dir @b{use} ".";
@b{for} Main @b{use} ("proc.adb");
- @b{end} Build;
- @b{package} Builder @b{is} --<<< for gnatmake and gprbuild
- @b{end} Builder;
+ @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} Compiler @b{is} --<<< for the compiler
+ @b{end} Compiler;
- @b{package} Binder @b{is} --<<< for the binder
- @b{end} Binder;
+ @b{package} Binder @b{is} --<<< for the binder
+ @b{end} Binder;
- @b{package} Linker @b{is} --<<< for the linker
- @b{end} Linker;
+ @b{package} Linker @b{is} --<<< for the linker
+ @b{end} Linker;
+ @b{end} Build;
@end smallexample
@noindent
@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;
- however, there may be system specific restrictions on the name.
- In general, it is recommended to stick to alphanumeric characters
- (and possibly underscores) to help portability.
+ 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}
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, @b{Library_Interface}, in addition to the
-two attributes that make a project a Library Project (@code{Library_Name} and
-@code{Library_Dir}).
+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.
- Projects importing this library project may only "with" units whose sources
- are listed in the @code{Library_Interface}. Other sources are considered
- implementation units.
+ 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
+ for Library_Dir use "lib";
+ for Library_Name use "loggin";
+ for Library_Interface use ("lib1", "lib2"); -- 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 only depends 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.
@smallexample @c projectfile
@group
for Library_Dir use "lib";
for Library_Name use "loggin";
for Library_Interface use ("lib1", "lib2"); -- unit names
+ for Library_Standalone use "encapsulated";
@end group
@end smallexample
@end smallexample
@noindent
-An extending project retains all the switches specified in the
-extended project.
+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::
using standard projects. This section will go over a few of these use
cases to try and explain what you can use aggregate projects for.
-@subsection Building all main units from a single project tree
+@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
gprbuild -PA.gpr
@end smallexample
-this will only rebuild the main units of project A, not those of the
+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
gnatmake commands, one per project, to build all executables.
This is a little inconvenient, but more importantly is inefficient
gprbuild -PAgg.gpr
@end smallexample
-this will build all main units from A, B and C.
+this will build all mains from A, B and C.
@smallexample @c projectfile
aggregate project Agg is
end Agg;
@end smallexample
-If B or C do not define any main unit (through their Main
+If B or C do not define any main program (through their Main
attribute), all their sources are build. When you do not group them
in the aggregate project, only those sources that are needed by A
will be build.
-If you add a main unit to a project P not already explicitly referenced in the
+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 unit will not be built when
+files for the aggregate project, or the main will not be built when
building the aggregate project.
+@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 build independently from each other (but they can be build in
Aggregate projects can be used to build multiple partitions
@end smallexample
+@c ---------------------------------------------
+@node Define a build environment
@subsection Define a build environment
+@c ---------------------------------------------
The environment variables at the time you launch gprbuild or gprbuild
will influence the view these tools have of the project (PATH to find
end MyProject;
@end smallexample
+@c --------------------------------------------
+@node Performance improvements in builder
@subsection Performance improvements in builder
+@c --------------------------------------------
The loading of aggregate projects is optimized in gprbuild and
gnatmake, so that all files are searched for only once on the disk
be done while maximizing the use of CPUs (compared to launching
multiple gprbuild and 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
@itemize @bullet
@item Languages
-@item Source_files, Source_List_File and other attributes dealing with
+@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 Inherit_Source_Path
@item Excluded_Source_Dirs
@item Locally_Removed_Files
-@item Excluded_Source_Fies
+@item Excluded_Source_Files
@item Excluded_Source_List_File
@item Interfaces
@end itemize
within the tree.
Basically, the idea is to specify all those projects that have
-main units you want to build and link, or libraries you want to
+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
@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
project C is
package Compiler is
- for Default_Switches ("Ada") use ("-O3, "-gnatn");
+ for Default_Switches ("Ada") use ("-O3", "-gnatn");
for Switches ("c_file1.adb") use ("-O0", "-g");
end Compiler;
end C;
For projects that are build 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 units, and
+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 project Agg is
+ for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
+ for Library_Name use ("agg");
+ for Library_Dir use ("lagg");
+ 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} into 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 aggregates 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 project Agg is
+ for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
+ for Library_Name use ("agg");
+ for Library_Dir use ("lagg");
+ for Library_Kind use "relocatable";
+
+ package Builder is
+ for Global_Compilation_Switches ("Ada") use ("-fPIC");
+ end Builder;
+ 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.
+
+@c ---------------------------------------------
@node Project File Reference
@section Project File Reference
@c ---------------------------------------------
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}: for future extension
-@item @b{aggregate library}: for future extension
+@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.
* gnatmake and Project Files::
* The GNAT Driver and Project Files::
* The Development Environments::
-* Cleaning up with GPRclean::
@end menu
@c ---------------------------------------------
command line.
@smallexample
- gnatmake ^-P^/PROJECT_FILE=^prj main1 main2 main3
+ gnatmake ^-P^/PROJECT_FILE=^prj main1.adb main2.adb main3.adb
@end smallexample
@noindent
@smallexample @c projectfile
@group
project Prj is
- for Main use ("main1", "main2", "main3");
+ for Main use ("main1.adb", "main2.adb", "main3.adb");
end Prj;
@end group
@end smallexample
@noindent
With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"}
is equivalent to
-@code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1 main2 main3"}.
+@code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1.adb main2.adb main3.adb"}.
When the project attribute @code{Main} is not specified, or is specified
as an empty string list, or when the switch @option{-u} is used on the command
this value is not defined.
@end table
-
-@c ---------------------------------------------
-@node Cleaning up with GPRclean
-@section Cleaning up with GPRclean
-@c ---------------------------------------------
-
-@noindent
-The GPRclean tool removes the files created by GPRbuild.
-At a minimum, to invoke GPRclean you must specify a main project file
-in a command such as @code{gprclean proj.gpr} or @code{gprclean -P proj.gpr}.
-
-Examples of invocation of GPRclean:
-
-@smallexample
- gprclean -r prj1.gpr
- gprclean -c -P prj2.gpr
-@end smallexample
-
-@menu
-* Switches for GPRclean::
-@end menu
-
-@c ---------------------------------------------
-@node Switches for GPRclean
-@subsection Switches for GPRclean
-@c ---------------------------------------------
-
-@noindent
-The switches for GPRclean are:
-
-@itemize @bullet
-@item @option{--config=<main config project file name>} : Specify the
- configuration project file name
-
-@item @option{--autoconf=<config project file name>}
-
- This specifies a configuration project file name that already exists or will
- be created automatically. Option @option{--autoconf=}
- cannot be specified more than once. If the configuration project file
- specified with @option{--autoconf=} exists, then it is used. Otherwise,
- @value{gprconfig} is invoked to create it automatically.
-
-@item @option{-c} : Only delete compiler-generated files. Do not delete
- executables and libraries.
-
-@item @option{-f} : Force deletions of unwritable files
-
-@item @option{-F} : Display full project path name in brief error messages
-
-@item @option{-h} : Display this message
-
-@item @option{-n} : Do not delete files, only list files to delete
-
-@item @option{-P<proj>} : Use Project File @emph{<proj>}.
-
-@item @option{-q} : Be quiet/terse. There is no output, except to report
- problems.
-
-@item @option{-r} : (recursive) Clean all projects referenced by the main
- project directly or indirectly. Without this switch, GPRclean only
- cleans the main project.
-
-@item @option{-v} : Verbose mode
-
-@item @option{-vPx} : Specify verbosity when parsing Project Files.
- x = 0 (default), 1 or 2.
-
-@item @option{-Xnm=val} : Specify an external reference for Project Files.
-
-@end itemize
OSDN Git Service
