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,...).
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,
common directory is the only source directory.
There are several ways of defining source directories:
build.gpris placed in the
commondirectory, the project has the needed implicit source directory.
"/usr/local/common/"on UNIX), or relative to the directory in which the project file resides (for instance "." if
common/, or "common" if it is one level up). Each of the source directories must exist and be readable.
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 "\".
**", then that path and all its subdirectories (recursively) are included in the list of source directories. For instance,
./**represent the complete directory tree rooted at the directory in which the project file resides.
When using that construct, it can sometimes be convenient to also use the attribute `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.
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 `Ignore_Source_Sub_Dirs' can be used. It specifies the list of simple file names for the roots of these undesirable directory subtrees.
for Source_Dirs use ("./**"); for Ignore_Source_Sub_Dirs use (".svn");
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
build.gpr project Build is for Source_Dirs use ("common"); -- <<<< end Build;
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.
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.
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 `Languages' attribute to a list of strings, each of which is the name of a language.
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 (see Naming Schemes). The default is the
standard GNAT extension (
.adb for bodies and
specs), which is what is used in our example, explaining why no naming scheme
is explicitly specified.
See Naming Schemes.
A warning is issued if both attributes Source_Files and Source_List_File are given explicit values. In this case, the attribute Source_Files prevails.
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 Source_Dirs. The project manager automatically finds
proc.adb as source files of the
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.