* Executable File Names::
* Avoid Duplication With Variables::
* Naming Schemes::
+* Installation::
+* Distributed support::
@end menu
@c ---------------------------------------------
It is often desirable to remove, from the source directories, directory
subtrees rooted at some subdirectories. An example is the subdirectories
created by a Version Control System such as Subversion that creates directory
- subtrees .svn/**. To do that, attribute @b{Ignore_Source_Sub_Dirs} can be
- used. It specifies the list of simple file names for the root of these
- undesirable directory subtrees.
+ 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
is explicitly specified.
@xref{Naming Schemes}.
-@item @code{Source Files}
- @cindex @code{Source_Files}
+@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.
@end ifset
@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{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}.
+@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{Build_Slaves}
+@cindex @code{Build_Slaves}
+
+A list of string referencing the remote build slaves to use for the
+compilation phase. The format is:
+@code{[protocol://]name.domain[:port]}.
+
+Where @code{protocol} is one of:
+
+@table @asis
+
+@item rsync
+@cindex @code{rsync}
+
+The sources are copied using the external @code{rsync} tool.
+
+@item file
+
+The sources are accessed via a shared directory or mount point.
+
+@end table
+
+The default port used to communicate with @command{gprslave} is
+@code{8484}.
+
+@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 ---------------------------------------------
@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 build from this project hierarchy. As we have seen before,
+ 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.
@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 build (the default is to build a
+ 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
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 which uses scenarios
- to indicate at the various kinds of library to be build and their
+ to indicate the various kinds of library to be built and their
corresponding object_dir.
@cindex @code{Library_ALI_Dir}
@c ---------------------------------------------
@noindent
-When using project files, library installation is part of the library build
-process. Thus no further action is needed in order to make use of the
-libraries that are built as part of the general application build. A usable
-version of the library is installed in the directory specified by the
-@code{Library_Dir} attribute of the library project file.
+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
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. A project to use this library is
+generated automatically by @command{gprinstall} which also copy, in the install
+location, the minimum set of sources needed to use the library.
+@ref{Installation}
+
@c ---------------------------------------------
@node Project Extension
@section Project Extension
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 build every night
+Suppose for instance that our example @code{Build} project is built every night
for the whole team, in some shared directory. A developer usually need 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
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 and explain what you can use aggregate projects for.
+cases to try to explain what you can use aggregate projects for.
@menu
* Building all main programs from a single project tree::
purposes for instance), or libraries (for easier reuse in various
contexts).
-However, if you build your project through gnatmake or gprbuild, using
-a syntax similar to
+However, if you build your project through @command{gnatmake} or
+@command{gprbuild}, using a syntax similar to
@smallexample
gprbuild -PA.gpr
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.
+@command{gnatmake} commands, one per project, to build all executables.
This is a little inconvenient, but more importantly is inefficient
-(since gnatmake needs to do duplicate work to ensure that sources are
+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).
+the -j switch.
-Also libraries are always rebuild when building a project.
+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
@end smallexample
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
+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 build.
+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
@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
+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 gprbuild, you could do
+Using only @command{gprbuild}, you could do
@smallexample
gprbuild -PA.gpr
gprbuild -PB.gpr
@end smallexample
-to build both. But again, gprbuild has to do some duplicate work for
+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.
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
+limitations and can aggregate two project trees that have common
sources.
-@smallexample
-Aggregate projects can group projects with duplicate file names
-@end smallexample
-
-This scenario is particularly useful in environment like VxWork 653
-where the applications running in the multiple partitions can be build
-in parallel through a single gprbuild command. This also works nicely
+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.
-@smallexample
- 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
-the compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the
+The environment variables at the time you launch @command{gprbuild} or
+@command{gnatmake} 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" statement,...). Several command line switches
can be used to override those (-X or -aP), but on some systems and
all systems often make it hard to read.
An aggregate project can be used to set the environment for all
-projects build through that aggregate. One of the nice aspects is that
+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
@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
+The loading of aggregate projects is optimized in @command{gprbuild} and
+@command{gnatmake}, 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, gprbuild and gnatmake compute how
-and where a source file should be compiled, and even if it is found
+servers). As part of the loading, @command{gprbuild} and @command{gnatmake}
+compute 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 gprbuild and gnatmake commands in parallel).
+multiple @command{gprbuild} and @command{gnatmake} commands in parallel).
@c -------------------------------------
@node Syntax of aggregate projects
Each aggregate project has its own (that is if agg1.gpr includes
agg2.gpr, they can potentially both have a different project path).
-This project path is defined as the concatenation, in that order, of
-the current directory, followed by the command line -aP switches,
-then the directories from the Project_Path attribute, then the
-directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH env.
-variables, and finally the predefined directories.
+
+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
users can override the value set in the (presumably shared
with others in his team) aggregate project.
-@item The -X command line switch to gprbuild and gnatmake
+@item The -X command line switch to @command{gprbuild} and @command{gnatmake}
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 gprbuild or
-natmake), and ignored in other aggregate projects. It is invalid
+project (i.e. the one specified on the command line to @command{gprbuild} or
+@command{gnatmake}), 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 build through the aggregate, which would not
+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
@item @b{Switches}:
@cindex @code{Switches}
This attribute gives the list of switches to use for the builder
-(gprbuild or gnatmake), depending on the language of the main file.
-For instance,
+(@command{gprbuild} or @command{gnatmake}), depending on the language of the
+main file. For instance,
@smallexample @c projectfile
for Switches ("Ada") use ("-d", "-p");
@end table
-For projects that are build through the aggregate, the package Builder
+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.
@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 @code{gprbuild}.
+ It describes compilers and other tools to @command{gprbuild}.
@end table
@c ---------------------------------------------
This package specifies the options used when starting an integrated
development environment, for instance @command{GPS} or @command{Gnatbench}.
@xref{The Development Environments}.
+@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}.
@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
-gnatmake or gprbuild command).
+@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.
@item ^--subdirs^/SUBDIRS^=<subdir>
@cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)
-This switch is recognized by gnatmake and gnatclean. It indicate that the real
-directories (except the source directories) are the subdirectories <subdir>
-of the directories specified in the project files. This applies in particular
-to object directories, library directories and exec directories. If the
-subdirectories do not exist, they are created automatically.
+This switch is recognized by @command{gnatmake} and @command{gnatclean}. It
+indicate that the real directories (except the source directories) are the
+subdirectories <subdir> of the directories specified in the project files.
+This applies in particular to object directories, library directories and
+exec directories. If the subdirectories do not exist, they are created
+automatically.
@end table
This is an associative array attribute, whose domain is a language name. Its
value is 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
-gnatmake, in particular in the handling of switches.
+@command{gnatmake}, in particular in the handling of switches.
@item Debugger_Command
This is simple attribute, Its value is a string that specifies the name of
projects / platform / upstream / gcc48.git / blobdiff