@set gprconfig GPRconfig
@c ------ projects.texi
-@c Copyright (C) 2002-2011, Free Software Foundation, Inc.
+@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
@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
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
@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 table
In order to include the elaboration code in the stand-alone library, the binder
cases to try and explain what you can use aggregate projects for.
@menu
-* Building all main units from a single project tree::
+* 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::
@end menu
@c -----------------------------------------------------------
-@node Building all main units from a single project tree
-@subsection Building all main units from a single project tree
+@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,
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 ---------------------------------------------------------
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
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 ---------------------------------------------
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
OSDN Git Service
