]>
Commit | Line | Data |
---|---|---|
b2cacbfe AC |
1 | @set gprconfig GPRconfig |
2 | ||
8f443da5 | 3 | @c ------ projects.texi |
b8b2d982 | 4 | @c Copyright (C) 2002-2014, Free Software Foundation, Inc. |
8f443da5 AC |
5 | @c This file is shared between the GNAT user's guide and gprbuild. It is not |
6 | @c compilable on its own, you should instead compile the other two manuals. | |
7 | @c For that reason, there is no toplevel @menu | |
b2cacbfe AC |
8 | |
9 | @c --------------------------------------------- | |
10 | @node GNAT Project Manager | |
11 | @chapter GNAT Project Manager | |
12 | @c --------------------------------------------- | |
13 | ||
14 | @noindent | |
b2cacbfe AC |
15 | @menu |
16 | * Introduction:: | |
17 | * Building With Projects:: | |
18 | * Organizing Projects into Subsystems:: | |
19 | * Scenarios in Projects:: | |
20 | * Library Projects:: | |
21 | * Project Extension:: | |
2c1b72d7 | 22 | * Aggregate Projects:: |
5415acbd | 23 | * Aggregate Library Projects:: |
b2cacbfe AC |
24 | * Project File Reference:: |
25 | @end menu | |
26 | ||
27 | @c --------------------------------------------- | |
28 | @node Introduction | |
29 | @section Introduction | |
30 | @c --------------------------------------------- | |
31 | ||
32 | @noindent | |
33 | This chapter describes GNAT's @emph{Project Manager}, a facility that allows | |
34 | you to manage complex builds involving a number of source files, directories, | |
35 | and options for different system configurations. In particular, | |
36 | project files allow you to specify: | |
37 | ||
38 | @itemize @bullet | |
39 | @item The directory or set of directories containing the source files, and/or the | |
40 | names of the specific source files themselves | |
41 | @item The directory in which the compiler's output | |
42 | (@file{ALI} files, object files, tree files, etc.) is to be placed | |
43 | @item The directory in which the executable programs are to be placed | |
d77cfab2 | 44 | @item Switch settings for any of the project-enabled tools; |
b2cacbfe AC |
45 | you can apply these settings either globally or to individual compilation units. |
46 | @item The source files containing the main subprogram(s) to be built | |
47 | @item The source programming language(s) | |
48 | @item Source file naming conventions; you can specify these either globally or for | |
49 | individual compilation units (@pxref{Naming Schemes}). | |
50 | @item Change any of the above settings depending on external values, thus enabling | |
a0ad148f | 51 | the reuse of the projects in various @b{scenarios} (@pxref{Scenarios in Projects}). |
b2cacbfe AC |
52 | @item Automatically build libraries as part of the build process |
53 | (@pxref{Library Projects}). | |
54 | ||
55 | @end itemize | |
56 | ||
57 | @noindent | |
58 | Project files are written in a syntax close to that of Ada, using familiar | |
59 | notions such as packages, context clauses, declarations, default values, | |
60 | assignments, and inheritance (@pxref{Project File Reference}). | |
61 | ||
62 | Project files can be built hierarchically from other project files, simplifying | |
63 | complex system integration and project reuse (@pxref{Organizing Projects into | |
64 | Subsystems}). | |
65 | ||
66 | @itemize @bullet | |
67 | @item One project can import other projects containing needed source files. | |
68 | More generally, the Project Manager lets you structure large development | |
69 | efforts into hierarchical subsystems, where build decisions are delegated | |
70 | to the subsystem level, and thus different compilation environments | |
d77cfab2 | 71 | (switch settings) used for different subsystems. |
b2cacbfe AC |
72 | @item You can organize GNAT projects in a hierarchy: a child project |
73 | can extend a parent project, inheriting the parent's source files and | |
74 | optionally overriding any of them with alternative versions | |
75 | (@pxref{Project Extension}). | |
76 | ||
77 | @end itemize | |
78 | ||
79 | @noindent | |
80 | Several tools support project files, generally in addition to specifying | |
81 | the information on the command line itself). They share common switches | |
82 | to control the loading of the project (in particular | |
d77cfab2 AC |
83 | @option{-P@emph{projectfile}} and |
84 | @option{-X@emph{vbl}=@emph{value}}). | |
b2cacbfe AC |
85 | |
86 | The Project Manager supports a wide range of development strategies, | |
87 | for systems of all sizes. Here are some typical practices that are | |
88 | easily handled: | |
89 | ||
90 | @itemize @bullet | |
91 | @item Using a common set of source files and generating object files in different | |
d77cfab2 | 92 | directories via different switch settings. It can be used for instance, for |
b2cacbfe AC |
93 | generating separate sets of object files for debugging and for production. |
94 | @item Using a mostly-shared set of source files with different versions of | |
95 | some units or subunits. It can be used for instance, for grouping and hiding | |
4887624e | 96 | all OS dependencies in a small number of implementation units. |
b2cacbfe AC |
97 | @end itemize |
98 | ||
99 | @noindent | |
b2cacbfe AC |
100 | Project files can be used to achieve some of the effects of a source |
101 | versioning system (for example, defining separate projects for | |
102 | the different sets of sources that comprise different releases) but the | |
103 | Project Manager is independent of any source configuration management tool | |
104 | that might be used by the developers. | |
105 | ||
106 | The various sections below introduce the different concepts related to | |
107 | projects. Each section starts with examples and use cases, and then goes into | |
108 | the details of related project file capabilities. | |
109 | ||
110 | @c --------------------------------------------- | |
111 | @node Building With Projects | |
112 | @section Building With Projects | |
113 | @c --------------------------------------------- | |
114 | ||
115 | @noindent | |
116 | In its simplest form, a unique project is used to build a single executable. | |
117 | This section concentrates on such a simple setup. Later sections will extend | |
118 | this basic model to more complex setups. | |
119 | ||
120 | The following concepts are the foundation of project files, and will be further | |
121 | detailed later in this documentation. They are summarized here as a reference. | |
122 | ||
123 | @table @asis | |
124 | @item @b{Project file}: | |
125 | A text file using an Ada-like syntax, generally using the @file{.gpr} | |
126 | extension. It defines build-related characteristics of an application. | |
127 | The characteristics include the list of sources, the location of those | |
128 | sources, the location for the generated object files, the name of | |
129 | the main program, and the options for the various tools involved in the | |
130 | build process. | |
131 | ||
132 | @item @b{Project attribute}: | |
133 | A specific project characteristic is defined by an attribute clause. Its | |
134 | value is a string or a sequence of strings. All settings in a project | |
135 | are defined through a list of predefined attributes with precise | |
136 | semantics. @xref{Attributes}. | |
137 | ||
138 | @item @b{Package in a project}: | |
139 | Global attributes are defined at the top level of a project. | |
140 | Attributes affecting specific tools are grouped in a | |
141 | package whose name is related to tool's function. The most common | |
142 | packages are @code{Builder}, @code{Compiler}, @code{Binder}, | |
143 | and @code{Linker}. @xref{Packages}. | |
144 | ||
145 | @item @b{Project variables}: | |
146 | In addition to attributes, a project can use variables to store intermediate | |
e86a3a7e AC |
147 | values and avoid duplication in complex expressions. It can be initialized |
148 | with a value coming from the environment. | |
149 | A frequent use of variables is to define scenarios. | |
b2cacbfe AC |
150 | @xref{External Values}, @xref{Scenarios in Projects}, and @xref{Variables}. |
151 | ||
152 | @item @b{Source files} and @b{source directories}: | |
153 | A source file is associated with a language through a naming convention. For | |
154 | instance, @code{foo.c} is typically the name of a C source file; | |
155 | @code{bar.ads} or @code{bar.1.ada} are two common naming conventions for a | |
156 | file containing an Ada spec. A compilation unit is often composed of a main | |
157 | source file and potentially several auxiliary ones, such as header files in C. | |
158 | The naming conventions can be user defined @xref{Naming Schemes}, and will | |
159 | drive the builder to call the appropriate compiler for the given source file. | |
160 | Source files are searched for in the source directories associated with the | |
161 | project through the @b{Source_Dirs} attribute. By default, all the files (in | |
162 | these source directories) following the naming conventions associated with the | |
163 | declared languages are considered to be part of the project. It is also | |
164 | possible to limit the list of source files using the @b{Source_Files} or | |
165 | @b{Source_List_File} attributes. Note that those last two attributes only | |
166 | accept basenames with no directory information. | |
167 | ||
168 | @item @b{Object files} and @b{object directory}: | |
169 | An object file is an intermediate file produced by the compiler from a | |
170 | compilation unit. It is used by post-compilation tools to produce | |
171 | final executables or libraries. Object files produced in the context of | |
172 | a given project are stored in a single directory that can be specified by the | |
173 | @b{Object_Dir} attribute. In order to store objects in | |
174 | two or more object directories, the system must be split into | |
175 | distinct subsystems with their own project file. | |
176 | ||
177 | @end table | |
178 | ||
179 | The following subsections introduce gradually all the attributes of interest | |
180 | for simple build needs. Here is the simple setup that will be used in the | |
181 | following examples. | |
182 | ||
183 | The Ada source files @file{pack.ads}, @file{pack.adb}, and @file{proc.adb} are in | |
184 | the @file{common/} directory. The file @file{proc.adb} contains an Ada main | |
185 | subprogram @code{Proc} that @code{with}s package @code{Pack}. We want to compile | |
d77cfab2 AC |
186 | these source files with the switch |
187 | @option{-O2}, and put the resulting files in | |
b2cacbfe AC |
188 | the directory @file{obj/}. |
189 | ||
190 | @smallexample | |
191 | @group | |
d77cfab2 | 192 | common/ |
b2cacbfe AC |
193 | pack.ads |
194 | pack.adb | |
195 | proc.adb | |
196 | @end group | |
197 | @group | |
4887624e | 198 | common/obj/ |
b2cacbfe AC |
199 | proc.ali, proc.o pack.ali, pack.o |
200 | @end group | |
201 | @end smallexample | |
202 | ||
203 | @noindent | |
e86a3a7e AC |
204 | Our project is to be called @emph{Build}. The name of the |
205 | file is the name of the project (case-insensitive) with the | |
b2cacbfe AC |
206 | @file{.gpr} extension, therefore the project file name is @file{build.gpr}. This |
207 | is not mandatory, but a warning is issued when this convention is not followed. | |
208 | ||
209 | This is a very simple example, and as stated above, a single project | |
210 | file is enough for it. We will thus create a new file, that for now | |
211 | should contain the following code: | |
212 | ||
213 | @smallexample | |
214 | @b{project} Build @b{is} | |
215 | @b{end} Build; | |
216 | @end smallexample | |
217 | ||
218 | @menu | |
219 | * Source Files and Directories:: | |
e6425869 | 220 | * Duplicate Sources in Projects:: |
b2cacbfe AC |
221 | * Object and Exec Directory:: |
222 | * Main Subprograms:: | |
223 | * Tools Options in Project Files:: | |
224 | * Compiling with Project Files:: | |
225 | * Executable File Names:: | |
226 | * Avoid Duplication With Variables:: | |
227 | * Naming Schemes:: | |
df378148 | 228 | * Installation:: |
f3d42000 | 229 | * Distributed support:: |
b2cacbfe AC |
230 | @end menu |
231 | ||
232 | @c --------------------------------------------- | |
233 | @node Source Files and Directories | |
234 | @subsection Source Files and Directories | |
235 | @c --------------------------------------------- | |
236 | ||
237 | @noindent | |
238 | When you create a new project, the first thing to describe is how to find the | |
4887624e | 239 | corresponding source files. These are the only settings that are needed by all |
b2cacbfe AC |
240 | the tools that will use this project (builder, compiler, binder and linker for |
241 | the compilation, IDEs to edit the source files,@dots{}). | |
242 | ||
be5a1b93 | 243 | @cindex Source directories |
4887624e | 244 | The first step is to declare the source directories, which are the directories |
b2cacbfe AC |
245 | to be searched to find source files. In the case of the example, |
246 | the @file{common} directory is the only source directory. | |
247 | ||
be5a1b93 | 248 | @cindex @code{Source_Dirs} |
b2cacbfe AC |
249 | There are several ways of defining source directories: |
250 | ||
251 | @itemize @bullet | |
252 | @item When the attribute @b{Source_Dirs} is not used, a project contains a | |
e86a3a7e AC |
253 | single source directory which is the one where the project file itself |
254 | resides. In our example, if @file{build.gpr} is placed in the @file{common} | |
255 | directory, the project has the needed implicit source directory. | |
b2cacbfe AC |
256 | |
257 | @item The attribute @b{Source_Dirs} can be set to a list of path names, one | |
258 | for each of the source directories. Such paths can either be absolute | |
259 | names (for instance @file{"/usr/local/common/"} on UNIX), or relative to the | |
260 | directory in which the project file resides (for instance "." if | |
261 | @file{build.gpr} is inside @file{common/}, or "common" if it is one level up). | |
262 | Each of the source directories must exist and be readable. | |
263 | ||
f6da8aff | 264 | @cindex portability |
e86a3a7e AC |
265 | The syntax for directories is platform specific. For portability, however, |
266 | the project manager will always properly translate UNIX-like path names to | |
4887624e AC |
267 | the native format of the specific platform. For instance, when the same |
268 | project file is to be used both on Unix and Windows, "/" should be used as | |
269 | the directory separator rather than "\". | |
e86a3a7e AC |
270 | |
271 | @item The attribute @b{Source_Dirs} can automatically include subdirectories | |
4887624e AC |
272 | using a special syntax inspired by some UNIX shells. If any of the paths in |
273 | the list ends with "@file{**}", then that path and all its subdirectories | |
e86a3a7e | 274 | (recursively) are included in the list of source directories. For instance, |
4887624e AC |
275 | @file{**} and @file{./**} represent the complete directory tree rooted at |
276 | the directory in which the project file resides. | |
f6da8aff | 277 | @cindex Source directories, recursive |
b2cacbfe | 278 | |
f6da8aff | 279 | @cindex @code{Excluded_Source_Dirs} |
e86a3a7e AC |
280 | When using that construct, it can sometimes be convenient to also use the |
281 | attribute @b{Excluded_Source_Dirs}, which is also a list of paths. Each entry | |
282 | specifies a directory whose immediate content, not including subdirs, is to | |
283 | be excluded. It is also possible to exclude a complete directory subtree | |
9434c32e | 284 | using the "**" notation. |
b2cacbfe | 285 | |
468ee96a AC |
286 | @cindex @code{Ignore_Source_Sub_Dirs} |
287 | It is often desirable to remove, from the source directories, directory | |
288 | subtrees rooted at some subdirectories. An example is the subdirectories | |
289 | created by a Version Control System such as Subversion that creates directory | |
061bc17d AC |
290 | subtrees rooted at subdirectories ".svn". To do that, attribute |
291 | @b{Ignore_Source_Sub_Dirs} can be used. It specifies the list of simple | |
292 | file names for the roots of these undesirable directory subtrees. | |
293 | ||
294 | @smallexample | |
295 | @b{for} Source_Dirs @b{use} ("./**"); | |
296 | @b{for} Ignore_Source_Sub_Dirs @b{use} (".svn"); | |
297 | @end smallexample | |
468ee96a | 298 | |
b2cacbfe AC |
299 | @end itemize |
300 | ||
301 | @noindent | |
302 | When applied to the simple example, and because we generally prefer to have | |
303 | the project file at the toplevel directory rather than mixed with the sources, | |
304 | we will create the following file | |
305 | ||
306 | @smallexample | |
307 | build.gpr | |
308 | @b{project} Build @b{is} | |
309 | @b{for} Source_Dirs @b{use} ("common"); -- <<<< | |
310 | @b{end} Build; | |
311 | @end smallexample | |
312 | ||
313 | @noindent | |
314 | Once source directories have been specified, one may need to indicate | |
315 | source files of interest. By default, all source files present in the source | |
316 | directories are considered by the project manager. When this is not desired, | |
317 | it is possible to specify the list of sources to consider explicitly. | |
318 | In such a case, only source file base names are indicated and not | |
319 | their absolute or relative path names. The project manager is in charge of | |
320 | locating the specified source files in the specified source directories. | |
321 | ||
322 | @itemize @bullet | |
4887624e | 323 | @item By default, the project manager searches for all source files of all |
b2cacbfe AC |
324 | specified languages in all the source directories. |
325 | ||
326 | Since the project manager was initially developed for Ada environments, the | |
e86a3a7e AC |
327 | default language is usually Ada and the above project file is complete: it |
328 | defines without ambiguity the sources composing the project: that is to say, | |
329 | all the sources in subdirectory "common" for the default language (Ada) using | |
b2cacbfe AC |
330 | the default naming convention. |
331 | ||
f6da8aff | 332 | @cindex @code{Languages} |
b2cacbfe | 333 | However, when compiling a multi-language application, or a pure C |
e86a3a7e AC |
334 | application, the project manager must be told which languages are of |
335 | interest, which is done by setting the @b{Languages} attribute to a list of | |
336 | strings, each of which is the name of a language. Tools like | |
337 | @command{gnatmake} only know about Ada, while other tools like | |
338 | @command{gprbuild} know about many more languages such as C, C++, Fortran, | |
339 | assembly and others can be added dynamically. | |
b2cacbfe | 340 | |
f6da8aff | 341 | @cindex Naming scheme |
b2cacbfe AC |
342 | Even when using only Ada, the default naming might not be suitable. Indeed, |
343 | how does the project manager recognizes an "Ada file" from any other | |
e86a3a7e | 344 | file? Project files can describe the naming scheme used for source files, |
b2cacbfe AC |
345 | and override the default (@pxref{Naming Schemes}). The default is the |
346 | standard GNAT extension (@file{.adb} for bodies and @file{.ads} for | |
347 | specs), which is what is used in our example, explaining why no naming scheme | |
348 | is explicitly specified. | |
349 | @xref{Naming Schemes}. | |
350 | ||
50878404 AC |
351 | @item @code{Source_Files} |
352 | @cindex @code{Source_Files} | |
b2cacbfe AC |
353 | In some cases, source directories might contain files that should not be |
354 | included in a project. One can specify the explicit list of file names to | |
355 | be considered through the @b{Source_Files} attribute. | |
356 | When this attribute is defined, instead of looking at every file in the | |
357 | source directories, the project manager takes only those names into | |
358 | consideration reports errors if they cannot be found in the source | |
359 | directories or does not correspond to the naming scheme. | |
360 | ||
361 | @item For various reasons, it is sometimes useful to have a project with no | |
362 | sources (most of the time because the attributes defined in the project | |
a0ad148f JJ |
363 | file will be reused in other projects, as explained in |
364 | @pxref{Organizing Projects into Subsystems}. To do this, the attribute | |
b2cacbfe AC |
365 | @emph{Source_Files} is set to the empty list, i.e. @code{()}. Alternatively, |
366 | @emph{Source_Dirs} can be set to the empty list, with the same | |
367 | result. | |
368 | ||
f6da8aff RD |
369 | @item @code{Source_List_File} |
370 | @cindex @code{Source_List_File} | |
31b8a02d | 371 | If there is a great number of files, it might be more convenient to use |
b2cacbfe AC |
372 | the attribute @b{Source_List_File}, which specifies the full path of a file. |
373 | This file must contain a list of source file names (one per line, no | |
374 | directory information) that are searched as if they had been defined | |
375 | through @emph{Source_Files}. Such a file can easily be created through | |
376 | external tools. | |
377 | ||
378 | A warning is issued if both attributes @code{Source_Files} and | |
e86a3a7e AC |
379 | @code{Source_List_File} are given explicit values. In this case, the |
380 | attribute @code{Source_Files} prevails. | |
b2cacbfe | 381 | |
f6da8aff RD |
382 | @item @code{Excluded_Source_Files} |
383 | @cindex @code{Excluded_Source_Files} | |
384 | @cindex @code{Locally_Removed_Files} | |
385 | @cindex @code{Excluded_Source_List_File} | |
b2cacbfe AC |
386 | Specifying an explicit list of files is not always convenient.It might be |
387 | more convenient to use the default search rules with specific exceptions. | |
388 | This can be done thanks to the attribute @b{Excluded_Source_Files} | |
389 | (or its synonym @b{Locally_Removed_Files}). | |
390 | Its value is the list of file names that should not be taken into account. | |
a0ad148f JJ |
391 | This attribute is often used when extending a project, |
392 | @xref{Project Extension}. A similar attribute | |
393 | @b{Excluded_Source_List_File} plays the same | |
e86a3a7e | 394 | role but takes the name of file containing file names similarly to |
b2cacbfe AC |
395 | @code{Source_List_File}. |
396 | ||
397 | @end itemize | |
398 | ||
399 | @noindent | |
400 | In most simple cases, such as the above example, the default source file search | |
401 | behavior provides the expected result, and we do not need to add anything after | |
402 | setting @code{Source_Dirs}. The project manager automatically finds | |
403 | @file{pack.ads}, @file{pack.adb} and @file{proc.adb} as source files of the | |
404 | project. | |
405 | ||
e6425869 AC |
406 | Note that by default a warning is issued when a project has no sources attached |
407 | to it and this is not explicitly indicated in the project file. | |
b2cacbfe | 408 | |
e6425869 AC |
409 | @c --------------------------------------------- |
410 | @node Duplicate Sources in Projects | |
411 | @subsection Duplicate Sources in Projects | |
412 | @c --------------------------------------------- | |
413 | ||
414 | @noindent | |
b2cacbfe | 415 | If the order of the source directories is known statically, that is if |
e6425869 | 416 | @code{"/**"} is not used in the string list @code{Source_Dirs}, then there may |
4887624e AC |
417 | be several files with the same name sitting in different directories of the |
418 | project. In this case, only the file in the first directory is considered as a | |
419 | source of the project and the others are hidden. If @code{"/**"} is used in the | |
420 | string list @code{Source_Dirs}, it is an error to have several files with the | |
421 | same name in the same directory @code{"/**"} subtree, since there would be an | |
422 | ambiguity as to which one should be used. However, two files with the same name | |
423 | may exist in two single directories or directory subtrees. In this case, the | |
424 | one in the first directory or directory subtree is a source of the project. | |
b2cacbfe | 425 | |
e6425869 AC |
426 | If there are two sources in different directories of the same @code{"/**"} |
427 | subtree, one way to resolve the problem is to exclude the directory of the | |
428 | file that should not be used as a source of the project. | |
429 | ||
b2cacbfe AC |
430 | @c --------------------------------------------- |
431 | @node Object and Exec Directory | |
432 | @subsection Object and Exec Directory | |
433 | @c --------------------------------------------- | |
434 | ||
435 | @noindent | |
436 | The next step when writing a project is to indicate where the compiler should | |
e86a3a7e AC |
437 | put the object files. In fact, the compiler and other tools might create |
438 | several different kind of files (for GNAT, there is the object file and the ALI | |
439 | file for instance). One of the important concepts in projects is that most | |
440 | tools may consider source directories as read-only and do not attempt to create | |
441 | new or temporary files there. Instead, all files are created in the object | |
442 | directory. It is of course not true for project-aware IDEs, whose purpose it is | |
443 | to create the source files. | |
b2cacbfe | 444 | |
be5a1b93 | 445 | @cindex @code{Object_Dir} |
b2cacbfe AC |
446 | The object directory is specified through the @b{Object_Dir} attribute. |
447 | Its value is the path to the object directory, either absolute or | |
448 | relative to the directory containing the project file. This | |
449 | directory must already exist and be readable and writable, although | |
450 | some tools have a switch to create the directory if needed (See | |
d77cfab2 | 451 | the switch @code{-p} for @command{gnatmake} |
455f3336 | 452 | and @command{gprbuild}). |
b2cacbfe AC |
453 | |
454 | If the attribute @code{Object_Dir} is not specified, it defaults to | |
e86a3a7e | 455 | the project directory, that is the directory containing the project file. |
b2cacbfe AC |
456 | |
457 | For our example, we can specify the object dir in this way: | |
458 | ||
459 | @smallexample | |
460 | @b{project} Build @b{is} | |
461 | @b{for} Source_Dirs @b{use} ("common"); | |
462 | @b{for} Object_Dir @b{use} "obj"; -- <<<< | |
463 | @b{end} Build; | |
464 | @end smallexample | |
465 | ||
466 | @noindent | |
e86a3a7e | 467 | As mentioned earlier, there is a single object directory per project. As a |
4887624e | 468 | result, if you have an existing system where the object files are spread across |
e86a3a7e AC |
469 | several directories, you can either move all of them into the same directory if |
470 | you want to build it with a single project file, or study the section on | |
471 | subsystems (@pxref{Organizing Projects into Subsystems}) to see how each | |
4887624e | 472 | separate object directory can be associated with one of the subsystems |
e86a3a7e | 473 | constituting the application. |
b2cacbfe AC |
474 | |
475 | When the @command{linker} is called, it usually creates an executable. By | |
476 | default, this executable is placed in the object directory of the project. It | |
477 | might be convenient to store it in its own directory. | |
478 | ||
be5a1b93 | 479 | @cindex @code{Exec_Dir} |
b2cacbfe AC |
480 | This can be done through the @code{Exec_Dir} attribute, which, like |
481 | @emph{Object_Dir} contains a single absolute or relative path and must point to | |
e86a3a7e AC |
482 | an existing and writable directory, unless you ask the tool to create it on |
483 | your behalf. When not specified, It defaults to the object directory and | |
484 | therefore to the project file's directory if neither @emph{Object_Dir} nor | |
485 | @emph{Exec_Dir} was specified. | |
b2cacbfe AC |
486 | |
487 | In the case of the example, let's place the executable in the root | |
488 | of the hierarchy, ie the same directory as @file{build.gpr}. Hence | |
489 | the project file is now | |
490 | ||
491 | @smallexample | |
492 | @b{project} Build @b{is} | |
493 | @b{for} Source_Dirs @b{use} ("common"); | |
494 | @b{for} Object_Dir @b{use} "obj"; | |
495 | @b{for} Exec_Dir @b{use} "."; -- <<<< | |
496 | @b{end} Build; | |
497 | @end smallexample | |
498 | ||
499 | @c --------------------------------------------- | |
500 | @node Main Subprograms | |
501 | @subsection Main Subprograms | |
502 | @c --------------------------------------------- | |
503 | ||
504 | @noindent | |
505 | In the previous section, executables were mentioned. The project manager needs | |
506 | to be taught what they are. In a project file, an executable is indicated by | |
4887624e | 507 | pointing to the source file of a main subprogram. In C this is the file that |
b2cacbfe AC |
508 | contains the @code{main} function, and in Ada the file that contains the main |
509 | unit. | |
510 | ||
511 | There can be any number of such main files within a given project, and thus | |
512 | several executables can be built in the context of a single project file. Of | |
31b8a02d | 513 | course, one given executable might not (and in fact will not) need all the |
b2cacbfe AC |
514 | source files referenced by the project. As opposed to other build environments |
515 | such as @command{makefile}, one does not need to specify the list of | |
4887624e AC |
516 | dependencies of each executable, the project-aware builder knows enough of the |
517 | semantics of the languages to build and link only the necessary elements. | |
b2cacbfe | 518 | |
be5a1b93 | 519 | @cindex @code{Main} |
b2cacbfe AC |
520 | The list of main files is specified via the @b{Main} attribute. It contains |
521 | a list of file names (no directories). If a project defines this | |
522 | attribute, it is not necessary to identify main files on the | |
523 | command line when invoking a builder, and editors like | |
524 | @command{GPS} will be able to create extra menus to spawn or debug the | |
525 | corresponding executables. | |
526 | ||
527 | @smallexample | |
528 | @b{project} Build @b{is} | |
529 | @b{for} Source_Dirs @b{use} ("common"); | |
530 | @b{for} Object_Dir @b{use} "obj"; | |
531 | @b{for} Exec_Dir @b{use} "."; | |
532 | @b{for} Main @b{use} ("proc.adb"); -- <<<< | |
533 | @b{end} Build; | |
534 | @end smallexample | |
535 | ||
536 | @noindent | |
537 | If this attribute is defined in the project, then spawning the builder | |
538 | with a command such as | |
539 | ||
540 | @smallexample | |
4887624e | 541 | gprbuild -Pbuild |
b2cacbfe AC |
542 | @end smallexample |
543 | ||
544 | @noindent | |
545 | automatically builds all the executables corresponding to the files | |
546 | listed in the @emph{Main} attribute. It is possible to specify one | |
547 | or more executables on the command line to build a subset of them. | |
548 | ||
b2cacbfe AC |
549 | @c --------------------------------------------- |
550 | @node Tools Options in Project Files | |
551 | @subsection Tools Options in Project Files | |
552 | @c --------------------------------------------- | |
553 | ||
554 | @noindent | |
e86a3a7e | 555 | We now have a project file that fully describes our environment, and can be |
4887624e | 556 | used to build the application with a simple @command{gprbuild} command as seen |
e86a3a7e | 557 | in the previous section. In fact, the empty project we showed immediately at |
308e6f3a | 558 | the beginning (with no attribute at all) could already fulfill that need if it |
e86a3a7e | 559 | was put in the @file{common} directory. |
b2cacbfe | 560 | |
4887624e AC |
561 | Of course, we might want more control. This section shows you how to specify |
562 | the compilation switches that the various tools involved in the building of the | |
563 | executable should use. | |
b2cacbfe | 564 | |
be5a1b93 | 565 | @cindex command line length |
4887624e | 566 | Since source names and locations are described in the project file, it is not |
e86a3a7e AC |
567 | necessary to use switches on the command line for this purpose (switches such |
568 | as -I for gcc). This removes a major source of command line length overflow. | |
b2cacbfe AC |
569 | Clearly, the builders will have to communicate this information one way or |
570 | another to the underlying compilers and tools they call but they usually use | |
4887624e | 571 | response files for this and thus are not subject to command line overflows. |
b2cacbfe | 572 | |
4887624e | 573 | Several tools participate to the creation of an executable: the compiler |
e86a3a7e | 574 | produces object files from the source files; the binder (in the Ada case) |
4887624e AC |
575 | creates a "source" file that takes care, among other things, of elaboration |
576 | issues and global variable initialization; and the linker gathers everything | |
577 | into a single executable that users can execute. All these tools are known to | |
b2cacbfe AC |
578 | the project manager and will be called with user defined switches from the |
579 | project files. However, we need to introduce a new project file concept to | |
4887624e | 580 | express the switches to be used for any of the tools involved in the build. |
b2cacbfe | 581 | |
be5a1b93 | 582 | @cindex project file packages |
b2cacbfe AC |
583 | A project file is subdivided into zero or more @b{packages}, each of which |
584 | contains the attributes specific to one tool (or one set of tools). Project | |
585 | files use an Ada-like syntax for packages. Package names permitted in project | |
e86a3a7e AC |
586 | files are restricted to a predefined set (@pxref{Packages}), and the contents |
587 | of packages are limited to a small set of constructs and attributes | |
b2cacbfe AC |
588 | (@pxref{Attributes}). |
589 | ||
e86a3a7e AC |
590 | Our example project file can be extended with the following empty packages. At |
591 | this stage, they could all be omitted since they are empty, but they show which | |
592 | packages would be involved in the build process. | |
b2cacbfe AC |
593 | |
594 | @smallexample | |
595 | @b{project} Build @b{is} | |
596 | @b{for} Source_Dirs @b{use} ("common"); | |
597 | @b{for} Object_Dir @b{use} "obj"; | |
598 | @b{for} Exec_Dir @b{use} "."; | |
599 | @b{for} Main @b{use} ("proc.adb"); | |
b2cacbfe | 600 | |
af89615f AC |
601 | @b{package} Builder @b{is} --<<< for gnatmake and gprbuild |
602 | @b{end} Builder; | |
b2cacbfe | 603 | |
af89615f AC |
604 | @b{package} Compiler @b{is} --<<< for the compiler |
605 | @b{end} Compiler; | |
b2cacbfe | 606 | |
af89615f AC |
607 | @b{package} Binder @b{is} --<<< for the binder |
608 | @b{end} Binder; | |
b2cacbfe | 609 | |
af89615f AC |
610 | @b{package} Linker @b{is} --<<< for the linker |
611 | @b{end} Linker; | |
612 | @b{end} Build; | |
b2cacbfe AC |
613 | @end smallexample |
614 | ||
615 | @noindent | |
616 | Let's first examine the compiler switches. As stated in the initial description | |
d77cfab2 | 617 | of the example, we want to compile all files with @option{-O2}. This is a |
b2cacbfe AC |
618 | compiler switch, although it is usual, on the command line, to pass it to the |
619 | builder which then passes it to the compiler. It is recommended to use directly | |
620 | the right package, which will make the setup easier to understand for other | |
621 | people. | |
622 | ||
d77cfab2 | 623 | Several attributes can be used to specify the switches: |
b2cacbfe AC |
624 | |
625 | @table @asis | |
626 | @item @b{Default_Switches}: | |
f6da8aff | 627 | @cindex @code{Default_Switches} |
b2cacbfe AC |
628 | This is the first mention in this manual of an @b{indexed attribute}. When |
629 | this attribute is defined, one must supply an @emph{index} in the form of a | |
630 | literal string. | |
631 | In the case of @emph{Default_Switches}, the index is the name of the | |
632 | language to which the switches apply (since a different compiler will | |
633 | likely be used for each language, and each compiler has its own set of | |
634 | switches). The value of the attribute is a list of switches. | |
635 | ||
d77cfab2 AC |
636 | In this example, we want to compile all Ada source files with the switch |
637 | @option{-O2}, and the resulting project file is as follows | |
b2cacbfe AC |
638 | (only the @code{Compiler} package is shown): |
639 | ||
640 | @smallexample | |
641 | @b{package} Compiler @b{is} | |
d77cfab2 | 642 | @b{for} Default_Switches ("Ada") @b{use} ("-O2"); |
b2cacbfe AC |
643 | @b{end} Compiler; |
644 | @end smallexample | |
645 | ||
d77cfab2 AC |
646 | @item @b{Switches}: |
647 | @cindex @code{Switches} | |
648 | in some cases, we might want to use specific switches | |
b2cacbfe AC |
649 | for one or more files. For instance, compiling @file{proc.adb} might not be |
650 | possible at high level of optimization because of a compiler issue. | |
d77cfab2 | 651 | In such a case, the @emph{Switches} |
b2cacbfe AC |
652 | attribute (indexed on the file name) can be used and will override the |
653 | switches defined by @emph{Default_Switches}. Our project file would | |
654 | become: | |
655 | ||
656 | @smallexample | |
455f3336 AC |
657 | package Compiler is |
658 | for Default_Switches ("Ada") | |
d77cfab2 AC |
659 | use ("-O2"); |
660 | for Switches ("proc.adb") | |
661 | use ("-O0"); | |
455f3336 | 662 | end Compiler; |
b2cacbfe AC |
663 | @end smallexample |
664 | ||
96d2756f | 665 | @noindent |
d77cfab2 | 666 | @code{Switches} may take a pattern as an index, such as in: |
96d2756f AC |
667 | |
668 | @smallexample | |
455f3336 AC |
669 | package Compiler is |
670 | for Default_Switches ("Ada") | |
d77cfab2 AC |
671 | use ("-O2"); |
672 | for Switches ("pkg*") | |
673 | use ("-O0"); | |
455f3336 | 674 | end Compiler; |
96d2756f AC |
675 | @end smallexample |
676 | ||
677 | @noindent | |
d77cfab2 AC |
678 | Sources @file{pkg.adb} and @file{pkg-child.adb} would be compiled with -O0, |
679 | not -O2. | |
96d2756f | 680 | |
b2cacbfe | 681 | @noindent |
d77cfab2 | 682 | @code{Switches} can also be given a language name as index instead of a file |
e86a3a7e | 683 | name in which case it has the same semantics as @emph{Default_Switches}. |
96d2756f | 684 | However, indexes with wild cards are never valid for language name. |
b2cacbfe | 685 | |
31b8a02d | 686 | @item @b{Local_Configuration_Pragmas}: |
f6da8aff | 687 | @cindex @code{Local_Configuration_Pragmas} |
b2cacbfe AC |
688 | this attribute may specify the path |
689 | of a file containing configuration pragmas for use by the Ada compiler, | |
690 | such as @code{pragma Restrictions (No_Tasking)}. These pragmas will be | |
691 | used for all the sources of the project. | |
692 | ||
693 | @end table | |
694 | ||
695 | The switches for the other tools are defined in a similar manner through the | |
d77cfab2 | 696 | @b{Default_Switches} and @b{Switches} attributes, respectively in the |
b2cacbfe | 697 | @emph{Builder} package (for @command{gnatmake} and @command{gprbuild}), |
e86a3a7e | 698 | the @emph{Binder} package (binding Ada executables) and the @emph{Linker} |
31b8a02d | 699 | package (for linking executables). |
b2cacbfe AC |
700 | |
701 | @c --------------------------------------------- | |
702 | @node Compiling with Project Files | |
703 | @subsection Compiling with Project Files | |
704 | @c --------------------------------------------- | |
705 | ||
706 | @noindent | |
707 | Now that our project files are written, let's build our executable. | |
708 | Here is the command we would use from the command line: | |
709 | ||
710 | @smallexample | |
d77cfab2 | 711 | gnatmake -Pbuild |
b2cacbfe AC |
712 | @end smallexample |
713 | ||
714 | @noindent | |
715 | This will automatically build the executables specified through the | |
716 | @emph{Main} attribute: for each, it will compile or recompile the | |
717 | sources for which the object file does not exist or is not up-to-date; it | |
718 | will then run the binder; and finally run the linker to create the | |
719 | executable itself. | |
720 | ||
721 | @command{gnatmake} only knows how to handle Ada files. By using | |
722 | @command{gprbuild} as a builder, you could automatically manage C files the | |
723 | same way: create the file @file{utils.c} in the @file{common} directory, | |
724 | set the attribute @emph{Languages} to @code{"(Ada, C)"}, and run | |
725 | ||
726 | @smallexample | |
d77cfab2 | 727 | gprbuild -Pbuild |
b2cacbfe AC |
728 | @end smallexample |
729 | ||
730 | @noindent | |
731 | Gprbuild knows how to recompile the C files and will | |
732 | recompile them only if one of their dependencies has changed. No direct | |
733 | indication on how to build the various elements is given in the | |
734 | project file, which describes the project properties rather than a | |
735 | set of actions to be executed. Here is the invocation of | |
736 | @command{gprbuild} when building a multi-language program: | |
737 | ||
738 | @smallexample | |
739 | $ gprbuild -Pbuild | |
31b8a02d AC |
740 | gcc -c proc.adb |
741 | gcc -c pack.adb | |
742 | gcc -c utils.c | |
b2cacbfe AC |
743 | gprbind proc |
744 | ... | |
31b8a02d | 745 | gcc proc.o -o proc |
b2cacbfe AC |
746 | @end smallexample |
747 | ||
748 | @noindent | |
749 | Notice the three steps described earlier: | |
750 | ||
751 | @itemize @bullet | |
752 | @item The first three gcc commands correspond to the compilation phase. | |
753 | @item The gprbind command corresponds to the post-compilation phase. | |
754 | @item The last gcc command corresponds to the final link. | |
755 | ||
756 | @end itemize | |
757 | ||
758 | @noindent | |
be5a1b93 | 759 | @cindex @option{-v} option (for GPRbuild) |
31b8a02d AC |
760 | The default output of GPRbuild's execution is kept reasonably simple and easy |
761 | to understand. In particular, some of the less frequently used commands are not | |
b2cacbfe | 762 | shown, and some parameters are abbreviated. So it is not possible to rerun the |
1d801f21 AC |
763 | effect of the @command{gprbuild} command by cut-and-pasting its output. |
764 | GPRbuild's option @code{-v} provides a much more verbose output which includes, | |
765 | among other information, more complete compilation, post-compilation and link | |
766 | commands. | |
b2cacbfe AC |
767 | |
768 | @c --------------------------------------------- | |
769 | @node Executable File Names | |
770 | @subsection Executable File Names | |
771 | @c --------------------------------------------- | |
772 | ||
773 | @noindent | |
be5a1b93 | 774 | @cindex @code{Executable} |
b2cacbfe AC |
775 | By default, the executable name corresponding to a main file is |
776 | computed from the main source file name. Through the attribute | |
777 | @b{Builder.Executable}, it is possible to change this default. | |
778 | ||
779 | For instance, instead of building @command{proc} (or @command{proc.exe} | |
780 | on Windows), we could configure our project file to build "proc1" | |
781 | (resp proc1.exe) with the following addition: | |
782 | ||
783 | @smallexample @c projectfile | |
d77cfab2 AC |
784 | @b{project} Build @b{is} |
785 | ... --@i{ same as before} | |
786 | @b{package} Builder @b{is} | |
787 | @b{for} Executable ("proc.adb") @b{use} "proc1"; | |
788 | @b{end} Builder | |
789 | @b{end} Build; | |
b2cacbfe AC |
790 | @end smallexample |
791 | ||
792 | @noindent | |
be5a1b93 | 793 | @cindex @code{Executable_Suffix} |
b2cacbfe AC |
794 | Attribute @b{Executable_Suffix}, when specified, may change the suffix |
795 | of the executable files, when no attribute @code{Executable} applies: | |
4887624e | 796 | its value replaces the platform-specific executable suffix. |
e86a3a7e | 797 | The default executable suffix is empty on UNIX and ".exe" on Windows. |
b2cacbfe AC |
798 | |
799 | It is also possible to change the name of the produced executable by using the | |
31b8a02d | 800 | command line switch @option{-o}. When several mains are defined in the project, |
b2cacbfe AC |
801 | it is not possible to use the @option{-o} switch and the only way to change the |
802 | names of the executable is provided by Attributes @code{Executable} and | |
803 | @code{Executable_Suffix}. | |
804 | ||
805 | @c --------------------------------------------- | |
806 | @node Avoid Duplication With Variables | |
807 | @subsection Avoid Duplication With Variables | |
808 | @c --------------------------------------------- | |
809 | ||
810 | @noindent | |
811 | To illustrate some other project capabilities, here is a slightly more complex | |
812 | project using similar sources and a main program in C: | |
813 | ||
814 | @smallexample @c projectfile | |
d77cfab2 AC |
815 | @b{project} C_Main @b{is} |
816 | @b{for} Languages @b{use} ("Ada", "C"); | |
817 | @b{for} Source_Dirs @b{use} ("common"); | |
818 | @b{for} Object_Dir @b{use} "obj"; | |
819 | @b{for} Main @b{use} ("main.c"); | |
820 | @b{package} Compiler @b{is} | |
b2cacbfe | 821 | C_Switches := ("-pedantic"); |
d77cfab2 AC |
822 | @b{for} Default_Switches ("C") @b{use} C_Switches; |
823 | @b{for} Default_Switches ("Ada") @b{use} ("-gnaty"); | |
824 | @b{for} Switches ("main.c") @b{use} C_Switches & ("-g"); | |
825 | @b{end} Compiler; | |
826 | @b{end} C_Main; | |
b2cacbfe AC |
827 | @end smallexample |
828 | ||
829 | @noindent | |
830 | This project has many similarities with the previous one. | |
831 | As expected, its @code{Main} attribute now refers to a C source. | |
832 | The attribute @emph{Exec_Dir} is now omitted, thus the resulting | |
833 | executable will be put in the directory @file{obj}. | |
834 | ||
835 | The most noticeable difference is the use of a variable in the | |
836 | @emph{Compiler} package to store settings used in several attributes. | |
837 | This avoids text duplication, and eases maintenance (a single place to | |
838 | modify if we want to add new switches for C files). We will revisit | |
839 | the use of variables in the context of scenarios (@pxref{Scenarios in | |
840 | Projects}). | |
841 | ||
842 | In this example, we see how the file @file{main.c} can be compiled with | |
843 | the switches used for all the other C files, plus @option{-g}. | |
844 | In this specific situation the use of a variable could have been | |
845 | replaced by a reference to the @code{Default_Switches} attribute: | |
846 | ||
847 | @smallexample @c projectfile | |
d77cfab2 | 848 | @b{for} Switches ("c_main.c") @b{use} Compiler'Default_Switches ("C") & ("-g"); |
b2cacbfe AC |
849 | @end smallexample |
850 | ||
851 | @noindent | |
852 | Note the tick (@emph{'}) used to refer to attributes defined in a package. | |
853 | ||
854 | Here is the output of the GPRbuild command using this project: | |
855 | ||
856 | @smallexample | |
857 | $gprbuild -Pc_main | |
31b8a02d AC |
858 | gcc -c -pedantic -g main.c |
859 | gcc -c -gnaty proc.adb | |
860 | gcc -c -gnaty pack.adb | |
861 | gcc -c -pedantic utils.c | |
862 | gprbind main.bexch | |
b2cacbfe | 863 | ... |
31b8a02d | 864 | gcc main.o -o main |
b2cacbfe AC |
865 | @end smallexample |
866 | ||
867 | @noindent | |
868 | The default switches for Ada sources, | |
869 | the default switches for C sources (in the compilation of @file{lib.c}), | |
e86a3a7e | 870 | and the specific switches for @file{main.c} have all been taken into |
b2cacbfe AC |
871 | account. |
872 | ||
873 | @c --------------------------------------------- | |
874 | @node Naming Schemes | |
875 | @subsection Naming Schemes | |
876 | @c --------------------------------------------- | |
877 | ||
878 | @noindent | |
879 | Sometimes an Ada software system is ported from one compilation environment to | |
880 | another (say GNAT), and the file are not named using the default GNAT | |
881 | conventions. Instead of changing all the file names, which for a variety of | |
e86a3a7e AC |
882 | reasons might not be possible, you can define the relevant file naming scheme |
883 | in the @b{Naming} package of your project file. | |
b2cacbfe AC |
884 | |
885 | The naming scheme has two distinct goals for the project manager: it | |
886 | allows finding of source files when searching in the source | |
887 | directories, and given a source file name it makes it possible to guess | |
888 | the associated language, and thus the compiler to use. | |
889 | ||
31b8a02d AC |
890 | Note that the use by the Ada compiler of pragmas Source_File_Name is not |
891 | supported when using project files. You must use the features described in this | |
b671e31b | 892 | paragraph. You can however specify other configuration pragmas. |
b2cacbfe AC |
893 | |
894 | The following attributes can be defined in package @code{Naming}: | |
895 | ||
896 | @table @asis | |
897 | @item @b{Casing}: | |
f6da8aff | 898 | @cindex @code{Casing} |
b2cacbfe AC |
899 | Its value must be one of @code{"lowercase"} (the default if |
900 | unspecified), @code{"uppercase"} or @code{"mixedcase"}. It describes the | |
901 | casing of file names with regards to the Ada unit name. Given an Ada unit | |
902 | My_Unit, the file name will respectively be @file{my_unit.adb} (lowercase), | |
903 | @file{MY_UNIT.ADB} (uppercase) or @file{My_Unit.adb} (mixedcase). | |
904 | On Windows, file names are case insensitive, so this attribute is | |
905 | irrelevant. | |
906 | ||
907 | @item @b{Dot_Replacement}: | |
f6da8aff | 908 | @cindex @code{Dot_Replacement} |
b2cacbfe AC |
909 | This attribute specifies the string that should replace the "." in unit |
910 | names. Its default value is @code{"-"} so that a unit | |
e86a3a7e AC |
911 | @code{Parent.Child} is expected to be found in the file |
912 | @file{parent-child.adb}. The replacement string must satisfy the following | |
913 | requirements to avoid ambiguities in the naming scheme: | |
b2cacbfe AC |
914 | |
915 | @itemize - | |
916 | @item It must not be empty | |
917 | @item It cannot start or end with an alphanumeric character | |
918 | @item It cannot be a single underscore | |
919 | @item It cannot start with an underscore followed by an alphanumeric | |
920 | @item It cannot contain a dot @code{'.'} except if the entire string | |
921 | is @code{"."} | |
922 | ||
923 | @end itemize | |
924 | ||
925 | @item @b{Spec_Suffix} and @b{Specification_Suffix}: | |
f6da8aff RD |
926 | @cindex @code{Spec_Suffix} |
927 | @cindex @code{Specification_Suffix} | |
b2cacbfe AC |
928 | For Ada, these attributes give the suffix used in file names that contain |
929 | specifications. For other languages, they give the extension for files | |
930 | that contain declaration (header files in C for instance). The attribute | |
931 | is indexed on the language. | |
932 | The two attributes are equivalent, but the latter is obsolescent. | |
466c2127 AC |
933 | |
934 | If the value of the attribute is the empty string, it indicates to the | |
935 | Project Manager that the only specifications/header files for the language | |
936 | are those specified with attributes @code{Spec} or | |
937 | @code{Specification_Exceptions}. | |
938 | ||
b2cacbfe | 939 | If @code{Spec_Suffix ("Ada")} is not specified, then the default is |
d77cfab2 | 940 | @code{".ads"}. |
466c2127 AC |
941 | |
942 | A non empty value must satisfy the following requirements: | |
b2cacbfe AC |
943 | |
944 | @itemize - | |
b2cacbfe | 945 | @item It must include at least one dot |
466c2127 AC |
946 | @item If @code{Dot_Replacement} is a single dot, then it cannot include |
947 | more than one dot. | |
b2cacbfe AC |
948 | @end itemize |
949 | ||
950 | @item @b{Body_Suffix} and @b{Implementation_Suffix}: | |
f6da8aff RD |
951 | @cindex @code{Body_Suffix} |
952 | @cindex @code{Implementation_Suffix} | |
b2cacbfe AC |
953 | These attributes give the extension used for file names that contain |
954 | code (bodies in Ada). They are indexed on the language. The second | |
955 | version is obsolescent and fully replaced by the first attribute. | |
956 | ||
466c2127 AC |
957 | For each language of a project, one of these two attributes need to be |
958 | specified, either in the project itself or in the configuration project file. | |
959 | ||
960 | If the value of the attribute is the empty string, it indicates to the | |
961 | Project Manager that the only source files for the language | |
962 | are those specified with attributes @code{Body} or | |
963 | @code{Implementation_Exceptions}. | |
964 | ||
b2cacbfe AC |
965 | These attributes must satisfy the same requirements as @code{Spec_Suffix}. |
966 | In addition, they must be different from any of the values in | |
967 | @code{Spec_Suffix}. | |
968 | If @code{Body_Suffix ("Ada")} is not specified, then the default is | |
d77cfab2 | 969 | @code{".adb"}. |
b2cacbfe AC |
970 | |
971 | If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the | |
972 | same string, then a file name that ends with the longest of these two | |
973 | suffixes will be a body if the longest suffix is @code{Body_Suffix ("Ada")} | |
974 | or a spec if the longest suffix is @code{Spec_Suffix ("Ada")}. | |
975 | ||
466c2127 AC |
976 | If the suffix does not start with a '.', a file with a name exactly equal to |
977 | the suffix will also be part of the project (for instance if you define the | |
978 | suffix as @code{Makefile.in}, a file called @file{Makefile.in} will be part | |
979 | of the project. This capability is usually not interesting when building. | |
b2cacbfe AC |
980 | However, it might become useful when a project is also used to |
981 | find the list of source files in an editor, like the GNAT Programming System | |
982 | (GPS). | |
983 | ||
984 | @item @b{Separate_Suffix}: | |
f6da8aff | 985 | @cindex @code{Separate_Suffix} |
b2cacbfe AC |
986 | This attribute is specific to Ada. It denotes the suffix used in file names |
987 | that contain separate bodies. If it is not specified, then it defaults to | |
466c2127 AC |
988 | same value as @code{Body_Suffix ("Ada")}. |
989 | ||
990 | The value of this attribute cannot be the empty string. | |
991 | ||
992 | Otherwise, the same rules apply as for the | |
b2cacbfe AC |
993 | @code{Body_Suffix} attribute. The only accepted index is "Ada". |
994 | ||
995 | @item @b{Spec} or @b{Specification}: | |
f6da8aff RD |
996 | @cindex @code{Spec} |
997 | @cindex @code{Specification} | |
b2cacbfe AC |
998 | This attribute @code{Spec} can be used to define the source file name for a |
999 | given Ada compilation unit's spec. The index is the literal name of the Ada | |
1000 | unit (case insensitive). The value is the literal base name of the file that | |
1001 | contains this unit's spec (case sensitive or insensitive depending on the | |
1002 | operating system). This attribute allows the definition of exceptions to the | |
1003 | general naming scheme, in case some files do not follow the usual | |
1004 | convention. | |
1005 | ||
1006 | When a source file contains several units, the relative position of the unit | |
1007 | can be indicated. The first unit in the file is at position 1 | |
1008 | ||
1009 | @smallexample @c projectfile | |
1010 | for Spec ("MyPack.MyChild") use "mypack.mychild.spec"; | |
1011 | for Spec ("top") use "foo.a" at 1; | |
1012 | for Spec ("foo") use "foo.a" at 2; | |
1013 | @end smallexample | |
1014 | ||
1015 | @item @b{Body} or @b{Implementation}: | |
f6da8aff RD |
1016 | @cindex @code{Body} |
1017 | @cindex @code{Implementation} | |
b2cacbfe AC |
1018 | These attribute play the same role as @emph{Spec} for Ada bodies. |
1019 | ||
1020 | @item @b{Specification_Exceptions} and @b{Implementation_Exceptions}: | |
f6da8aff RD |
1021 | @cindex @code{Specification_Exceptions} |
1022 | @cindex @code{Implementation_Exceptions} | |
b2cacbfe AC |
1023 | These attributes define exceptions to the naming scheme for languages |
1024 | other than Ada. They are indexed on the language name, and contain | |
1025 | a list of file names respectively for headers and source code. | |
1026 | ||
b2cacbfe AC |
1027 | @end table |
1028 | ||
d77cfab2 | 1029 | @set unw |
b2cacbfe AC |
1030 | For example, the following package models the Apex file naming rules: |
1031 | ||
1032 | @smallexample @c projectfile | |
1033 | @group | |
d77cfab2 AC |
1034 | @b{package} Naming @b{is} |
1035 | @b{for} Casing @b{use} "lowercase"; | |
1036 | @b{for} Dot_Replacement @b{use} "."; | |
1037 | @b{for} Spec_Suffix ("Ada") @b{use} ".1.ada"; | |
1038 | @b{for} Body_Suffix ("Ada") @b{use} ".2.ada"; | |
1039 | @b{end} Naming; | |
b2cacbfe AC |
1040 | @end group |
1041 | @end smallexample | |
b2cacbfe | 1042 | |
b2cacbfe | 1043 | |
df378148 AC |
1044 | @c --------------------------------------------- |
1045 | @node Installation | |
1046 | @subsection Installation | |
1047 | @c --------------------------------------------- | |
1048 | ||
1049 | @noindent | |
1050 | After building an application or a library it is often required to | |
436d9f92 AC |
1051 | install it into the development environment. For instance this step is |
1052 | required if the library is to be used by another application. | |
1053 | The @command{gprinstall} tool provides an easy way to install | |
1054 | libraries, executable or object code generated during the build. The | |
df378148 AC |
1055 | @b{Install} package can be used to change the default locations. |
1056 | ||
1057 | The following attributes can be defined in package @code{Install}: | |
1058 | ||
1059 | @table @asis | |
1060 | ||
1061 | @item @b{Active} | |
1062 | ||
1063 | Whether the project is to be installed, values are @code{true} | |
1064 | (default) or @code{false}. | |
1065 | ||
ca11219d AC |
1066 | @item @b{Artifacts} |
1067 | @cindex @code{Artifacts} | |
1068 | ||
1069 | An array attribute to declare a set of files not part of the sources | |
1070 | to be installed. The array discriminant is the directory where the | |
1071 | file is to be installed. If a relative directory then Prefix (see | |
1072 | below) is prepended. | |
1073 | ||
df378148 AC |
1074 | @item @b{Prefix}: |
1075 | @cindex @code{Prefix} | |
1076 | ||
1077 | Root directory for the installation. | |
1078 | ||
1079 | @item @b{Exec_Subdir} | |
1080 | ||
1081 | Subdirectory of @b{Prefix} where executables are to be | |
1082 | installed. Default is @b{bin}. | |
1083 | ||
1084 | @item @b{Lib_Subdir} | |
1085 | ||
1086 | Subdirectory of @b{Prefix} where directory with the library or object | |
1087 | files is to be installed. Default is @b{lib}. | |
1088 | ||
1089 | @item @b{Sources_Subdir} | |
1090 | ||
1091 | Subdirectory of @b{Prefix} where directory with sources is to be | |
1092 | installed. Default is @b{include}. | |
1093 | ||
1094 | @item @b{Project_Subdir} | |
1095 | ||
436d9f92 | 1096 | Subdirectory of @b{Prefix} where the generated project file is to be |
df378148 | 1097 | installed. Default is @b{share/gpr}. |
bb6c60f4 AC |
1098 | |
1099 | @item @b{Mode} | |
1100 | ||
1101 | The installation mode, it is either @b{dev} (default) or @b{usage}. | |
1102 | See @b{gprbuild} user's guide for details. | |
1103 | ||
1104 | @item @b{Install_Name} | |
1105 | ||
1106 | Specify the name to use for recording the installation. The default is | |
1107 | the project name without the extension. | |
df378148 AC |
1108 | @end table |
1109 | ||
f3d42000 AC |
1110 | @c --------------------------------------------- |
1111 | @node Distributed support | |
1112 | @subsection Distributed support | |
1113 | @c --------------------------------------------- | |
1114 | ||
1115 | @noindent | |
1116 | For large projects the compilation time can become a limitation in | |
1117 | the development cycle. To cope with that, GPRbuild supports | |
1118 | distributed compilation. | |
1119 | ||
1120 | The following attributes can be defined in package @code{Remote}: | |
1121 | ||
1122 | @table @asis | |
1123 | ||
f3d42000 AC |
1124 | @item @b{Root_Dir}: |
1125 | @cindex @code{Root_Dir} | |
1126 | ||
1127 | Root directory of the project's sources. The default value is the | |
1128 | project's directory. | |
1129 | ||
1130 | @end table | |
1131 | ||
b2cacbfe AC |
1132 | @c --------------------------------------------- |
1133 | @node Organizing Projects into Subsystems | |
1134 | @section Organizing Projects into Subsystems | |
1135 | @c --------------------------------------------- | |
1136 | ||
1137 | @noindent | |
1138 | A @b{subsystem} is a coherent part of the complete system to be built. It is | |
31b8a02d AC |
1139 | represented by a set of sources and one single object directory. A system can |
1140 | be composed of a single subsystem when it is simple as we have seen in the | |
1141 | first section. Complex systems are usually composed of several interdependent | |
b2cacbfe AC |
1142 | subsystems. A subsystem is dependent on another subsystem if knowledge of the |
1143 | other one is required to build it, and in particular if visibility on some of | |
1144 | the sources of this other subsystem is required. Each subsystem is usually | |
1145 | represented by its own project file. | |
1146 | ||
1147 | In this section, the previous example is being extended. Let's assume some | |
1148 | sources of our @code{Build} project depend on other sources. | |
1149 | For instance, when building a graphical interface, it is usual to depend upon | |
1150 | a graphical library toolkit such as GtkAda. Furthermore, we also need | |
1151 | sources from a logging module we had previously written. | |
1152 | ||
1153 | @menu | |
1154 | * Project Dependencies:: | |
1155 | * Cyclic Project Dependencies:: | |
1156 | * Sharing Between Projects:: | |
1157 | * Global Attributes:: | |
1158 | @end menu | |
1159 | ||
1160 | @c --------------------------------------------- | |
1161 | @node Project Dependencies | |
1162 | @subsection Project Dependencies | |
1163 | @c --------------------------------------------- | |
1164 | ||
1165 | @noindent | |
1166 | GtkAda comes with its own project file (appropriately called | |
1167 | @file{gtkada.gpr}), and we will assume we have already built a project | |
1168 | called @file{logging.gpr} for the logging module. With the information provided | |
1169 | so far in @file{build.gpr}, building the application would fail with an error | |
1170 | indicating that the gtkada and logging units that are relied upon by the sources | |
1171 | of this project cannot be found. | |
1172 | ||
4887624e AC |
1173 | This is solved by adding the following @b{with} clauses at the beginning of our |
1174 | project: | |
b2cacbfe AC |
1175 | |
1176 | @smallexample @c projectfile | |
d77cfab2 AC |
1177 | @b{with} "gtkada.gpr"; |
1178 | @b{with} "a/b/logging.gpr"; | |
1179 | @b{project} Build @b{is} | |
1180 | ... --@i{ as before} | |
1181 | @b{end} Build; | |
b2cacbfe AC |
1182 | @end smallexample |
1183 | ||
1184 | @noindent | |
be5a1b93 | 1185 | @cindex @code{Externally_Built} |
4887624e AC |
1186 | When such a project is compiled, @command{gprbuild} will automatically check |
1187 | the other projects and recompile their sources when needed. It will also | |
b2cacbfe | 1188 | recompile the sources from @code{Build} when needed, and finally create the |
e86a3a7e | 1189 | executable. In some cases, the implementation units needed to recompile a |
4887624e AC |
1190 | project are not available, or come from some third party and you do not want to |
1191 | recompile it yourself. In this case, set the attribute @b{Externally_Built} to | |
1192 | "true", indicating to the builder that this project can be assumed to be | |
1193 | up-to-date, and should not be considered for recompilation. In Ada, if the | |
1194 | sources of this externally built project were compiled with another version of | |
1195 | the compiler or with incompatible options, the binder will issue an error. | |
b2cacbfe AC |
1196 | |
1197 | The project's @code{with} clause has several effects. It provides source | |
e86a3a7e AC |
1198 | visibility between projects during the compilation process. It also guarantees |
1199 | that the necessary object files from @code{Logging} and @code{GtkAda} are | |
1200 | available when linking @code{Build}. | |
b2cacbfe AC |
1201 | |
1202 | As can be seen in this example, the syntax for importing projects is similar | |
1203 | to the syntax for importing compilation units in Ada. However, project files | |
1204 | use literal strings instead of names, and the @code{with} clause identifies | |
1205 | project files rather than packages. | |
1206 | ||
1207 | Each literal string after @code{with} is the path | |
1208 | (absolute or relative) to a project file. The @code{.gpr} extension is | |
1209 | optional, although we recommend adding it. If no extension is specified, | |
d77cfab2 | 1210 | and no project file with the @file{.gpr} extension is found, then |
b2cacbfe AC |
1211 | the file is searched for exactly as written in the @code{with} clause, |
1212 | that is with no extension. | |
1213 | ||
2c1b72d7 AC |
1214 | As mentioned above, the path after a @code{with} has to be a literal |
1215 | string, and you cannot use concatenation, or lookup the value of external | |
1216 | variables to change the directories from which a project is loaded. | |
1217 | A solution if you need something like this is to use aggregate projects | |
1218 | (@pxref{Aggregate Projects}). | |
1219 | ||
be5a1b93 | 1220 | @cindex project path |
b2cacbfe AC |
1221 | When a relative path or a base name is used, the |
1222 | project files are searched relative to each of the directories in the | |
1223 | @b{project path}. This path includes all the directories found with the | |
4887624e | 1224 | following algorithm, in this order; the first matching file is used: |
b2cacbfe AC |
1225 | |
1226 | @itemize @bullet | |
1227 | @item First, the file is searched relative to the directory that contains the | |
1228 | current project file. | |
1d801f21 | 1229 | |
f6da8aff | 1230 | @item |
e2441021 | 1231 | @cindex @code{GPR_PROJECT_PATH_FILE} |
f6da8aff | 1232 | @cindex @code{GPR_PROJECT_PATH} |
e2441021 | 1233 | @cindex @code{ADA_PROJECT_PATH} |
b2cacbfe | 1234 | Then it is searched relative to all the directories specified in the |
d77cfab2 | 1235 | environment variables @b{GPR_PROJECT_PATH_FILE}, |
e2441021 AC |
1236 | @b{GPR_PROJECT_PATH} and @b{ADA_PROJECT_PATH} (in that order) if they exist. |
1237 | The value of @b{GPR_PROJECT_PATH_FILE}, when defined, is the path name of | |
1238 | a text file that contains project directory path names, one per line. | |
1239 | @b{GPR_PROJECT_PATH} and @b{ADA_PROJECT_PATH}, when defined, contain | |
1240 | project directory path names separated by directory separators. | |
1241 | @b{ADA_PROJECT_PATH} is used for compatibility, it is recommended to | |
1242 | use @b{GPR_PROJECT_PATH_FILE} or @b{GPR_PROJECT_PATH}. | |
1d801f21 | 1243 | |
b2cacbfe | 1244 | @item Finally, it is searched relative to the default project directories. |
4887624e AC |
1245 | Such directories depend on the tool used. The locations searched in the |
1246 | specified order are: | |
1d801f21 AC |
1247 | |
1248 | @itemize @bullet | |
1249 | @item @file{<prefix>/<target>/lib/gnat} | |
a54d0eb4 AC |
1250 | (for @command{gnatmake} in all cases, and for @command{gprbuild} if option |
1251 | @option{--target} is specified) | |
a0367a97 AC |
1252 | @item @file{<prefix>/<target>/share/gpr} |
1253 | (for @command{gnatmake} in all cases, and for @command{gprbuild} if option | |
1254 | @option{--target} is specified) | |
1d801f21 AC |
1255 | @item @file{<prefix>/share/gpr/} |
1256 | (for @command{gnatmake} and @command{gprbuild}) | |
1257 | @item @file{<prefix>/lib/gnat/} | |
1258 | (for @command{gnatmake} and @command{gprbuild}) | |
1259 | @end itemize | |
b2cacbfe | 1260 | |
1d801f21 AC |
1261 | In our example, @file{gtkada.gpr} is found in the predefined directory if |
1262 | it was installed at the same root as GNAT. | |
b2cacbfe AC |
1263 | @end itemize |
1264 | ||
1265 | @noindent | |
1266 | Some tools also support extending the project path from the command line, | |
1267 | generally through the @option{-aP}. You can see the value of the project | |
1268 | path by using the @command{gnatls -v} command. | |
1269 | ||
1270 | Any symbolic link will be fully resolved in the directory of the | |
1271 | importing project file before the imported project file is examined. | |
1272 | ||
1273 | Any source file in the imported project can be used by the sources of the | |
1274 | importing project, transitively. | |
1275 | Thus if @code{A} imports @code{B}, which imports @code{C}, the sources of | |
1276 | @code{A} may depend on the sources of @code{C}, even if @code{A} does not | |
1277 | import @code{C} explicitly. However, this is not recommended, because if | |
1278 | and when @code{B} ceases to import @code{C}, some sources in @code{A} will | |
1279 | no longer compile. @command{gprbuild} has a switch @option{--no-indirect-imports} | |
1280 | that will report such indirect dependencies. | |
1281 | ||
1282 | One very important aspect of a project hierarchy is that | |
1283 | @b{a given source can only belong to one project} (otherwise the project manager | |
1284 | would not know which settings apply to it and when to recompile it). It means | |
1285 | that different project files do not usually share source directories or | |
1286 | when they do, they need to specify precisely which project owns which sources | |
1287 | using attribute @code{Source_Files} or equivalent. By contrast, 2 projects | |
1288 | can each own a source with the same base file name as long as they live in | |
1289 | different directories. The latter is not true for Ada Sources because of the | |
308e6f3a | 1290 | correlation between source files and Ada units. |
b2cacbfe AC |
1291 | |
1292 | @c --------------------------------------------- | |
1293 | @node Cyclic Project Dependencies | |
1294 | @subsection Cyclic Project Dependencies | |
1295 | @c --------------------------------------------- | |
1296 | ||
1297 | @noindent | |
1298 | Cyclic dependencies are mostly forbidden: | |
1299 | if @code{A} imports @code{B} (directly or indirectly) then @code{B} | |
1300 | is not allowed to import @code{A}. However, there are cases when cyclic | |
1301 | dependencies would be beneficial. For these cases, another form of import | |
1302 | between projects exists: the @b{limited with}. A project @code{A} that | |
1303 | imports a project @code{B} with a straight @code{with} may also be imported, | |
1304 | directly or indirectly, by @code{B} through a @code{limited with}. | |
1305 | ||
1306 | The difference between straight @code{with} and @code{limited with} is that | |
1307 | the name of a project imported with a @code{limited with} cannot be used in the | |
1308 | project importing it. In particular, its packages cannot be renamed and | |
1309 | its variables cannot be referred to. | |
1310 | ||
1311 | @smallexample @c 0projectfile | |
1312 | with "b.gpr"; | |
1313 | with "c.gpr"; | |
1314 | project A is | |
1315 | For Exec_Dir use B'Exec_Dir; -- ok | |
1316 | end A; | |
1317 | ||
1318 | limited with "a.gpr"; -- Cyclic dependency: A -> B -> A | |
1319 | project B is | |
1320 | For Exec_Dir use A'Exec_Dir; -- not ok | |
1321 | end B; | |
1322 | ||
1323 | with "d.gpr"; | |
1324 | project C is | |
1325 | end C; | |
1326 | ||
1327 | limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A | |
1328 | project D is | |
1329 | For Exec_Dir use A'Exec_Dir; -- not ok | |
1330 | end D; | |
1331 | @end smallexample | |
1332 | ||
1333 | @c --------------------------------------------- | |
1334 | @node Sharing Between Projects | |
1335 | @subsection Sharing Between Projects | |
1336 | @c --------------------------------------------- | |
1337 | ||
1338 | @noindent | |
308e6f3a | 1339 | When building an application, it is common to have similar needs in several of |
31b8a02d AC |
1340 | the projects corresponding to the subsystems under construction. For instance, |
1341 | they will all have the same compilation switches. | |
b2cacbfe AC |
1342 | |
1343 | As seen before (@pxref{Tools Options in Project Files}), setting compilation | |
31b8a02d AC |
1344 | switches for all sources of a subsystem is simple: it is just a matter of |
1345 | adding a @code{Compiler.Default_Switches} attribute to each project files with | |
1346 | the same value. Of course, that means duplication of data, and both places need | |
1347 | to be changed in order to recompile the whole application with different | |
1348 | switches. It can become a real problem if there are many subsystems and thus | |
1349 | many project files to edit. | |
b2cacbfe AC |
1350 | |
1351 | There are two main approaches to avoiding this duplication: | |
1352 | ||
1353 | @itemize @bullet | |
1354 | @item Since @file{build.gpr} imports @file{logging.gpr}, we could change it | |
1355 | to reference the attribute in Logging, either through a package renaming, | |
1356 | or by referencing the attribute. The following example shows both cases: | |
1357 | ||
1358 | @smallexample @c projectfile | |
1359 | project Logging is | |
1360 | package Compiler is | |
d77cfab2 AC |
1361 | for Switches ("Ada") |
1362 | use ("-O2"); | |
b2cacbfe AC |
1363 | end Compiler; |
1364 | package Binder is | |
d77cfab2 | 1365 | for Switches ("Ada") |
455f3336 | 1366 | use ("-E"); |
b2cacbfe AC |
1367 | end Binder; |
1368 | end Logging; | |
1369 | ||
1370 | with "logging.gpr"; | |
1371 | project Build is | |
1372 | package Compiler renames Logging.Compiler; | |
1373 | package Binder is | |
d77cfab2 | 1374 | for Switches ("Ada") use Logging.Binder'Switches ("Ada"); |
b2cacbfe AC |
1375 | end Binder; |
1376 | end Build; | |
1377 | @end smallexample | |
1378 | ||
1379 | @noindent | |
1380 | The solution used for @code{Compiler} gets the same value for all | |
1381 | attributes of the package, but you cannot modify anything from the | |
1382 | package (adding extra switches or some exceptions). The second | |
1383 | version is more flexible, but more verbose. | |
1384 | ||
1385 | If you need to refer to the value of a variable in an imported | |
1386 | project, rather than an attribute, the syntax is similar but uses | |
1387 | a "." rather than an apostrophe. For instance: | |
1388 | ||
1389 | @smallexample @c projectfile | |
1390 | with "imported"; | |
1391 | project Main is | |
1392 | Var1 := Imported.Var; | |
1393 | end Main; | |
1394 | @end smallexample | |
1395 | ||
1396 | @item The second approach is to define the switches in a third project. | |
4887624e | 1397 | That project is set up without any sources (so that, as opposed to |
b2cacbfe AC |
1398 | the first example, none of the project plays a special role), and |
1399 | will only be used to define the attributes. Such a project is | |
1400 | typically called @file{shared.gpr}. | |
1401 | ||
1402 | @smallexample @c projectfile | |
1403 | abstract project Shared is | |
455f3336 | 1404 | for Source_Files use (); -- no sources |
b2cacbfe | 1405 | package Compiler is |
d77cfab2 AC |
1406 | for Switches ("Ada") |
1407 | use ("-O2"); | |
b2cacbfe AC |
1408 | end Compiler; |
1409 | end Shared; | |
1410 | ||
1411 | with "shared.gpr"; | |
1412 | project Logging is | |
1413 | package Compiler renames Shared.Compiler; | |
1414 | end Logging; | |
1415 | ||
1416 | with "shared.gpr"; | |
1417 | project Build is | |
1418 | package Compiler renames Shared.Compiler; | |
1419 | end Build; | |
1420 | @end smallexample | |
1421 | ||
1422 | @noindent | |
1423 | As for the first example, we could have chosen to set the attributes | |
31b8a02d | 1424 | one by one rather than to rename a package. The reason we explicitly |
b2cacbfe AC |
1425 | indicate that @code{Shared} has no sources is so that it can be created |
1426 | in any directory and we are sure it shares no sources with @code{Build} | |
1427 | or @code{Logging}, which of course would be invalid. | |
1428 | ||
f6da8aff | 1429 | @cindex project qualifier |
b2cacbfe AC |
1430 | Note the additional use of the @b{abstract} qualifier in @file{shared.gpr}. |
1431 | This qualifier is optional, but helps convey the message that we do not | |
1432 | intend this project to have sources (@pxref{Qualified Projects} for | |
1433 | more qualifiers). | |
1434 | @end itemize | |
1435 | ||
b2cacbfe AC |
1436 | @c --------------------------------------------- |
1437 | @node Global Attributes | |
1438 | @subsection Global Attributes | |
1439 | @c --------------------------------------------- | |
1440 | ||
1441 | @noindent | |
1442 | We have already seen many examples of attributes used to specify a special | |
1443 | option of one of the tools involved in the build process. Most of those | |
1444 | attributes are project specific. That it to say, they only affect the invocation | |
1445 | of tools on the sources of the project where they are defined. | |
1446 | ||
1447 | There are a few additional attributes that apply to all projects in a | |
1448 | hierarchy as long as they are defined on the "main" project. | |
1449 | The main project is the project explicitly mentioned on the command-line. | |
1450 | The project hierarchy is the "with"-closure of the main project. | |
1451 | ||
1452 | Here is a list of commonly used global attributes: | |
1453 | ||
1454 | @table @asis | |
1455 | @item @b{Builder.Global_Configuration_Pragmas}: | |
f6da8aff | 1456 | @cindex @code{Global_Configuration_Pragmas} |
b2cacbfe AC |
1457 | This attribute points to a file that contains configuration pragmas |
1458 | to use when building executables. These pragmas apply for all | |
15a5de99 | 1459 | executables built from this project hierarchy. As we have seen before, |
b2cacbfe AC |
1460 | additional pragmas can be specified on a per-project basis by setting the |
1461 | @code{Compiler.Local_Configuration_Pragmas} attribute. | |
1462 | ||
1463 | @item @b{Builder.Global_Compilation_Switches}: | |
f6da8aff | 1464 | @cindex @code{Global_Compilation_Switches} |
b2cacbfe AC |
1465 | This attribute is a list of compiler switches to use when compiling any |
1466 | source file in the project hierarchy. These switches are used in addition | |
1467 | to the ones defined in the @code{Compiler} package, which only apply to | |
1468 | the sources of the corresponding project. This attribute is indexed on | |
1469 | the name of the language. | |
1470 | ||
1471 | @end table | |
1472 | ||
1473 | Using such global capabilities is convenient. It can also lead to unexpected | |
1474 | behavior. Especially when several subsystems are shared among different main | |
1475 | projects and the different global attributes are not | |
1476 | compatible. Note that using aggregate projects can be a safer and more powerful | |
1477 | replacement to global attributes. | |
1478 | ||
1479 | @c --------------------------------------------- | |
1480 | @node Scenarios in Projects | |
1481 | @section Scenarios in Projects | |
1482 | @c --------------------------------------------- | |
1483 | ||
1484 | @noindent | |
1485 | Various aspects of the projects can be modified based on @b{scenarios}. These | |
1486 | are user-defined modes that change the behavior of a project. Typical | |
1487 | examples are the setup of platform-specific compiler options, or the use of | |
1488 | a debug and a release mode (the former would activate the generation of debug | |
4887624e | 1489 | information, while the second will focus on improving code optimization). |
b2cacbfe | 1490 | |
4887624e AC |
1491 | Let's enhance our example to support debug and release modes. The issue is to |
1492 | let the user choose what kind of system he is building: use @option{-g} as | |
1493 | compiler switches in debug mode and @option{-O2} in release mode. We will also | |
1494 | set up the projects so that we do not share the same object directory in both | |
1495 | modes; otherwise switching from one to the other might trigger more | |
1496 | recompilations than needed or mix objects from the two modes. | |
b2cacbfe AC |
1497 | |
1498 | One naive approach is to create two different project files, say | |
1499 | @file{build_debug.gpr} and @file{build_release.gpr}, that set the appropriate | |
4887624e AC |
1500 | attributes as explained in previous sections. This solution does not scale |
1501 | well, because in the presence of multiple projects depending on each other, you | |
1502 | will also have to duplicate the complete hierarchy and adapt the project files | |
1503 | to point to the right copies. | |
b2cacbfe | 1504 | |
be5a1b93 | 1505 | @cindex scenarios |
b2cacbfe AC |
1506 | Instead, project files support the notion of scenarios controlled |
1507 | by external values. Such values can come from several sources (in decreasing | |
1508 | order of priority): | |
1509 | ||
1510 | @table @asis | |
1511 | @item @b{Command line}: | |
f6da8aff | 1512 | @cindex @option{-X} |
b2cacbfe AC |
1513 | When launching @command{gnatmake} or @command{gprbuild}, the user can pass |
1514 | extra @option{-X} switches to define the external value. In | |
1515 | our case, the command line might look like | |
1516 | ||
1517 | @smallexample | |
1518 | gnatmake -Pbuild.gpr -Xmode=debug | |
1519 | or gnatmake -Pbuild.gpr -Xmode=release | |
1520 | @end smallexample | |
1521 | ||
d77cfab2 | 1522 | @item @b{Environment variables}: |
b2cacbfe | 1523 | When the external value does not come from the command line, it can come from |
d77cfab2 AC |
1524 | the value of environment variables of the appropriate name. |
1525 | In our case, if an environment variable called "mode" | |
4887624e | 1526 | exists, its value will be taken into account. |
b2cacbfe | 1527 | |
4887624e | 1528 | @item @b{External function second parameter}. |
b2cacbfe AC |
1529 | |
1530 | @end table | |
1531 | ||
be5a1b93 | 1532 | @cindex @code{external} |
b2cacbfe AC |
1533 | We now need to get that value in the project. The general form is to use |
1534 | the predefined function @b{external} which returns the current value of | |
4887624e | 1535 | the external. For instance, we could set up the object directory to point to |
b2cacbfe AC |
1536 | either @file{obj/debug} or @file{obj/release} by changing our project to |
1537 | ||
1538 | @smallexample @c projectfile | |
d77cfab2 AC |
1539 | @b{project} Build @b{is} |
1540 | @b{for} Object_Dir @b{use} "obj/" & @b{external} ("mode", "debug"); | |
1541 | ... --@i{ as before} | |
1542 | @b{end} Build; | |
b2cacbfe AC |
1543 | @end smallexample |
1544 | ||
1545 | @noindent | |
1546 | The second parameter to @code{external} is optional, and is the default | |
1547 | value to use if "mode" is not set from the command line or the environment. | |
1548 | ||
1549 | In order to set the switches according to the different scenarios, other | |
b671e31b | 1550 | constructs have to be introduced such as typed variables and case constructions. |
b2cacbfe | 1551 | |
be5a1b93 | 1552 | @cindex typed variable |
b671e31b | 1553 | @cindex case construction |
b2cacbfe AC |
1554 | A @b{typed variable} is a variable that |
1555 | can take only a limited number of values, similar to an enumeration in Ada. | |
b671e31b | 1556 | Such a variable can then be used in a @b{case construction} and create conditional |
b2cacbfe AC |
1557 | sections in the project. The following example shows how this can be done: |
1558 | ||
1559 | @smallexample @c projectfile | |
d77cfab2 AC |
1560 | @b{project} Build @b{is} |
1561 | @b{type} Mode_Type @b{is} ("debug", "release"); --@i{ all possible values} | |
1562 | Mode : Mode_Type := @b{external} ("mode", "debug"); --@i{ a typed variable} | |
1563 | ||
1564 | @b{package} Compiler @b{is} | |
1565 | @b{case} Mode @b{is} | |
1566 | @b{when} "debug" => | |
1567 | @b{for} Switches ("Ada") | |
1568 | @b{use} ("-g"); | |
1569 | @b{when} "release" => | |
1570 | @b{for} Switches ("Ada") | |
1571 | @b{use} ("-O2"); | |
1572 | @b{end} @b{case}; | |
1573 | @b{end} Compiler; | |
1574 | @b{end} Build; | |
b2cacbfe AC |
1575 | @end smallexample |
1576 | ||
1577 | @noindent | |
1578 | The project has suddenly grown in size, but has become much more flexible. | |
1579 | @code{Mode_Type} defines the only valid values for the @code{mode} variable. If | |
1580 | any other value is read from the environment, an error is reported and the | |
1581 | project is considered as invalid. | |
1582 | ||
1583 | The @code{Mode} variable is initialized with an external value | |
1584 | defaulting to @code{"debug"}. This default could be omitted and that would | |
b671e31b | 1585 | force the user to define the value. Finally, we can use a case construction to set the |
b2cacbfe AC |
1586 | switches depending on the scenario the user has chosen. |
1587 | ||
1588 | Most aspects of the projects can depend on scenarios. The notable exception | |
4887624e | 1589 | are project dependencies (@code{with} clauses), which cannot depend on a scenario. |
b2cacbfe AC |
1590 | |
1591 | Scenarios work the same way with @b{project hierarchies}: you can either | |
1592 | duplicate a variable similar to @code{Mode} in each of the project (as long | |
1593 | as the first argument to @code{external} is always the same and the type is | |
1594 | the same), or simply set the variable in the @file{shared.gpr} project | |
1595 | (@pxref{Sharing Between Projects}). | |
1596 | ||
1597 | @c --------------------------------------------- | |
1598 | @node Library Projects | |
1599 | @section Library Projects | |
1600 | @c --------------------------------------------- | |
1601 | ||
1602 | @noindent | |
1603 | So far, we have seen examples of projects that create executables. However, | |
1604 | it is also possible to create libraries instead. A @b{library} is a specific | |
1605 | type of subsystem where, for convenience, objects are grouped together | |
1606 | using system-specific means such as archives or windows DLLs. | |
1607 | ||
1608 | Library projects provide a system- and language-independent way of building both @b{static} | |
1609 | and @b{dynamic} libraries. They also support the concept of @b{standalone | |
4887624e | 1610 | libraries} (SAL) which offer two significant properties: the elaboration |
b2cacbfe AC |
1611 | (e.g. initialization) of the library is either automatic or very simple; |
1612 | a change in the | |
1613 | implementation part of the library implies minimal post-compilation actions on | |
1614 | the complete system and potentially no action at all for the rest of the | |
1615 | system in the case of dynamic SALs. | |
1616 | ||
2757c5bf AC |
1617 | There is a restriction on shared library projects: by default, they are only |
1618 | allowed to import other shared library projects. They are not allowed to | |
1619 | import non library projects or static library projects. | |
1620 | ||
b2cacbfe AC |
1621 | The GNAT Project Manager takes complete care of the library build, rebuild and |
1622 | installation tasks, including recompilation of the source files for which | |
1623 | objects do not exist or are not up to date, assembly of the library archive, and | |
1624 | installation of the library (i.e., copying associated source, object and | |
1625 | @file{ALI} files to the specified location). | |
1626 | ||
1627 | @menu | |
1628 | * Building Libraries:: | |
1629 | * Using Library Projects:: | |
1630 | * Stand-alone Library Projects:: | |
1631 | * Installing a library with project files:: | |
1632 | @end menu | |
1633 | ||
1634 | @c --------------------------------------------- | |
1635 | @node Building Libraries | |
1636 | @subsection Building Libraries | |
1637 | @c --------------------------------------------- | |
1638 | ||
1639 | @noindent | |
1640 | Let's enhance our example and transform the @code{logging} subsystem into a | |
4887624e AC |
1641 | library. In order to do so, a few changes need to be made to |
1642 | @file{logging.gpr}. Some attributes need to be defined: at least | |
1643 | @code{Library_Name} and @code{Library_Dir}; in addition, some other attributes | |
1644 | can be used to specify specific aspects of the library. For readability, it is | |
1645 | also recommended (although not mandatory), to use the qualifier @code{library} | |
1646 | in front of the @code{project} keyword. | |
b2cacbfe AC |
1647 | |
1648 | @table @asis | |
1649 | @item @b{Library_Name}: | |
f6da8aff | 1650 | @cindex @code{Library_Name} |
b2cacbfe | 1651 | This attribute is the name of the library to be built. There is no |
7a0ddd20 AC |
1652 | restriction on the name of a library imposed by the project manager, except |
1653 | for stand-alone libraries whose names must follow the syntax of Ada | |
4887624e | 1654 | identifiers; however, there may be system-specific restrictions on the name. |
7a0ddd20 AC |
1655 | In general, it is recommended to stick to alphanumeric characters (and |
1656 | possibly single underscores) to help portability. | |
b2cacbfe AC |
1657 | |
1658 | @item @b{Library_Dir}: | |
f6da8aff | 1659 | @cindex @code{Library_Dir} |
b2cacbfe AC |
1660 | This attribute is the path (absolute or relative) of the directory where |
1661 | the library is to be installed. In the process of building a library, | |
1662 | the sources are compiled, the object files end up in the explicit or | |
1663 | implicit @code{Object_Dir} directory. When all sources of a library | |
1664 | are compiled, some of the compilation artifacts, including the library itself, | |
4887624e | 1665 | are copied to the library_dir directory. This directory must exist and be |
b2cacbfe AC |
1666 | writable. It must also be different from the object directory so that cleanup |
1667 | activities in the Library_Dir do not affect recompilation needs. | |
1668 | ||
1669 | @end table | |
1670 | ||
1671 | Here is the new version of @file{logging.gpr} that makes it a library: | |
1672 | ||
1673 | @smallexample @c projectfile | |
d77cfab2 AC |
1674 | library @b{project} Logging @b{is} --@i{ "library" is optional} |
1675 | @b{for} Library_Name @b{use} "logging"; --@i{ will create "liblogging.a" on Unix} | |
1676 | @b{for} Object_Dir @b{use} "obj"; | |
1677 | @b{for} Library_Dir @b{use} "lib"; --@i{ different from object_dir} | |
1678 | @b{end} Logging; | |
b2cacbfe AC |
1679 | @end smallexample |
1680 | ||
1681 | @noindent | |
1682 | Once the above two attributes are defined, the library project is valid and | |
1683 | is enough for building a library with default characteristics. | |
1684 | Other library-related attributes can be used to change the defaults: | |
1685 | ||
1686 | @table @asis | |
1687 | @item @b{Library_Kind}: | |
f6da8aff | 1688 | @cindex @code{Library_Kind} |
b2cacbfe AC |
1689 | The value of this attribute must be either @code{"static"}, @code{"dynamic"} or |
1690 | @code{"relocatable"} (the latter is a synonym for dynamic). It indicates | |
15a5de99 | 1691 | which kind of library should be built (the default is to build a |
b2cacbfe AC |
1692 | static library, that is an archive of object files that can potentially |
1693 | be linked into a static executable). When the library is set to be dynamic, | |
308e6f3a | 1694 | a separate image is created that will be loaded independently, usually |
b2cacbfe AC |
1695 | at the start of the main program execution. Support for dynamic libraries is |
1696 | very platform specific, for instance on Windows it takes the form of a DLL | |
1697 | while on GNU/Linux, it is a dynamic elf image whose suffix is usually | |
1698 | @file{.so}. Library project files, on the other hand, can be written in | |
308e6f3a RW |
1699 | a platform independent way so that the same project file can be used to build |
1700 | a library on different operating systems. | |
b2cacbfe AC |
1701 | |
1702 | If you need to build both a static and a dynamic library, it is recommended | |
4887624e AC |
1703 | to use two different object directories, since in some cases some extra code |
1704 | needs to be generated for the latter. For such cases, one can either define | |
1705 | two different project files, or a single one that uses scenarios to indicate | |
1706 | the various kinds of library to be built and their corresponding object_dir. | |
b2cacbfe | 1707 | |
be5a1b93 | 1708 | @cindex @code{Library_ALI_Dir} |
b2cacbfe | 1709 | @item @b{Library_ALI_Dir}: |
b2cacbfe AC |
1710 | This attribute may be specified to indicate the directory where the ALI |
1711 | files of the library are installed. By default, they are copied into the | |
1712 | @code{Library_Dir} directory, but as for the executables where we have a | |
1713 | separate @code{Exec_Dir} attribute, you might want to put them in a separate | |
1714 | directory since there can be hundreds of them. The same restrictions as for | |
1715 | the @code{Library_Dir} attribute apply. | |
1716 | ||
be5a1b93 | 1717 | @cindex @code{Library_Version} |
b2cacbfe | 1718 | @item @b{Library_Version}: |
4887624e | 1719 | This attribute is platform dependent, and has no effect on Windows. |
b2cacbfe AC |
1720 | On Unix, it is used only for dynamic libraries as the internal |
1721 | name of the library (the @code{"soname"}). If the library file name (built | |
1722 | from the @code{Library_Name}) is different from the @code{Library_Version}, | |
1723 | then the library file will be a symbolic link to the actual file whose name | |
1724 | will be @code{Library_Version}. This follows the usual installation schemes | |
1725 | for dynamic libraries on many Unix systems. | |
1726 | ||
be5a1b93 TQ |
1727 | @smallexample @c projectfile |
1728 | @group | |
d77cfab2 | 1729 | @b{project} Logging @b{is} |
b2cacbfe | 1730 | Version := "1"; |
d77cfab2 AC |
1731 | @b{for} Library_Dir @b{use} "lib"; |
1732 | @b{for} Library_Name @b{use} "logging"; | |
1733 | @b{for} Library_Kind @b{use} "dynamic"; | |
1734 | @b{for} Library_Version @b{use} "liblogging.so." & Version; | |
1735 | @b{end} Logging; | |
be5a1b93 TQ |
1736 | @end group |
1737 | @end smallexample | |
b2cacbfe AC |
1738 | |
1739 | @noindent | |
1740 | After the compilation, the directory @file{lib} will contain both a | |
1741 | @file{libdummy.so.1} library and a symbolic link to it called | |
1742 | @file{libdummy.so}. | |
1743 | ||
be5a1b93 | 1744 | @cindex @code{Library_GCC} |
b2cacbfe | 1745 | @item @b{Library_GCC}: |
b2cacbfe AC |
1746 | This attribute is the name of the tool to use instead of "gcc" to link shared |
1747 | libraries. A common use of this attribute is to define a wrapper script that | |
4887624e | 1748 | accomplishes specific actions before calling gcc (which itself calls the |
b2cacbfe AC |
1749 | linker to build the library image). |
1750 | ||
f2e7ec10 AC |
1751 | @item @b{Library_Options}: |
1752 | @cindex @code{Library_Options} | |
35a1c212 | 1753 | This attribute may be used to specify additional switches (last switches) |
f2e7ec10 AC |
1754 | when linking a shared library. |
1755 | ||
4887624e | 1756 | It may also be used to add foreign object files to a static library. |
41c79d60 AC |
1757 | Each string in Library_Options is an absolute or relative path of an object |
1758 | file. When a relative path, it is relative to the object directory. | |
1759 | ||
f2e7ec10 AC |
1760 | @item @b{Leading_Library_Options}: |
1761 | @cindex @code{Leading_Library_Options} | |
1762 | This attribute, that is taken into account only by @command{gprbuild}, may be | |
1763 | used to specified leading options (first switches) when linking a shared | |
1764 | library. | |
1765 | ||
be5a1b93 | 1766 | @cindex @code{Linker_Options} |
b2cacbfe | 1767 | @item @b{Linker.Linker_Options}: |
b2cacbfe AC |
1768 | This attribute specifies additional switches to be given to the linker when |
1769 | linking an executable. It is ignored when defined in the main project and | |
1770 | taken into account in all other projects that are imported directly or | |
1771 | indirectly. These switches complement the @code{Linker.Switches} | |
1772 | defined in the main project. This is useful when a particular subsystem | |
1773 | depends on an external library: adding this dependency as a | |
1774 | @code{Linker_Options} in the project of the subsystem is more convenient than | |
1775 | adding it to all the @code{Linker.Switches} of the main projects that depend | |
1776 | upon this subsystem. | |
1777 | @end table | |
1778 | ||
b2cacbfe AC |
1779 | @c --------------------------------------------- |
1780 | @node Using Library Projects | |
1781 | @subsection Using Library Projects | |
1782 | @c --------------------------------------------- | |
1783 | ||
1784 | @noindent | |
1785 | When the builder detects that a project file is a library project file, it | |
1786 | recompiles all sources of the project that need recompilation and rebuild the | |
1787 | library if any of the sources have been recompiled. It then groups all object | |
1788 | files into a single file, which is a shared or a static library. This library | |
1789 | can later on be linked with multiple executables. Note that the use | |
1790 | of shard libraries reduces the size of the final executable and can also reduce | |
1791 | the memory footprint at execution time when the library is shared among several | |
1792 | executables. | |
1793 | ||
1794 | It is also possible to build @b{multi-language libraries}. When using | |
1795 | @command{gprbuild} as a builder, multi-language library projects allow naturally | |
308e6f3a | 1796 | the creation of multi-language libraries . @command{gnatmake}, does not try to |
b2cacbfe AC |
1797 | compile non Ada sources. However, when the project is multi-language, it will |
1798 | automatically link all object files found in the object directory, whether or | |
1799 | not they were compiled from an Ada source file. This specific behavior does not | |
1800 | apply to Ada-only projects which only take into account the objects | |
1801 | corresponding to the sources of the project. | |
1802 | ||
1803 | A non-library project can import a library project. When the builder is invoked | |
1804 | on the former, the library of the latter is only rebuilt when absolutely | |
4887624e AC |
1805 | necessary. For instance, if a unit of the library is not up-to-date but none of |
1806 | the executables need this unit, then the unit is not recompiled and the library | |
1807 | is not reassembled. For instance, let's assume in our example that logging has | |
1808 | the following sources: @file{log1.ads}, @file{log1.adb}, @file{log2.ads} and | |
b2cacbfe AC |
1809 | @file{log2.adb}. If @file{log1.adb} has been modified, then the library |
1810 | @file{liblogging} will be rebuilt when compiling all the sources of | |
1811 | @code{Build} only if @file{proc.ads}, @file{pack.ads} or @file{pack.adb} | |
1812 | include a @code{"with Log1"}. | |
1813 | ||
1814 | To ensure that all the sources in the @code{Logging} library are | |
1815 | up to date, and that all the sources of @code{Build} are also up to date, | |
4887624e | 1816 | the following two commands need to be used: |
b2cacbfe AC |
1817 | |
1818 | @smallexample | |
1819 | gnatmake -Plogging.gpr | |
1820 | gnatmake -Pbuild.gpr | |
1821 | @end smallexample | |
1822 | ||
1823 | @noindent | |
1824 | All @file{ALI} files will also be copied from the object directory to the | |
1825 | library directory. To build executables, @command{gnatmake} will use the | |
1826 | library rather than the individual object files. | |
1827 | ||
4887624e | 1828 | Library projects can also be useful to describe a library that needs to be used |
b2cacbfe | 1829 | but, for some reason, cannot be rebuilt. For instance, it is the case when some |
4887624e AC |
1830 | of the library sources are not available. Such library projects need to use the |
1831 | @code{Externally_Built} attribute as in the example below: | |
b2cacbfe AC |
1832 | |
1833 | @smallexample @c projectfile | |
d77cfab2 AC |
1834 | library @b{project} Extern_Lib @b{is} |
1835 | @b{for} Languages @b{use} ("Ada", "C"); | |
1836 | @b{for} Source_Dirs @b{use} ("lib_src"); | |
1837 | @b{for} Library_Dir @b{use} "lib2"; | |
1838 | @b{for} Library_Kind @b{use} "dynamic"; | |
1839 | @b{for} Library_Name @b{use} "l2"; | |
1840 | @b{for} Externally_Built @b{use} "true"; --@i{ <<<<} | |
1841 | @b{end} Extern_Lib; | |
b2cacbfe AC |
1842 | @end smallexample |
1843 | ||
1844 | @noindent | |
1845 | In the case of externally built libraries, the @code{Object_Dir} | |
1846 | attribute does not need to be specified because it will never be | |
1847 | used. | |
1848 | ||
1849 | The main effect of using such an externally built library project is mostly to | |
1850 | affect the linker command in order to reference the desired library. It can | |
1851 | also be achieved by using @code{Linker.Linker_Options} or @code{Linker.Switches} | |
1852 | in the project corresponding to the subsystem needing this external library. | |
1853 | This latter method is more straightforward in simple cases but when several | |
1854 | subsystems depend upon the same external library, finding the proper place | |
1855 | for the @code{Linker.Linker_Options} might not be easy and if it is | |
1856 | not placed properly, the final link command is likely to present ordering issues. | |
1857 | In such a situation, it is better to use the externally built library project | |
1858 | so that all other subsystems depending on it can declare this dependency thanks | |
1859 | to a project @code{with} clause, which in turn will trigger the builder to find | |
1860 | the proper order of libraries in the final link command. | |
b2cacbfe AC |
1861 | |
1862 | @c --------------------------------------------- | |
1863 | @node Stand-alone Library Projects | |
1864 | @subsection Stand-alone Library Projects | |
1865 | @c --------------------------------------------- | |
1866 | ||
1867 | @noindent | |
be5a1b93 | 1868 | @cindex standalone libraries |
b2cacbfe AC |
1869 | A @b{stand-alone library} is a library that contains the necessary code to |
1870 | elaborate the Ada units that are included in the library. A stand-alone | |
1871 | library is a convenient way to add an Ada subsystem to a more global system | |
1872 | whose main is not in Ada since it makes the elaboration of the Ada part mostly | |
1873 | transparent. However, stand-alone libraries are also useful when the main is in | |
308e6f3a | 1874 | Ada: they provide a means for minimizing relinking & redeployment of complex |
b2cacbfe AC |
1875 | systems when localized changes are made. |
1876 | ||
7a0ddd20 AC |
1877 | The name of a stand-alone library, specified with attribute |
1878 | @code{Library_Name}, must have the syntax of an Ada identifier. | |
1879 | ||
308e6f3a | 1880 | The most prominent characteristic of a stand-alone library is that it offers a |
b2cacbfe AC |
1881 | distinction between interface units and implementation units. Only the former |
1882 | are visible to units outside the library. A stand-alone library project is thus | |
b727a82b AC |
1883 | characterised by a third attribute, usually @b{Library_Interface}, in addition |
1884 | to the two attributes that make a project a Library Project | |
1885 | (@code{Library_Name} and @code{Library_Dir}). This third attribute may also be | |
1886 | @b{Interfaces}. @b{Library_Interface} only works when the interface is in Ada | |
1887 | and takes a list of units as parameter. @b{Interfaces} works for any supported | |
1888 | language and takes a list of sources as parameter. | |
b2cacbfe AC |
1889 | |
1890 | @table @asis | |
1891 | @item @b{Library_Interface}: | |
f6da8aff | 1892 | @cindex @code{Library_Interface} |
a8551b5f AC |
1893 | This attribute defines an explicit subset of the units of the project. Units |
1894 | from projects importing this library project may only "with" units whose | |
1895 | sources are listed in the @code{Library_Interface}. Other sources are | |
1896 | considered implementation units. | |
b2cacbfe | 1897 | |
be5a1b93 TQ |
1898 | @smallexample @c projectfile |
1899 | @group | |
d77cfab2 | 1900 | @b{for} Library_Dir @b{use} "lib"; |
4887624e | 1901 | @b{for} Library_Name @b{use} "logging"; |
d77cfab2 | 1902 | @b{for} Library_Interface @b{use} ("lib1", "lib2"); --@i{ unit names} |
be5a1b93 TQ |
1903 | @end group |
1904 | @end smallexample | |
b2cacbfe | 1905 | |
b727a82b | 1906 | @item @b{Interfaces} |
a8551b5f AC |
1907 | This attribute defines an explicit subset of the source files of a project. |
1908 | Sources from projects importing this project, can only depend on sources from | |
1909 | this subset. This attribute can be used on non library projects. It can also | |
1910 | be used as a replacement for attribute @code{Library_Interface}, in which | |
1911 | case, units have to be replaced by source files. For multi-language library | |
1912 | projects, it is the only way to make the project a Stand-Alone Library project | |
1913 | whose interface is not purely Ada. | |
b727a82b | 1914 | |
76f734d8 AC |
1915 | @item @b{Library_Standalone}: |
1916 | @cindex @code{Library_Standalone} | |
1917 | This attribute defines the kind of standalone library to | |
1918 | build. Values are either @code{standard} (the default), @code{no} or | |
5e12215f AC |
1919 | @code{encapsulated}. When @code{standard} is used the code to elaborate and |
1920 | finalize the library is embedded, when @code{encapsulated} is used the | |
4887624e | 1921 | library can furthermore depend only on static libraries (including |
76f734d8 AC |
1922 | the GNAT runtime). This attribute can be set to @code{no} to make it clear |
1923 | that the library should not be standalone in which case the | |
f6820c2d AC |
1924 | @code{Library_Interface} should not defined. Note that this attribute |
1925 | only applies to shared libraries, so @code{Library_Kind} must be set | |
1926 | to @code{dynamic}. | |
76f734d8 AC |
1927 | |
1928 | @smallexample @c projectfile | |
1929 | @group | |
d77cfab2 | 1930 | @b{for} Library_Dir @b{use} "lib"; |
4887624e | 1931 | @b{for} Library_Name @b{use} "logging"; |
d77cfab2 AC |
1932 | @b{for} Library_Kind @b{use} "dynamic"; |
1933 | @b{for} Library_Interface @b{use} ("lib1", "lib2"); --@i{ unit names} | |
1934 | @b{for} Library_Standalone @b{use} "encapsulated"; | |
76f734d8 AC |
1935 | @end group |
1936 | @end smallexample | |
1937 | ||
b2cacbfe AC |
1938 | @end table |
1939 | ||
1940 | In order to include the elaboration code in the stand-alone library, the binder | |
1941 | is invoked on the closure of the library units creating a package whose name | |
d77cfab2 | 1942 | depends on the library name (b~logging.ads/b in the example). |
b2cacbfe AC |
1943 | This binder-generated package includes @b{initialization} and @b{finalization} |
1944 | procedures whose names depend on the library name (@code{logginginit} and | |
1945 | @code{loggingfinal} in the example). The object corresponding to this package is | |
1946 | included in the library. | |
1947 | ||
1948 | @table @asis | |
1949 | @item @b{Library_Auto_Init}: | |
f6da8aff | 1950 | @cindex @code{Library_Auto_Init} |
b2cacbfe AC |
1951 | A dynamic stand-alone Library is automatically initialized |
1952 | if automatic initialization of Stand-alone Libraries is supported on the | |
1953 | platform and if attribute @b{Library_Auto_Init} is not specified or | |
1954 | is specified with the value "true". A static Stand-alone Library is never | |
1955 | automatically initialized. Specifying "false" for this attribute | |
4887624e | 1956 | prevents automatic initialization. |
b2cacbfe AC |
1957 | |
1958 | When a non-automatically initialized stand-alone library is used in an | |
1959 | executable, its initialization procedure must be called before any service of | |
1960 | the library is used. When the main subprogram is in Ada, it may mean that the | |
1961 | initialization procedure has to be called during elaboration of another | |
1962 | package. | |
1963 | ||
1964 | @item @b{Library_Dir}: | |
f6da8aff | 1965 | @cindex @code{Library_Dir} |
b2cacbfe AC |
1966 | For a stand-alone library, only the @file{ALI} files of the interface units |
1967 | (those that are listed in attribute @code{Library_Interface}) are copied to | |
1968 | the library directory. As a consequence, only the interface units may be | |
1969 | imported from Ada units outside of the library. If other units are imported, | |
1970 | the binding phase will fail. | |
1971 | ||
1972 | @item @b{Binder.Default_Switches}: | |
1973 | When a stand-alone library is bound, the switches that are specified in | |
1974 | the attribute @b{Binder.Default_Switches ("Ada")} are | |
1975 | used in the call to @command{gnatbind}. | |
1976 | ||
b2cacbfe | 1977 | @item @b{Library_Src_Dir}: |
f6da8aff | 1978 | @cindex @code{Library_Src_Dir} |
b2cacbfe AC |
1979 | This attribute defines the location (absolute or relative to the project |
1980 | directory) where the sources of the interface units are copied at | |
1981 | installation time. | |
4887624e AC |
1982 | These sources includes the specs of the interface units along with the |
1983 | closure of sources necessary to compile them successfully. That may include | |
1984 | bodies and subunits, when pragmas @code{Inline} are used, or when there are | |
1985 | generic units in specs. This directory cannot point to the object directory | |
1986 | or one of the source directories, but it can point to the library directory, | |
b2cacbfe AC |
1987 | which is the default value for this attribute. |
1988 | ||
1989 | @item @b{Library_Symbol_Policy}: | |
f6da8aff | 1990 | @cindex @code{Library_Symbol_Policy} |
b2cacbfe AC |
1991 | This attribute controls the export of symbols and, on some platforms (like |
1992 | VMS) that have the notions of major and minor IDs built in the library | |
1993 | files, it controls the setting of these IDs. It is not supported on all | |
1994 | platforms (where it will just have no effect). It may have one of the | |
1995 | following values: | |
1996 | ||
1997 | @itemize - | |
1998 | @item @code{"autonomous"} or @code{"default"}: exported symbols are not controlled | |
1999 | @item @code{"compliant"}: if attribute @b{Library_Reference_Symbol_File} | |
2000 | is not defined, then it is equivalent to policy "autonomous". If there | |
2001 | are exported symbols in the reference symbol file that are not in the | |
2002 | object files of the interfaces, the major ID of the library is increased. | |
2003 | If there are symbols in the object files of the interfaces that are not | |
2004 | in the reference symbol file, these symbols are put at the end of the list | |
2005 | in the newly created symbol file and the minor ID is increased. | |
2006 | @item @code{"controlled"}: the attribute @b{Library_Reference_Symbol_File} must be | |
2007 | defined. The library will fail to build if the exported symbols in the | |
2008 | object files of the interfaces do not match exactly the symbol in the | |
2009 | symbol file. | |
2010 | @item @code{"restricted"}: The attribute @b{Library_Symbol_File} must be defined. | |
2011 | The library will fail to build if there are symbols in the symbol file that | |
2012 | are not in the exported symbols of the object files of the interfaces. | |
2013 | Additional symbols in the object files are not added to the symbol file. | |
2014 | @item @code{"direct"}: The attribute @b{Library_Symbol_File} must be defined and | |
2015 | must designate an existing file in the object directory. This symbol file | |
2016 | is passed directly to the underlying linker without any symbol processing. | |
2017 | ||
2018 | @end itemize | |
2019 | ||
2020 | @item @b{Library_Reference_Symbol_File} | |
f6da8aff | 2021 | @cindex @code{Library_Reference_Symbol_File} |
b2cacbfe AC |
2022 | This attribute may define the path name of a reference symbol file that is |
2023 | read when the symbol policy is either "compliant" or "controlled", on | |
2024 | platforms that support symbol control, such as VMS, when building a | |
2025 | stand-alone library. The path may be an absolute path or a path relative | |
2026 | to the project directory. | |
2027 | ||
2028 | @item @b{Library_Symbol_File} | |
f6da8aff | 2029 | @cindex @code{Library_Symbol_File} |
b2cacbfe AC |
2030 | This attribute may define the name of the symbol file to be created when |
2031 | building a stand-alone library when the symbol policy is either "compliant", | |
2032 | "controlled" or "restricted", on platforms that support symbol control, | |
2033 | such as VMS. When symbol policy is "direct", then a file with this name | |
2034 | must exist in the object directory. | |
2035 | @end table | |
2036 | ||
b2cacbfe AC |
2037 | @c --------------------------------------------- |
2038 | @node Installing a library with project files | |
2039 | @subsection Installing a library with project files | |
2040 | @c --------------------------------------------- | |
2041 | ||
2042 | @noindent | |
4bb43ffb AC |
2043 | When using project files, a usable version of the library is created in the |
2044 | directory specified by the @code{Library_Dir} attribute of the library | |
2045 | project file. Thus no further action is needed in order to make use of | |
2046 | the libraries that are built as part of the general application build. | |
b2cacbfe AC |
2047 | |
2048 | You may want to install a library in a context different from where the library | |
2049 | is built. This situation arises with third party suppliers, who may want | |
2050 | to distribute a library in binary form where the user is not expected to be | |
2051 | able to recompile the library. The simplest option in this case is to provide | |
2052 | a project file slightly different from the one used to build the library, by | |
2053 | using the @code{externally_built} attribute. @ref{Using Library Projects} | |
2054 | ||
4bb43ffb | 2055 | Another option is to use @command{gprinstall} to install the library in a |
4887624e AC |
2056 | different context than the build location. @command{gprinstall} automatically |
2057 | generates a project to use this library, and also copies the minimum set of | |
2058 | sources needed to use the library to the install location. | |
4bb43ffb AC |
2059 | @ref{Installation} |
2060 | ||
b2cacbfe AC |
2061 | @c --------------------------------------------- |
2062 | @node Project Extension | |
2063 | @section Project Extension | |
2064 | @c --------------------------------------------- | |
2065 | ||
2066 | @noindent | |
2067 | During development of a large system, it is sometimes necessary to use | |
2068 | modified versions of some of the source files, without changing the original | |
2069 | sources. This can be achieved through the @b{project extension} facility. | |
2070 | ||
15a5de99 | 2071 | Suppose for instance that our example @code{Build} project is built every night |
4887624e | 2072 | for the whole team, in some shared directory. A developer usually needs to work |
b2cacbfe AC |
2073 | on a small part of the system, and might not want to have a copy of all the |
2074 | sources and all the object files (mostly because that would require too much | |
2075 | disk space, time to recompile everything). He prefers to be able to override | |
2076 | some of the source files in his directory, while taking advantage of all the | |
2077 | object files generated at night. | |
2078 | ||
2079 | Another example can be taken from large software systems, where it is common to have | |
2080 | multiple implementations of a common interface; in Ada terms, multiple | |
2081 | versions of a package body for the same spec. For example, one implementation | |
4887624e | 2082 | might be safe for use in tasking programs, while another might be used only |
b2cacbfe AC |
2083 | in sequential applications. This can be modeled in GNAT using the concept |
2084 | of @emph{project extension}. If one project (the ``child'') @emph{extends} | |
2085 | another project (the ``parent'') then by default all source files of the | |
2086 | parent project are inherited by the child, but the child project can | |
2087 | override any of the parent's source files with new versions, and can also | |
2088 | add new files or remove unnecessary ones. | |
2089 | This facility is the project analog of a type extension in | |
2090 | object-oriented programming. Project hierarchies are permitted (an extending | |
2091 | project may itself be extended), and a project that | |
2092 | extends a project can also import other projects. | |
2093 | ||
2094 | A third example is that of using project extensions to provide different | |
2095 | versions of the same system. For instance, assume that a @code{Common} | |
2096 | project is used by two development branches. One of the branches has now | |
2097 | been frozen, and no further change can be done to it or to @code{Common}. | |
2098 | However, the other development branch still needs evolution of @code{Common}. | |
2099 | Project extensions provide a flexible solution to create a new version | |
2100 | of a subsystem while sharing and reusing as much as possible from the original | |
2101 | one. | |
2102 | ||
4887624e | 2103 | A project extension implicitly inherits all the sources and objects from the |
b2cacbfe | 2104 | project it extends. It is possible to create a new version of some of the |
4887624e AC |
2105 | sources in one of the additional source directories of the extending |
2106 | project. Those new versions hide the original versions. Adding new sources or | |
2107 | removing existing ones is also possible. Here is an example on how to extend | |
2108 | the project @code{Build} from previous examples: | |
b2cacbfe AC |
2109 | |
2110 | @smallexample @c projectfile | |
d77cfab2 AC |
2111 | @b{project} Work @b{extends} "../bld/build.gpr" @b{is} |
2112 | @b{end} Work; | |
b2cacbfe AC |
2113 | @end smallexample |
2114 | ||
2115 | @noindent | |
2116 | The project after @b{extends} is the one being extended. As usual, it can be | |
2117 | specified using an absolute path, or a path relative to any of the directories | |
2118 | in the project path (@pxref{Project Dependencies}). This project does not | |
4887624e AC |
2119 | specify source or object directories, so the default values for these |
2120 | attributes will be used that is to say the current directory (where project | |
2121 | @code{Work} is placed). We can compile that project with | |
b2cacbfe AC |
2122 | |
2123 | @smallexample | |
4887624e | 2124 | gprbuild -Pwork |
b2cacbfe AC |
2125 | @end smallexample |
2126 | ||
2127 | @noindent | |
2128 | If no sources have been placed in the current directory, this command | |
2129 | won't do anything, since this project does not change the | |
2130 | sources it inherited from @code{Build}, therefore all the object files | |
2131 | in @code{Build} and its dependencies are still valid and are reused | |
2132 | automatically. | |
2133 | ||
4887624e AC |
2134 | Suppose we now want to supply an alternate version of @file{pack.adb} but use |
2135 | the existing versions of @file{pack.ads} and @file{proc.adb}. We can create | |
2136 | the new file in Work's current directory (likely by copying the one from the | |
2137 | @code{Build} project and making changes to it. If new packages are needed at | |
2138 | the same time, we simply create new files in the source directory of the | |
2139 | extending project. | |
b2cacbfe | 2140 | |
4887624e | 2141 | When we recompile, @command{gprbuild} will now automatically recompile |
b2cacbfe AC |
2142 | this file (thus creating @file{pack.o} in the current directory) and |
2143 | any file that depends on it (thus creating @file{proc.o}). Finally, the | |
2144 | executable is also linked locally. | |
2145 | ||
2146 | Note that we could have obtained the desired behavior using project import | |
2147 | rather than project inheritance. A @code{base} project would contain the | |
2148 | sources for @file{pack.ads} and @file{proc.adb}, and @code{Work} would | |
2149 | import @code{base} and add @file{pack.adb}. In this scenario, @code{base} | |
2150 | cannot contain the original version of @file{pack.adb} otherwise there would be | |
2151 | 2 versions of the same unit in the closure of the project and this is not | |
2152 | allowed. Generally speaking, it is not recommended to put the spec and the | |
2153 | body of a unit in different projects since this affects their autonomy and | |
2154 | reusability. | |
2155 | ||
2156 | In a project file that extends another project, it is possible to | |
2157 | indicate that an inherited source is @b{not part} of the sources of the | |
2158 | extending project. This is necessary sometimes when a package spec has | |
2159 | been overridden and no longer requires a body: in this case, it is | |
2160 | necessary to indicate that the inherited body is not part of the sources | |
2161 | of the project, otherwise there will be a compilation error | |
2162 | when compiling the spec. | |
2163 | ||
be5a1b93 TQ |
2164 | @cindex @code{Excluded_Source_Files} |
2165 | @cindex @code{Excluded_Source_List_File} | |
b2cacbfe AC |
2166 | For that purpose, the attribute @b{Excluded_Source_Files} is used. |
2167 | Its value is a list of file names. | |
2168 | It is also possible to use attribute @code{Excluded_Source_List_File}. | |
2169 | Its value is the path of a text file containing one file name per | |
2170 | line. | |
2171 | ||
2172 | @smallexample @c @projectfile | |
2173 | project Work extends "../bld/build.gpr" is | |
2174 | for Source_Files use ("pack.ads"); | |
2175 | -- New spec of Pkg does not need a completion | |
2176 | for Excluded_Source_Files use ("pack.adb"); | |
2177 | end Work; | |
2178 | @end smallexample | |
2179 | ||
2180 | @noindent | |
1a36a0cd AC |
2181 | All packages that are not declared in the extending project are inherited from |
2182 | the project being extended, with their attributes, with the exception of | |
2183 | @code{Linker'Linker_Options} which is never inherited. In particular, an | |
2184 | extending project retains all the switches specified in the project being | |
2185 | extended. | |
2186 | ||
2187 | At the project level, if they are not declared in the extending project, some | |
2188 | attributes are inherited from the project being extended. They are: | |
2189 | @code{Languages}, @code{Main} (for a root non library project) and | |
4887624e | 2190 | @code{Library_Name} (for a project extending a library project). |
b2cacbfe AC |
2191 | |
2192 | @menu | |
2193 | * Project Hierarchy Extension:: | |
2194 | @end menu | |
2195 | ||
2196 | @c --------------------------------------------- | |
2197 | @node Project Hierarchy Extension | |
2198 | @subsection Project Hierarchy Extension | |
2199 | @c --------------------------------------------- | |
2200 | ||
2201 | @noindent | |
2202 | One of the fundamental restrictions in project extension is the following: | |
2203 | @b{A project is not allowed to import directly or indirectly at the same time an | |
2204 | extending project and one of its ancestors}. | |
2205 | ||
2206 | By means of example, consider the following hierarchy of projects. | |
2207 | ||
2208 | @smallexample | |
2209 | a.gpr contains package A1 | |
2210 | b.gpr, imports a.gpr and contains B1, which depends on A1 | |
2211 | c.gpr, imports b.gpr and contains C1, which depends on B1 | |
2212 | @end smallexample | |
2213 | ||
2214 | @noindent | |
2215 | If we want to locally extend the packages @code{A1} and @code{C1}, we need to | |
2216 | create several extending projects: | |
2217 | ||
2218 | @smallexample | |
2219 | a_ext.gpr which extends a.gpr, and overrides A1 | |
2220 | b_ext.gpr which extends b.gpr and imports a_ext.gpr | |
2221 | c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1 | |
2222 | @end smallexample | |
2223 | ||
2224 | @noindent | |
2225 | @smallexample @c projectfile | |
d77cfab2 AC |
2226 | @b{project} A_Ext @b{extends} "a.gpr" @b{is} |
2227 | @b{for} Source_Files @b{use} ("a1.adb", "a1.ads"); | |
2228 | @b{end} A_Ext; | |
2229 | ||
2230 | @b{with} "a_ext.gpr"; | |
2231 | @b{project} B_Ext @b{extends} "b.gpr" @b{is} | |
2232 | @b{end} B_Ext; | |
2233 | ||
2234 | @b{with} "b_ext.gpr"; | |
2235 | @b{project} C_Ext @b{extends} "c.gpr" @b{is} | |
2236 | @b{for} Source_Files @b{use} ("c1.adb"); | |
2237 | @b{end} C_Ext; | |
b2cacbfe AC |
2238 | @end smallexample |
2239 | ||
2240 | @noindent | |
2241 | The extension @file{b_ext.gpr} is required, even though we are not overriding | |
2242 | any of the sources of @file{b.gpr} because otherwise @file{c_expr.gpr} would | |
2243 | import @file{b.gpr} which itself knows nothing about @file{a_ext.gpr}. | |
2244 | ||
be5a1b93 | 2245 | @cindex extends all |
b2cacbfe AC |
2246 | When extending a large system spanning multiple projects, it is often |
2247 | inconvenient to extend every project in the hierarchy that is impacted by a | |
2248 | small change introduced in a low layer. In such cases, it is possible to create | |
4887624e | 2249 | an @b{implicit extension} of an entire hierarchy using @b{extends all} |
b2cacbfe AC |
2250 | relationship. |
2251 | ||
2252 | When the project is extended using @code{extends all} inheritance, all projects | |
2253 | that are imported by it, both directly and indirectly, are considered virtually | |
2254 | extended. That is, the project manager creates implicit projects | |
2255 | that extend every project in the hierarchy; all these implicit projects do not | |
2256 | control sources on their own and use the object directory of | |
2257 | the "extending all" project. | |
2258 | ||
2259 | It is possible to explicitly extend one or more projects in the hierarchy | |
2260 | in order to modify the sources. These extending projects must be imported by | |
2261 | the "extending all" project, which will replace the corresponding virtual | |
2262 | projects with the explicit ones. | |
2263 | ||
2264 | When building such a project hierarchy extension, the project manager will | |
2265 | ensure that both modified sources and sources in implicit extending projects | |
4887624e | 2266 | that depend on them are recompiled. |
b2cacbfe AC |
2267 | |
2268 | Thus, in our example we could create the following projects instead: | |
2269 | ||
2270 | @smallexample | |
2271 | a_ext.gpr, extends a.gpr and overrides A1 | |
2272 | c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1 | |
2273 | ||
2274 | @end smallexample | |
2275 | ||
2276 | @noindent | |
2277 | @smallexample @c projectfile | |
d77cfab2 AC |
2278 | @b{project} A_Ext @b{extends} "a.gpr" @b{is} |
2279 | @b{for} Source_Files @b{use} ("a1.adb", "a1.ads"); | |
2280 | @b{end} A_Ext; | |
2281 | ||
2282 | @b{with} "a_ext.gpr"; | |
2283 | @b{project} C_Ext @b{extends} @b{all} "c.gpr" @b{is} | |
2284 | @b{for} Source_Files @b{use} ("c1.adb"); | |
2285 | @b{end} C_Ext; | |
b2cacbfe AC |
2286 | @end smallexample |
2287 | ||
2288 | @noindent | |
2289 | When building project @file{c_ext.gpr}, the entire modified project space is | |
2290 | considered for recompilation, including the sources of @file{b.gpr} that are | |
2291 | impacted by the changes in @code{A1} and @code{C1}. | |
2292 | ||
2c1b72d7 AC |
2293 | @c --------------------------------------------- |
2294 | @node Aggregate Projects | |
2295 | @section Aggregate Projects | |
2296 | @c --------------------------------------------- | |
2297 | ||
2298 | @noindent | |
2299 | ||
2300 | Aggregate projects are an extension of the project paradigm, and are | |
2301 | meant to solve a few specific use cases that cannot be solved directly | |
2302 | using standard projects. This section will go over a few of these use | |
15a5de99 | 2303 | cases to try to explain what you can use aggregate projects for. |
2c1b72d7 | 2304 | |
77aa62e7 | 2305 | @menu |
ce20f35b | 2306 | * Building all main programs from a single project tree:: |
77aa62e7 AC |
2307 | * Building a set of projects with a single command:: |
2308 | * Define a build environment:: | |
2309 | * Performance improvements in builder:: | |
2310 | * Syntax of aggregate projects:: | |
2311 | * package Builder in aggregate projects:: | |
2312 | @end menu | |
2313 | ||
2314 | @c ----------------------------------------------------------- | |
ce20f35b AC |
2315 | @node Building all main programs from a single project tree |
2316 | @subsection Building all main programs from a single project tree | |
77aa62e7 | 2317 | @c ----------------------------------------------------------- |
2c1b72d7 AC |
2318 | |
2319 | Most often, an application is organized into modules and submodules, | |
2320 | which are very conveniently represented as a project tree or graph | |
2321 | (the root project A @code{with}s the projects for each modules (say B and C), | |
2322 | which in turn @code{with} projects for submodules. | |
2323 | ||
2324 | Very often, modules will build their own executables (for testing | |
2325 | purposes for instance), or libraries (for easier reuse in various | |
2326 | contexts). | |
2327 | ||
4bb43ffb AC |
2328 | However, if you build your project through @command{gnatmake} or |
2329 | @command{gprbuild}, using a syntax similar to | |
2c1b72d7 AC |
2330 | |
2331 | @smallexample | |
2332 | gprbuild -PA.gpr | |
2333 | @end smallexample | |
2334 | ||
ce20f35b | 2335 | this will only rebuild the main programs of project A, not those of the |
2c1b72d7 | 2336 | imported projects B and C. Therefore you have to spawn several |
4bb43ffb | 2337 | @command{gnatmake} commands, one per project, to build all executables. |
2c1b72d7 | 2338 | This is a little inconvenient, but more importantly is inefficient |
4bb43ffb | 2339 | because @command{gnatmake} needs to do duplicate work to ensure that sources are |
2c1b72d7 | 2340 | up-to-date, and cannot easily compile things in parallel when using |
15a5de99 | 2341 | the -j switch. |
2c1b72d7 | 2342 | |
15a5de99 | 2343 | Also libraries are always rebuilt when building a project. |
2c1b72d7 AC |
2344 | |
2345 | You could therefore define an aggregate project Agg that groups A, B | |
2346 | and C. Then, when you build with | |
2347 | ||
2348 | @smallexample | |
2349 | gprbuild -PAgg.gpr | |
2350 | @end smallexample | |
2351 | ||
ce20f35b | 2352 | this will build all mains from A, B and C. |
2c1b72d7 AC |
2353 | |
2354 | @smallexample @c projectfile | |
d77cfab2 AC |
2355 | aggregate @b{project} Agg @b{is} |
2356 | @b{for} Project_Files @b{use} ("a.gpr", "b.gpr", "c.gpr"); | |
2357 | @b{end} Agg; | |
2c1b72d7 AC |
2358 | @end smallexample |
2359 | ||
ce20f35b | 2360 | If B or C do not define any main program (through their Main |
15a5de99 | 2361 | attribute), all their sources are built. When you do not group them |
2c1b72d7 | 2362 | in the aggregate project, only those sources that are needed by A |
15a5de99 | 2363 | will be built. |
2c1b72d7 | 2364 | |
ce20f35b | 2365 | If you add a main to a project P not already explicitly referenced in the |
2c1b72d7 | 2366 | aggregate project, you will need to add "p.gpr" in the list of project |
ce20f35b | 2367 | files for the aggregate project, or the main will not be built when |
2c1b72d7 AC |
2368 | building the aggregate project. |
2369 | ||
4887624e | 2370 | Aggregate projects are supported only with @command{gprbuild}, not with |
0bd38d94 AC |
2371 | @command{gnatmake}. |
2372 | ||
77aa62e7 AC |
2373 | @c --------------------------------------------------------- |
2374 | @node Building a set of projects with a single command | |
2c1b72d7 | 2375 | @subsection Building a set of projects with a single command |
77aa62e7 | 2376 | @c --------------------------------------------------------- |
2c1b72d7 AC |
2377 | |
2378 | One other case is when you have multiple applications and libraries | |
15a5de99 | 2379 | that are built independently from each other (but can be built in |
2c1b72d7 AC |
2380 | parallel). For instance, you have a project tree rooted at A, and |
2381 | another one (which might share some subprojects) rooted at B. | |
2382 | ||
4bb43ffb | 2383 | Using only @command{gprbuild}, you could do |
2c1b72d7 AC |
2384 | |
2385 | @smallexample | |
2386 | gprbuild -PA.gpr | |
2387 | gprbuild -PB.gpr | |
2388 | @end smallexample | |
2389 | ||
4bb43ffb | 2390 | to build both. But again, @command{gprbuild} has to do some duplicate work for |
2c1b72d7 AC |
2391 | those files that are shared between the two, and cannot truly build |
2392 | things in parallel efficiently. | |
2393 | ||
2394 | If the two projects are really independent, share no sources other | |
2395 | than through a common subproject, and have no source files with a | |
2396 | common basename, you could create a project C that imports A and | |
2397 | B. But these restrictions are often too strong, and one has to build | |
2398 | them independently. An aggregate project does not have these | |
15a5de99 | 2399 | limitations and can aggregate two project trees that have common |
2c1b72d7 AC |
2400 | sources. |
2401 | ||
70f4ad20 | 2402 | This scenario is particularly useful in environments like VxWorks 653 |
15a5de99 | 2403 | where the applications running in the multiple partitions can be built |
4bb43ffb | 2404 | in parallel through a single @command{gprbuild} command. This also works nicely |
2c1b72d7 AC |
2405 | with Annex E. |
2406 | ||
77aa62e7 AC |
2407 | @c --------------------------------------------- |
2408 | @node Define a build environment | |
2c1b72d7 | 2409 | @subsection Define a build environment |
77aa62e7 | 2410 | @c --------------------------------------------- |
2c1b72d7 | 2411 | |
0bd38d94 AC |
2412 | The environment variables at the time you launch @command{gprbuild} |
2413 | will influence the view these tools have of the project | |
4bb43ffb | 2414 | (PATH to find the compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the |
2c1b72d7 | 2415 | projects, environment variables that are referenced in project files |
bb304287 | 2416 | through the "external" built-in function, ...). Several command line switches |
2c1b72d7 AC |
2417 | can be used to override those (-X or -aP), but on some systems and |
2418 | with some projects, this might make the command line too long, and on | |
2419 | all systems often make it hard to read. | |
2420 | ||
2421 | An aggregate project can be used to set the environment for all | |
15a5de99 | 2422 | projects built through that aggregate. One of the nice aspects is that |
2c1b72d7 AC |
2423 | you can put the aggregate project under configuration management, and |
2424 | make sure all your user have a consistent environment when | |
2425 | building. The syntax looks like | |
2426 | ||
2427 | @smallexample @c projectfile | |
d77cfab2 AC |
2428 | aggregate @b{project} Agg @b{is} |
2429 | @b{for} Project_Files @b{use} ("A.gpr", "B.gpr"); | |
2430 | @b{for} Project_Path @b{use} ("../dir1", "../dir1/dir2"); | |
2431 | @b{for} External ("BUILD") @b{use} "PRODUCTION"; | |
2432 | ||
2433 | @b{package} Builder @b{is} | |
2434 | @b{for} Switches ("Ada") @b{use} ("-q"); | |
2435 | @b{end} Builder; | |
2436 | @b{end} Agg; | |
2c1b72d7 AC |
2437 | @end smallexample |
2438 | ||
2439 | One of the often requested features in projects is to be able to | |
bb304287 | 2440 | reference external variables in @code{with} declarations, as in |
2c1b72d7 AC |
2441 | |
2442 | @smallexample @c projectfile | |
d77cfab2 AC |
2443 | @b{with} @b{external}("SETUP") & "path/prj.gpr"; --@i{ ILLEGAL} |
2444 | @b{project} MyProject @b{is} | |
2c1b72d7 | 2445 | ... |
d77cfab2 | 2446 | @b{end} MyProject; |
2c1b72d7 AC |
2447 | @end smallexample |
2448 | ||
4887624e AC |
2449 | For various reasons, this is not allowed. But using aggregate projects provide |
2450 | an elegant solution. For instance, you could use a project file like: | |
2c1b72d7 AC |
2451 | |
2452 | @smallexample @c projectfile | |
d77cfab2 AC |
2453 | aggregate @b{project} Agg @b{is} |
2454 | @b{for} Project_Path @b{use} (@b{external}("SETUP") & "path"); | |
2455 | @b{for} Project_Files @b{use} ("myproject.gpr"); | |
2456 | @b{end} Agg; | |
2c1b72d7 | 2457 | |
d77cfab2 AC |
2458 | @b{with} "prj.gpr"; --@i{ searched on Agg'Project_Path} |
2459 | @b{project} MyProject @b{is} | |
2c1b72d7 | 2460 | ... |
d77cfab2 | 2461 | @b{end} MyProject; |
2c1b72d7 AC |
2462 | @end smallexample |
2463 | ||
77aa62e7 AC |
2464 | @c -------------------------------------------- |
2465 | @node Performance improvements in builder | |
2c1b72d7 | 2466 | @subsection Performance improvements in builder |
77aa62e7 | 2467 | @c -------------------------------------------- |
2c1b72d7 | 2468 | |
0bd38d94 AC |
2469 | The loading of aggregate projects is optimized in @command{gprbuild}, |
2470 | so that all files are searched for only once on the disk | |
2c1b72d7 | 2471 | (thus reducing the number of system calls and contributing to faster |
4887624e | 2472 | compilation times, especially on systems with sources on remote |
0bd38d94 | 2473 | servers). As part of the loading, @command{gprbuild} |
88de755d VC |
2474 | computes how and where a source file should be compiled, and even if it is |
2475 | found several times in the aggregated projects it will be compiled only | |
2c1b72d7 AC |
2476 | once. |
2477 | ||
2478 | Since there is no ambiguity as to which switches should be used, files | |
2479 | can be compiled in parallel (through the usual -j switch) and this can | |
2480 | be done while maximizing the use of CPUs (compared to launching | |
4bb43ffb | 2481 | multiple @command{gprbuild} and @command{gnatmake} commands in parallel). |
2c1b72d7 | 2482 | |
77aa62e7 AC |
2483 | @c ------------------------------------- |
2484 | @node Syntax of aggregate projects | |
2c1b72d7 | 2485 | @subsection Syntax of aggregate projects |
77aa62e7 | 2486 | @c ------------------------------------- |
2c1b72d7 AC |
2487 | |
2488 | An aggregate project follows the general syntax of project files. The | |
2489 | recommended extension is still @file{.gpr}. However, a special | |
2490 | @code{aggregate} qualifier must be put before the keyword | |
2491 | @code{project}. | |
2492 | ||
2493 | An aggregate project cannot @code{with} any other project (standard or | |
88de755d VC |
2494 | aggregate), except an abstract project which can be used to share attribute |
2495 | values. Also, aggregate projects cannot be extended or imported though a | |
2496 | @code{with} clause by any other project. Building other aggregate projects from | |
2497 | an aggregate project is done through the Project_Files attribute (see below). | |
2c1b72d7 AC |
2498 | |
2499 | An aggregate project does not have any source files directly (only | |
2500 | through other standard projects). Therefore a number of the standard | |
2501 | attributes and packages are forbidden in an aggregate project. Here is the | |
2502 | (non exhaustive) list: | |
2503 | ||
2504 | @itemize @bullet | |
2505 | @item Languages | |
735ca1b9 | 2506 | @item Source_Files, Source_List_File and other attributes dealing with |
2c1b72d7 AC |
2507 | list of sources. |
2508 | @item Source_Dirs, Exec_Dir and Object_Dir | |
2509 | @item Library_Dir, Library_Name and other library-related attributes | |
2510 | @item Main | |
2511 | @item Roots | |
2512 | @item Externally_Built | |
2513 | @item Inherit_Source_Path | |
2514 | @item Excluded_Source_Dirs | |
2515 | @item Locally_Removed_Files | |
735ca1b9 | 2516 | @item Excluded_Source_Files |
2c1b72d7 AC |
2517 | @item Excluded_Source_List_File |
2518 | @item Interfaces | |
2519 | @end itemize | |
2520 | ||
2521 | The only package that is authorized (albeit optional) is | |
2522 | Builder. Other packages (in particular Compiler, Binder and Linker) | |
4887624e | 2523 | are forbidden. |
2c1b72d7 | 2524 | |
4887624e | 2525 | The following three attributes can be used only in an aggregate project: |
2c1b72d7 AC |
2526 | |
2527 | @table @asis | |
2528 | @item @b{Project_Files}: | |
2529 | @cindex @code{Project_Files} | |
2530 | ||
2531 | This attribute is compulsory (or else we are not aggregating any project, | |
2532 | and thus not doing anything). It specifies a list of @file{.gpr} files | |
2533 | that are grouped in the aggregate. The list may be empty. The project | |
2534 | files can be either other aggregate projects, or standard projects. When | |
2535 | grouping standard projects, you can have both the root of a project tree | |
2536 | (and you do not need to specify all its imported projects), and any project | |
2537 | within the tree. | |
2538 | ||
2539 | Basically, the idea is to specify all those projects that have | |
ce20f35b | 2540 | main programs you want to build and link, or libraries you want to |
2c1b72d7 AC |
2541 | build. You can even specify projects that do not use the Main |
2542 | attribute nor the @code{Library_*} attributes, and the result will be to | |
2543 | build all their source files (not just the ones needed by other | |
2544 | projects). | |
2545 | ||
88de755d VC |
2546 | The file can include paths (absolute or relative). Paths are relative to |
2547 | the location of the aggregate project file itself (if you use a base name, | |
2548 | we expect to find the .gpr file in the same directory as the aggregate | |
2549 | project file). The environment variables @code{ADA_PROJECT_PATH}, | |
2550 | @code{GPR_PROJECT_PATH} and @code{GPR_PROJECT_PATH_FILE} are not used to find | |
2551 | the project files. The extension @file{.gpr} is mandatory, since this attribute | |
2552 | contains file names, not project names. | |
2c1b72d7 AC |
2553 | |
2554 | Paths can also include the @code{"*"} and @code{"**"} globbing patterns. The | |
2555 | latter indicates that any subdirectory (recursively) will be | |
2556 | searched for matching files. The latter (@code{"**"}) can only occur at the | |
2557 | last position in the directory part (ie @code{"a/**/*.gpr"} is supported, but | |
2558 | not @code{"**/a/*.gpr"}). Starting the pattern with @code{"**"} is equivalent | |
2559 | to starting with @code{"./**"}. | |
2560 | ||
2561 | For now, the pattern @code{"*"} is only allowed in the filename part, not | |
2562 | in the directory part. This is mostly for efficiency reasons to limit the | |
2563 | number of system calls that are needed. | |
2564 | ||
2565 | Here are a few valid examples: | |
2566 | ||
2567 | @smallexample @c projectfile | |
d77cfab2 AC |
2568 | @b{for} Project_Files @b{use} ("a.gpr", "subdir/b.gpr"); |
2569 | --@i{ two specific projects relative to the directory of agg.gpr} | |
2c1b72d7 | 2570 | |
d77cfab2 AC |
2571 | @b{for} Project_Files @b{use} ("**/*.gpr"); |
2572 | --@i{ all projects recursively} | |
2c1b72d7 AC |
2573 | @end smallexample |
2574 | ||
2575 | @item @b{Project_Path}: | |
2576 | @cindex @code{Project_Path} | |
2577 | ||
2578 | This attribute can be used to specify a list of directories in | |
bb304287 | 2579 | which to look for project files in @code{with} declarations. |
2c1b72d7 | 2580 | |
4887624e AC |
2581 | When you specify a project in Project_Files (say @code{x/y/a.gpr}), and |
2582 | @code{a.gpr} imports a project @code{b.gpr}, only @code{b.gpr} is searched in | |
2583 | the project path. @code{a.gpr} must be exactly at | |
2584 | @code{<dir of the aggregate>/x/y/a.gpr}. | |
2c1b72d7 AC |
2585 | |
2586 | This attribute, however, does not affect the search for the aggregated | |
2587 | project files specified with @code{Project_Files}. | |
2588 | ||
4887624e AC |
2589 | Each aggregate project has its own @code{Project_Path} (that is if |
2590 | @code{agg1.gpr} includes @code{agg2.gpr}, they can potentially both have a | |
2591 | different @code{Project_Path}). | |
6f5c2c4b AC |
2592 | |
2593 | This project path is defined as the concatenation, in that order, of: | |
2594 | ||
2595 | @itemize @bullet | |
2596 | @item the current directory; | |
2597 | @item followed by the command line -aP switches; | |
2598 | @item then the directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH environment | |
2599 | variables; | |
2600 | @item then the directories from the Project_Path attribute; | |
2601 | @item and finally the predefined directories. | |
2602 | @end itemize | |
2c1b72d7 AC |
2603 | |
2604 | In the example above, agg2.gpr's project path is not influenced by | |
2605 | the attribute agg1'Project_Path, nor is agg1 influenced by | |
2606 | agg2'Project_Path. | |
2607 | ||
2608 | This can potentially lead to errors. In the following example: | |
2609 | ||
2610 | @smallexample | |
2611 | +---------------+ +----------------+ | |
2612 | | Agg1.gpr |-=--includes--=-->| Agg2.gpr | | |
2613 | | 'project_path| | 'project_path | | |
2614 | | | | | | |
2615 | +---------------+ +----------------+ | |
2616 | : : | |
2617 | includes includes | |
2618 | : : | |
2619 | v v | |
2620 | +-------+ +---------+ | |
2621 | | P.gpr |<---------- withs --------| Q.gpr | | |
2622 | +-------+---------\ +---------+ | |
2623 | | | | |
2624 | withs | | |
2625 | | | | |
2626 | v v | |
2627 | +-------+ +---------+ | |
2628 | | R.gpr | | R'.gpr | | |
2629 | +-------+ +---------+ | |
2630 | @end smallexample | |
2631 | ||
2632 | When looking for p.gpr, both aggregates find the same physical file on | |
2633 | the disk. However, it might happen that with their different project | |
2634 | paths, both aggregate projects would in fact find a different r.gpr. | |
2635 | Since we have a common project (p.gpr) "with"ing two different r.gpr, | |
2636 | this will be reported as an error by the builder. | |
2637 | ||
2638 | Directories are relative to the location of the aggregate project file. | |
2639 | ||
4887624e | 2640 | Example: |
2c1b72d7 AC |
2641 | |
2642 | @smallexample @c projectfile | |
d77cfab2 | 2643 | @b{for} Project_Path @b{use} ("/usr/local/gpr", "gpr/"); |
2c1b72d7 AC |
2644 | @end smallexample |
2645 | ||
2646 | @item @b{External}: | |
2647 | @cindex @code{External} | |
2648 | ||
2649 | This attribute can be used to set the value of environment | |
bb304287 | 2650 | variables as retrieved through the @code{external} function |
2c1b72d7 AC |
2651 | in projects. It does not affect the environment variables |
2652 | themselves (so for instance you cannot use it to change the value | |
2653 | of your PATH as seen from the spawned compiler). | |
2654 | ||
2655 | This attribute affects the external values as seen in the rest of | |
7e4f00b4 | 2656 | the aggregate project, and in the aggregated projects. |
2c1b72d7 AC |
2657 | |
2658 | The exact value of external a variable comes from one of three | |
2659 | sources (each level overrides the previous levels): | |
2660 | ||
2661 | @itemize @bullet | |
2662 | @item An External attribute in aggregate project, for instance | |
2663 | @code{for External ("BUILD_MODE") use "DEBUG"}; | |
2664 | ||
2665 | @item Environment variables | |
2666 | ||
2667 | These override the value given by the attribute, so that | |
2668 | users can override the value set in the (presumably shared | |
4887624e | 2669 | with others team members) aggregate project. |
2c1b72d7 | 2670 | |
0bd38d94 | 2671 | @item The -X command line switch to @command{gprbuild} |
2c1b72d7 AC |
2672 | |
2673 | This always takes precedence. | |
2674 | ||
2675 | @end itemize | |
2676 | ||
2677 | This attribute is only taken into account in the main aggregate | |
0bd38d94 AC |
2678 | project (i.e. the one specified on the command line to @command{gprbuild}), |
2679 | and ignored in other aggregate projects. It is invalid | |
2c1b72d7 AC |
2680 | in standard projects. |
2681 | The goal is to have a consistent value in all | |
15a5de99 | 2682 | projects that are built through the aggregate, which would not |
2c1b72d7 AC |
2683 | be the case in the diamond case: A groups the aggregate |
2684 | projects B and C, which both (either directly or indirectly) | |
2685 | build the project P. If B and C could set different values for | |
2686 | the environment variables, we would have two different views of | |
2687 | P, which in particular might impact the list of source files in P. | |
2688 | ||
2689 | @end table | |
2690 | ||
77aa62e7 AC |
2691 | @c ---------------------------------------------- |
2692 | @node package Builder in aggregate projects | |
2c1b72d7 | 2693 | @subsection package Builder in aggregate projects |
77aa62e7 | 2694 | @c ---------------------------------------------- |
2c1b72d7 AC |
2695 | |
2696 | As we mentioned before, only the package Builder can be specified in | |
2697 | an aggregate project. In this package, only the following attributes | |
2698 | are valid: | |
2699 | ||
2700 | @table @asis | |
d77cfab2 AC |
2701 | @item @b{Switches}: |
2702 | @cindex @code{Switches} | |
0bd38d94 AC |
2703 | This attribute gives the list of switches to use for @command{gprbuild}. |
2704 | Because no mains can be specified for aggregate projects, the only possible | |
2705 | index for attribute @code{Switches} is @code{others}. All other indexes will | |
2706 | be ignored. | |
2707 | ||
2708 | Example: | |
2c1b72d7 AC |
2709 | |
2710 | @smallexample @c projectfile | |
d77cfab2 | 2711 | @b{for} Switches (@b{others}) @b{use} ("-v", "-k", "-j8"); |
2c1b72d7 AC |
2712 | @end smallexample |
2713 | ||
2714 | These switches are only read from the main aggregate project (the | |
2715 | one passed on the command line), and ignored in all other aggregate | |
2716 | projects or projects. | |
2717 | ||
2718 | It can only contain builder switches, not compiler switches. | |
2719 | ||
2720 | @item @b{Global_Compilation_Switches} | |
2721 | @cindex @code{Global_Compilation_Switches} | |
2722 | ||
2723 | This attribute gives the list of compiler switches for the various | |
2724 | languages. For instance, | |
2725 | ||
2726 | @smallexample @c projectfile | |
d77cfab2 AC |
2727 | @b{for} Global_Compilation_Switches ("Ada") @b{use} ("O1", "-g"); |
2728 | @b{for} Global_Compilation_Switches ("C") @b{use} ("-O2"); | |
2c1b72d7 AC |
2729 | @end smallexample |
2730 | ||
2731 | This attribute is only taken into account in the aggregate project | |
2732 | specified on the command line, not in other aggregate projects. | |
2733 | ||
2734 | In the projects grouped by that aggregate, the attribute | |
2735 | Builder.Global_Compilation_Switches is also ignored. However, the | |
2736 | attribute Compiler.Default_Switches will be taken into account (but | |
2737 | that of the aggregate have higher priority). The attribute | |
2738 | Compiler.Switches is also taken into account and can be used to | |
2739 | override the switches for a specific file. As a result, it always | |
2740 | has priority. | |
2741 | ||
2742 | The rules are meant to avoid ambiguities when compiling. For | |
2743 | instance, aggregate project Agg groups the projects A and B, that | |
2744 | both depend on C. Here is an extra for all of these projects: | |
2745 | ||
2746 | @smallexample @c projectfile | |
d77cfab2 AC |
2747 | aggregate @b{project} Agg @b{is} |
2748 | @b{for} Project_Files @b{use} ("a.gpr", "b.gpr"); | |
2749 | @b{package} Builder @b{is} | |
2750 | @b{for} Global_Compilation_Switches ("Ada") @b{use} ("-O2"); | |
2751 | @b{end} Builder; | |
2752 | @b{end} Agg; | |
2753 | ||
2754 | @b{with} "c.gpr"; | |
2755 | @b{project} A @b{is} | |
2756 | @b{package} Builder @b{is} | |
2757 | @b{for} Global_Compilation_Switches ("Ada") @b{use} ("-O1"); | |
2758 | --@i{ ignored} | |
2759 | @b{end} Builder; | |
2760 | ||
2761 | @b{package} Compiler @b{is} | |
2762 | @b{for} Default_Switches ("Ada") | |
2763 | @b{use} ("-O1", "-g"); | |
2764 | @b{for} Switches ("a_file1.adb") | |
2765 | @b{use} ("-O0"); | |
2766 | @b{end} Compiler; | |
2767 | @b{end} A; | |
2768 | ||
2769 | @b{with} "c.gpr"; | |
2770 | @b{project} B @b{is} | |
2771 | @b{package} Compiler @b{is} | |
2772 | @b{for} Default_Switches ("Ada") @b{use} ("-O0"); | |
2773 | @b{end} Compiler; | |
2774 | @b{end} B; | |
2775 | ||
2776 | @b{project} C @b{is} | |
2777 | @b{package} Compiler @b{is} | |
2778 | @b{for} Default_Switches ("Ada") | |
2779 | @b{use} ("-O3", | |
2780 | "-gnatn"); | |
2781 | @b{for} Switches ("c_file1.adb") | |
2782 | @b{use} ("-O0", "-g"); | |
2783 | @b{end} Compiler; | |
2784 | @b{end} C; | |
2c1b72d7 AC |
2785 | @end smallexample |
2786 | ||
2787 | then the following switches are used: | |
2788 | ||
2789 | @itemize @bullet | |
2790 | @item all files from project A except a_file1.adb are compiled | |
d77cfab2 | 2791 | with "-O2 -g", since the aggregate project has priority. |
2c1b72d7 | 2792 | @item the file a_file1.adb is compiled with |
d77cfab2 | 2793 | "-O0", since the Compiler.Switches has priority |
2c1b72d7 | 2794 | @item all files from project B are compiled with |
d77cfab2 AC |
2795 | "-O2", since the aggregate project has priority |
2796 | @item all files from C are compiled with "-O2 -gnatn", except for | |
2797 | c_file1.adb which is compiled with "-O0 -g" | |
2c1b72d7 AC |
2798 | @end itemize |
2799 | ||
2800 | Even though C is seen through two paths (through A and through | |
2801 | B), the switches used by the compiler are unambiguous. | |
2802 | ||
2803 | @item @b{Global_Configuration_Pragmas} | |
2804 | @cindex @code{Global_Configuration_Pragmas} | |
2805 | ||
2806 | This attribute can be used to specify a file containing | |
0bd38d94 | 2807 | configuration pragmas, to be passed to the Ada compiler. Since we |
2c1b72d7 AC |
2808 | ignore the package Builder in other aggregate projects and projects, |
2809 | only those pragmas defined in the main aggregate project will be | |
2810 | taken into account. | |
2811 | ||
2812 | Projects can locally add to those by using the | |
2813 | @code{Compiler.Local_Configuration_Pragmas} attribute if they need. | |
2814 | ||
0bd38d94 AC |
2815 | @item @b{Global_Config_File} |
2816 | @cindex @code{Global_Config_File} | |
2817 | ||
2818 | This attribute, indexed with a language name, can be used to specify a config | |
2819 | when compiling sources of the language. For Ada, these files are configuration | |
2820 | pragmas files. | |
2821 | ||
2c1b72d7 AC |
2822 | @end table |
2823 | ||
15a5de99 | 2824 | For projects that are built through the aggregate, the package Builder |
2c1b72d7 | 2825 | is ignored, except for the Executable attribute which specifies the |
ce20f35b | 2826 | name of the executables resulting from the link of the main programs, and |
2c1b72d7 AC |
2827 | for the Executable_Suffix. |
2828 | ||
5415acbd AC |
2829 | @c --------------------------------------------- |
2830 | @node Aggregate Library Projects | |
2831 | @section Aggregate Library Projects | |
2832 | @c --------------------------------------------- | |
2833 | ||
2834 | @noindent | |
2835 | ||
2836 | Aggregate library projects make it possible to build a single library | |
2837 | using object files built using other standard or library | |
2838 | projects. This gives the flexibility to describe an application as | |
2839 | having multiple modules (a GUI, database access, ...) using different | |
2840 | project files (so possibly built with different compiler options) and | |
2841 | yet create a single library (static or relocatable) out of the | |
2842 | corresponding object files. | |
2843 | ||
77aa62e7 AC |
2844 | @menu |
2845 | * Building aggregate library projects:: | |
2846 | * Syntax of aggregate library projects:: | |
2847 | @end menu | |
2848 | ||
2849 | @c --------------------------------------------- | |
2850 | @node Building aggregate library projects | |
5415acbd | 2851 | @subsection Building aggregate library projects |
77aa62e7 | 2852 | @c --------------------------------------------- |
5415acbd AC |
2853 | |
2854 | For example, we can define an aggregate project Agg that groups A, B | |
2855 | and C: | |
2856 | ||
2857 | @smallexample @c projectfile | |
d77cfab2 AC |
2858 | aggregate library @b{project} Agg @b{is} |
2859 | @b{for} Project_Files @b{use} ("a.gpr", "b.gpr", "c.gpr"); | |
2860 | @b{for} Library_Name @b{use} ("agg"); | |
2861 | @b{for} Library_Dir @b{use} ("lagg"); | |
2862 | @b{end} Agg; | |
5415acbd AC |
2863 | @end smallexample |
2864 | ||
2865 | Then, when you build with: | |
2866 | ||
2867 | @smallexample | |
2868 | gprbuild agg.gpr | |
2869 | @end smallexample | |
2870 | ||
2871 | This will build all units from projects A, B and C and will create a | |
4887624e | 2872 | static library named @file{libagg.a} in the @file{lagg} |
5415acbd AC |
2873 | directory. An aggregate library project has the same set of |
2874 | restriction as a standard library project. | |
2875 | ||
41c79d60 | 2876 | Note that a shared aggregate library project cannot aggregate a |
5415acbd AC |
2877 | static library project. In platforms where a compiler option is |
2878 | required to create relocatable object files, a Builder package in the | |
2879 | aggregate library project may be used: | |
2880 | ||
2881 | @smallexample @c projectfile | |
d77cfab2 AC |
2882 | aggregate library @b{project} Agg @b{is} |
2883 | @b{for} Project_Files @b{use} ("a.gpr", "b.gpr", "c.gpr"); | |
2884 | @b{for} Library_Name @b{use} ("agg"); | |
2885 | @b{for} Library_Dir @b{use} ("lagg"); | |
2886 | @b{for} Library_Kind @b{use} "relocatable"; | |
2887 | ||
2888 | @b{package} Builder @b{is} | |
2889 | @b{for} Global_Compilation_Switches ("Ada") @b{use} ("-fPIC"); | |
2890 | @b{end} Builder; | |
2891 | @b{end} Agg; | |
5415acbd AC |
2892 | @end smallexample |
2893 | ||
2894 | With the above aggregate library Builder package, the @code{-fPIC} | |
2895 | option will be passed to the compiler when building any source code | |
2896 | from projects @file{a.gpr}, @file{b.gpr} and @file{c.gpr}. | |
2897 | ||
77aa62e7 AC |
2898 | @c --------------------------------------------- |
2899 | @node Syntax of aggregate library projects | |
5415acbd | 2900 | @subsection Syntax of aggregate library projects |
77aa62e7 | 2901 | @c --------------------------------------------- |
5415acbd AC |
2902 | |
2903 | An aggregate library project follows the general syntax of project | |
2904 | files. The recommended extension is still @file{.gpr}. However, a special | |
2905 | @code{aggregate library} qualifier must be put before the keyword | |
2906 | @code{project}. | |
2907 | ||
2908 | An aggregate library project cannot @code{with} any other project | |
2909 | (standard or aggregate), except an abstract project which can be used | |
2910 | to share attribute values. | |
2911 | ||
2912 | An aggregate library project does not have any source files directly (only | |
2913 | through other standard projects). Therefore a number of the standard | |
2914 | attributes and packages are forbidden in an aggregate library | |
2915 | project. Here is the (non exhaustive) list: | |
2916 | ||
2917 | @itemize @bullet | |
2918 | @item Languages | |
2919 | @item Source_Files, Source_List_File and other attributes dealing with | |
2920 | list of sources. | |
2921 | @item Source_Dirs, Exec_Dir and Object_Dir | |
5415acbd AC |
2922 | @item Main |
2923 | @item Roots | |
2924 | @item Externally_Built | |
2925 | @item Inherit_Source_Path | |
2926 | @item Excluded_Source_Dirs | |
2927 | @item Locally_Removed_Files | |
2928 | @item Excluded_Source_Files | |
2929 | @item Excluded_Source_List_File | |
2930 | @item Interfaces | |
2931 | @end itemize | |
2932 | ||
2933 | The only package that is authorized (albeit optional) is Builder. | |
2934 | ||
2935 | The Project_Files attribute (See @pxref{Aggregate Projects}) is used to | |
2936 | described the aggregated projects whose object files have to be | |
88de755d VC |
2937 | included into the aggregate library. The environment variables |
2938 | @code{ADA_PROJECT_PATH}, @code{GPR_PROJECT_PATH} and | |
2939 | @code{GPR_PROJECT_PATH_FILE} are not used to find the project files. | |
5415acbd | 2940 | |
b2cacbfe AC |
2941 | @c --------------------------------------------- |
2942 | @node Project File Reference | |
2943 | @section Project File Reference | |
2944 | @c --------------------------------------------- | |
2945 | ||
2946 | @noindent | |
2947 | This section describes the syntactic structure of project files, the various | |
2948 | constructs that can be used. Finally, it ends with a summary of all available | |
2949 | attributes. | |
2950 | ||
2951 | @menu | |
2952 | * Project Declaration:: | |
2953 | * Qualified Projects:: | |
2954 | * Declarations:: | |
2955 | * Packages:: | |
2956 | * Expressions:: | |
2957 | * External Values:: | |
2958 | * Typed String Declaration:: | |
2959 | * Variables:: | |
b671e31b | 2960 | * Case Constructions:: |
b2cacbfe | 2961 | * Attributes:: |
b2cacbfe AC |
2962 | @end menu |
2963 | ||
2964 | @c --------------------------------------------- | |
2965 | @node Project Declaration | |
2966 | @subsection Project Declaration | |
2967 | @c --------------------------------------------- | |
2968 | ||
2969 | @noindent | |
2970 | Project files have an Ada-like syntax. The minimal project file is: | |
2971 | ||
2972 | @smallexample @c projectfile | |
2973 | @group | |
d77cfab2 AC |
2974 | @b{project} Empty @b{is} |
2975 | @b{end} Empty; | |
b2cacbfe AC |
2976 | @end group |
2977 | @end smallexample | |
2978 | ||
2979 | @noindent | |
2980 | The identifier @code{Empty} is the name of the project. | |
2981 | This project name must be present after the reserved | |
2982 | word @code{end} at the end of the project file, followed by a semi-colon. | |
2983 | ||
308e6f3a | 2984 | @b{Identifiers} (i.e.@: the user-defined names such as project or variable names) |
b2cacbfe AC |
2985 | have the same syntax as Ada identifiers: they must start with a letter, |
2986 | and be followed by zero or more letters, digits or underscore characters; | |
2987 | it is also illegal to have two underscores next to each other. Identifiers | |
2988 | are always case-insensitive ("Name" is the same as "name"). | |
2989 | ||
2990 | @smallexample | |
2991 | simple_name ::= identifier | |
2992 | name ::= simple_name @{ . simple_name @} | |
2993 | @end smallexample | |
2994 | ||
2995 | @noindent | |
2996 | @b{Strings} are used for values of attributes or as indexes for these | |
2997 | attributes. They are in general case sensitive, except when noted | |
2998 | otherwise (in particular, strings representing file names will be case | |
2999 | insensitive on some systems, so that "file.adb" and "File.adb" both | |
3000 | represent the same file). | |
3001 | ||
3002 | @b{Reserved words} are the same as for standard Ada 95, and cannot | |
3003 | be used for identifiers. In particular, the following words are currently | |
3004 | used in project files, but others could be added later on. In bold are the | |
3005 | extra reserved words in project files: @code{all, at, case, end, for, is, | |
3006 | limited, null, others, package, renames, type, use, when, with, @b{extends}, | |
3007 | @b{external}, @b{project}}. | |
3008 | ||
3009 | @b{Comments} in project files have the same syntax as in Ada, two consecutive | |
3010 | hyphens through the end of the line. | |
3011 | ||
3012 | A project may be an @b{independent project}, entirely defined by a single | |
3013 | project file. Any source file in an independent project depends only | |
3014 | on the predefined library and other source files in the same project. | |
3015 | But a project may also depend on other projects, either by importing them | |
3016 | through @b{with clauses}, or by @b{extending} at most one other project. Both | |
3017 | types of dependency can be used in the same project. | |
3018 | ||
3019 | A path name denotes a project file. It can be absolute or relative. | |
3020 | An absolute path name includes a sequence of directories, in the syntax of | |
3021 | the host operating system, that identifies uniquely the project file in the | |
3022 | file system. A relative path name identifies the project file, relative | |
3023 | to the directory that contains the current project, or relative to a | |
3024 | directory listed in the environment variables ADA_PROJECT_PATH and | |
3025 | GPR_PROJECT_PATH. Path names are case sensitive if file names in the host | |
3026 | operating system are case sensitive. As a special case, the directory | |
3027 | separator can always be "/" even on Windows systems, so that project files | |
3028 | can be made portable across architectures. | |
4887624e | 3029 | The syntax of the environment variables ADA_PROJECT_PATH and |
b2cacbfe AC |
3030 | GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and |
3031 | semicolons on Windows. | |
3032 | ||
3033 | A given project name can appear only once in a context clause. | |
3034 | ||
3035 | It is illegal for a project imported by a context clause to refer, directly | |
3036 | or indirectly, to the project in which this context clause appears (the | |
4887624e | 3037 | dependency graph cannot contain cycles), except when one of the with clauses |
b2cacbfe AC |
3038 | in the cycle is a @b{limited with}. |
3039 | @c ??? Need more details here | |
3040 | ||
3041 | @smallexample @c projectfile | |
d77cfab2 AC |
3042 | @b{with} "other_project.gpr"; |
3043 | @b{project} My_Project @b{extends} "extended.gpr" @b{is} | |
3044 | @b{end} My_Project; | |
b2cacbfe AC |
3045 | @end smallexample |
3046 | ||
3047 | @noindent | |
3048 | These dependencies form a @b{directed graph}, potentially cyclic when using | |
4887624e | 3049 | @b{limited with}. The subgraph reflecting the @b{extends} relations is a tree. |
b2cacbfe AC |
3050 | |
3051 | A project's @b{immediate sources} are the source files directly defined by | |
3052 | that project, either implicitly by residing in the project source directories, | |
3053 | or explicitly through any of the source-related attributes. | |
4887624e AC |
3054 | More generally, a project's @b{sources} are the immediate sources of the |
3055 | project together with the immediate sources (unless overridden) of any project | |
3056 | on which it depends directly or indirectly. | |
b2cacbfe AC |
3057 | |
3058 | A @b{project hierarchy} can be created, where projects are children of | |
3059 | other projects. The name of such a child project must be @code{Parent.Child}, | |
3060 | where @code{Parent} is the name of the parent project. In particular, this | |
3061 | makes all @code{with} clauses of the parent project automatically visible | |
3062 | in the child project. | |
3063 | ||
3064 | @smallexample | |
3065 | project ::= context_clause project_declaration | |
3066 | ||
3067 | context_clause ::= @{with_clause@} | |
3068 | with_clause ::= @i{with} path_name @{ , path_name @} ; | |
3069 | path_name ::= string_literal | |
3070 | ||
3071 | project_declaration ::= simple_project_declaration | project_extension | |
3072 | simple_project_declaration ::= | |
3073 | @i{project} @i{<project_>}name @i{is} | |
3074 | @{declarative_item@} | |
3075 | @i{end} <project_>simple_name; | |
3076 | @end smallexample | |
3077 | ||
3078 | @c --------------------------------------------- | |
3079 | @node Qualified Projects | |
3080 | @subsection Qualified Projects | |
3081 | @c --------------------------------------------- | |
3082 | ||
3083 | @noindent | |
3084 | Before the reserved @code{project}, there may be one or two @b{qualifiers}, that | |
3085 | is identifiers or reserved words, to qualify the project. | |
3086 | The current list of qualifiers is: | |
3087 | ||
3088 | @table @asis | |
3089 | @item @b{abstract}: qualifies a project with no sources. Such a | |
3090 | project must either have no declaration of attributes @code{Source_Dirs}, | |
3091 | @code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of | |
3092 | @code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared | |
3093 | as empty. If it extends another project, the project it extends must also be a | |
3094 | qualified abstract project. | |
3095 | @item @b{standard}: a standard project is a non library project with sources. | |
3096 | This is the default (implicit) qualifier. | |
8c18a165 AC |
3097 | @item @b{aggregate}: a project whose sources are aggregated from other |
3098 | project files. | |
3099 | @item @b{aggregate library}: a library whose sources are aggregated | |
3100 | from other project or library project files. | |
b2cacbfe AC |
3101 | @item @b{library}: a library project must declare both attributes |
3102 | @code{Library_Name} and @code{Library_Dir}. | |
3103 | @item @b{configuration}: a configuration project cannot be in a project tree. | |
4bb43ffb | 3104 | It describes compilers and other tools to @command{gprbuild}. |
b2cacbfe AC |
3105 | @end table |
3106 | ||
b2cacbfe AC |
3107 | @c --------------------------------------------- |
3108 | @node Declarations | |
3109 | @subsection Declarations | |
3110 | @c --------------------------------------------- | |
3111 | ||
3112 | @noindent | |
3113 | Declarations introduce new entities that denote types, variables, attributes, | |
3114 | and packages. Some declarations can only appear immediately within a project | |
3115 | declaration. Others can appear within a project or within a package. | |
3116 | ||
3117 | @smallexample | |
3118 | declarative_item ::= simple_declarative_item | |
3119 | | typed_string_declaration | |
3120 | | package_declaration | |
3121 | ||
3122 | simple_declarative_item ::= variable_declaration | |
3123 | | typed_variable_declaration | |
3124 | | attribute_declaration | |
3125 | | case_construction | |
3126 | | empty_declaration | |
3127 | ||
3128 | empty_declaration ::= @i{null} ; | |
3129 | @end smallexample | |
3130 | ||
3131 | @noindent | |
3132 | An empty declaration is allowed anywhere a declaration is allowed. It has | |
3133 | no effect. | |
3134 | ||
3135 | @c --------------------------------------------- | |
3136 | @node Packages | |
3137 | @subsection Packages | |
3138 | @c --------------------------------------------- | |
3139 | ||
3140 | @noindent | |
3141 | A project file may contain @b{packages}, that group attributes (typically | |
3142 | all the attributes that are used by one of the GNAT tools). | |
3143 | ||
3144 | A package with a given name may only appear once in a project file. | |
3145 | The following packages are currently supported in project files | |
3146 | (See @pxref{Attributes} for the list of attributes that each can contain). | |
3147 | ||
3148 | @table @code | |
3149 | @item Binder | |
3150 | This package specifies characteristics useful when invoking the binder either | |
3151 | directly via the @command{gnat} driver or when using a builder such as | |
3152 | @command{gnatmake} or @command{gprbuild}. @xref{Main Subprograms}. | |
3153 | @item Builder | |
3154 | This package specifies the compilation options used when building an | |
3155 | executable or a library for a project. Most of the options should be | |
3156 | set in one of @code{Compiler}, @code{Binder} or @code{Linker} packages, | |
3157 | but there are some general options that should be defined in this | |
3158 | package. @xref{Main Subprograms}, and @pxref{Executable File Names} in | |
3159 | particular. | |
1037b0f4 | 3160 | @ifclear FSFEDITION |
b2cacbfe AC |
3161 | @item Check |
3162 | This package specifies the options used when calling the checking tool | |
3163 | @command{gnatcheck} via the @command{gnat} driver. Its attribute | |
3164 | @b{Default_Switches} has the same semantics as for the package | |
3165 | @code{Builder}. The first string should always be @code{-rules} to specify | |
3166 | that all the other options belong to the @code{-rules} section of the | |
3167 | parameters to @command{gnatcheck}. | |
1037b0f4 | 3168 | @end ifclear |
b671e31b VC |
3169 | @item Clean |
3170 | This package specifies the options used when cleaning a project or a project | |
3171 | tree using the tools @command{gnatclean} or @command{gprclean}. | |
b2cacbfe AC |
3172 | @item Compiler |
3173 | This package specifies the compilation options used by the compiler for | |
3174 | each languages. @xref{Tools Options in Project Files}. | |
3175 | @item Cross_Reference | |
3176 | This package specifies the options used when calling the library tool | |
3177 | @command{gnatxref} via the @command{gnat} driver. Its attributes | |
d77cfab2 | 3178 | @b{Default_Switches} and @b{Switches} have the same semantics as for the |
b2cacbfe | 3179 | package @code{Builder}. |
1037b0f4 | 3180 | @ifclear FSFEDITION |
b2cacbfe AC |
3181 | @item Eliminate |
3182 | This package specifies the options used when calling the tool | |
3183 | @command{gnatelim} via the @command{gnat} driver. Its attributes | |
d77cfab2 | 3184 | @b{Default_Switches} and @b{Switches} have the same semantics as for the |
b2cacbfe | 3185 | package @code{Builder}. |
1037b0f4 | 3186 | @end ifclear |
b2cacbfe AC |
3187 | @item Finder |
3188 | This package specifies the options used when calling the search tool | |
3189 | @command{gnatfind} via the @command{gnat} driver. Its attributes | |
d77cfab2 | 3190 | @b{Default_Switches} and @b{Switches} have the same semantics as for the |
b2cacbfe | 3191 | package @code{Builder}. |
d77cfab2 | 3192 | @item Gnatls |
637a41a5 AC |
3193 | This package specifies the options to use when invoking @command{gnatls} |
3194 | via the @command{gnat} driver. | |
1037b0f4 | 3195 | @ifclear FSFEDITION |
d77cfab2 | 3196 | @item Gnatstub |
b2cacbfe AC |
3197 | This package specifies the options used when calling the tool |
3198 | @command{gnatstub} via the @command{gnat} driver. Its attributes | |
d77cfab2 | 3199 | @b{Default_Switches} and @b{Switches} have the same semantics as for the |
b2cacbfe | 3200 | package @code{Builder}. |
1037b0f4 | 3201 | @end ifclear |
b2cacbfe AC |
3202 | @item IDE |
3203 | This package specifies the options used when starting an integrated | |
3204 | development environment, for instance @command{GPS} or @command{Gnatbench}. | |
df378148 AC |
3205 | @item Install |
3206 | This package specifies the options used when installing a project | |
3207 | with @command{gprinstall}. @xref{Installation}. | |
b2cacbfe AC |
3208 | @item Linker |
3209 | This package specifies the options used by the linker. | |
3210 | @xref{Main Subprograms}. | |
1037b0f4 | 3211 | @ifclear FSFEDITION |
b2cacbfe AC |
3212 | @item Metrics |
3213 | This package specifies the options used when calling the tool | |
3214 | @command{gnatmetric} via the @command{gnat} driver. Its attributes | |
d77cfab2 | 3215 | @b{Default_Switches} and @b{Switches} have the same semantics as for the |
b2cacbfe | 3216 | package @code{Builder}. |
1037b0f4 | 3217 | @end ifclear |
b2cacbfe AC |
3218 | @item Naming |
3219 | This package specifies the naming conventions that apply | |
3220 | to the source files in a project. In particular, these conventions are | |
3221 | used to automatically find all source files in the source directories, | |
3222 | or given a file name to find out its language for proper processing. | |
3223 | @xref{Naming Schemes}. | |
1037b0f4 | 3224 | @ifclear FSFEDITION |
b2cacbfe AC |
3225 | @item Pretty_Printer |
3226 | This package specifies the options used when calling the formatting tool | |
3227 | @command{gnatpp} via the @command{gnat} driver. Its attributes | |
d77cfab2 | 3228 | @b{Default_Switches} and @b{Switches} have the same semantics as for the |
b2cacbfe | 3229 | package @code{Builder}. |
1037b0f4 | 3230 | @end ifclear |
b671e31b VC |
3231 | @item Remote |
3232 | This package is used by @command{gprbuild} to describe how distributed | |
3233 | compilation should be done. | |
b2cacbfe AC |
3234 | @item Stack |
3235 | This package specifies the options used when calling the tool | |
3236 | @command{gnatstack} via the @command{gnat} driver. Its attributes | |
d77cfab2 | 3237 | @b{Default_Switches} and @b{Switches} have the same semantics as for the |
b2cacbfe AC |
3238 | package @code{Builder}. |
3239 | @item Synchronize | |
3240 | This package specifies the options used when calling the tool | |
3241 | @command{gnatsync} via the @command{gnat} driver. | |
3242 | ||
3243 | @end table | |
3244 | ||
3245 | In its simplest form, a package may be empty: | |
3246 | ||
3247 | @smallexample @c projectfile | |
3248 | @group | |
d77cfab2 AC |
3249 | @b{project} Simple @b{is} |
3250 | @b{package} Builder @b{is} | |
3251 | @b{end} Builder; | |
3252 | @b{end} Simple; | |
b2cacbfe AC |
3253 | @end group |
3254 | @end smallexample | |
3255 | ||
3256 | @noindent | |
3257 | A package may contain @b{attribute declarations}, | |
3258 | @b{variable declarations} and @b{case constructions}, as will be | |
3259 | described below. | |
3260 | ||
3261 | When there is ambiguity between a project name and a package name, | |
3262 | the name always designates the project. To avoid possible confusion, it is | |
3263 | always a good idea to avoid naming a project with one of the | |
3264 | names allowed for packages or any name that starts with @code{gnat}. | |
3265 | ||
3266 | A package can also be defined by a @b{renaming declaration}. The new package | |
3267 | renames a package declared in a different project file, and has the same | |
3268 | attributes as the package it renames. The name of the renamed package | |
3269 | must be the same as the name of the renaming package. The project must | |
3270 | contain a package declaration with this name, and the project | |
3271 | must appear in the context clause of the current project, or be its parent | |
3272 | project. It is not possible to add or override attributes to the renaming | |
f2e7ec10 AC |
3273 | project. If you need to do so, you should use an @b{extending declaration} |
3274 | (see below). | |
b2cacbfe AC |
3275 | |
3276 | Packages that are renamed in other project files often come from project files | |
3277 | that have no sources: they are just used as templates. Any modification in the | |
3278 | template will be reflected automatically in all the project files that rename | |
3279 | a package from the template. This is a very common way to share settings | |
3280 | between projects. | |
3281 | ||
f2e7ec10 AC |
3282 | Finally, a package can also be defined by an @b{extending declaration}. This is |
3283 | similar to a @b{renaming declaration}, except that it is possible to add or | |
3284 | override attributes. | |
3285 | ||
b2cacbfe | 3286 | @smallexample |
f2e7ec10 | 3287 | package_declaration ::= package_spec | package_renaming | package_extension |
b2cacbfe AC |
3288 | package_spec ::= |
3289 | @i{package} @i{<package_>}simple_name @i{is} | |
3290 | @{simple_declarative_item@} | |
3291 | @i{end} package_identifier ; | |
3292 | package_renaming ::== | |
3293 | @i{package} @i{<package_>}simple_name @i{renames} @i{<project_>}simple_name.package_identifier ; | |
f2e7ec10 AC |
3294 | package_extension ::== |
3295 | @i{package} @i{<package_>}simple_name @i{extends} @i{<project_>}simple_name.package_identifier @i{is} | |
3296 | @{simple_declarative_item@} | |
3297 | @i{end} package_identifier ; | |
b2cacbfe AC |
3298 | @end smallexample |
3299 | ||
3300 | @c --------------------------------------------- | |
3301 | @node Expressions | |
3302 | @subsection Expressions | |
3303 | @c --------------------------------------------- | |
3304 | ||
3305 | @noindent | |
3306 | An expression is any value that can be assigned to an attribute or a | |
308e6f3a | 3307 | variable. It is either a literal value, or a construct requiring runtime |
b2cacbfe AC |
3308 | computation by the project manager. In a project file, the computed value of |
3309 | an expression is either a string or a list of strings. | |
3310 | ||
3311 | A string value is one of: | |
3312 | @itemize @bullet | |
3313 | @item A literal string, for instance @code{"comm/my_proj.gpr"} | |
3314 | @item The name of a variable that evaluates to a string (@pxref{Variables}) | |
3315 | @item The name of an attribute that evaluates to a string (@pxref{Attributes}) | |
3316 | @item An external reference (@pxref{External Values}) | |
3317 | @item A concatenation of the above, as in @code{"prefix_" & Var}. | |
3318 | ||
3319 | @end itemize | |
3320 | ||
3321 | @noindent | |
3322 | A list of strings is one of the following: | |
3323 | ||
3324 | @itemize @bullet | |
3325 | @item A parenthesized comma-separated list of zero or more string expressions, for | |
3326 | instance @code{(File_Name, "gnat.adc", File_Name & ".orig")} or @code{()}. | |
3327 | @item The name of a variable that evaluates to a list of strings | |
3328 | @item The name of an attribute that evaluates to a list of strings | |
3329 | @item A concatenation of a list of strings and a string (as defined above), for | |
3330 | instance @code{("A", "B") & "C"} | |
3331 | @item A concatenation of two lists of strings | |
3332 | ||
3333 | @end itemize | |
3334 | ||
3335 | @noindent | |
3336 | The following is the grammar for expressions | |
3337 | ||
3338 | @smallexample | |
3339 | string_literal ::= "@{string_element@}" -- Same as Ada | |
3340 | string_expression ::= string_literal | |
3341 | | @i{variable_}name | |
3342 | | external_value | |
3343 | | attribute_reference | |
3344 | | ( string_expression @{ & string_expression @} ) | |
3345 | string_list ::= ( string_expression @{ , string_expression @} ) | |
3346 | | @i{string_variable}_name | |
3347 | | @i{string_}attribute_reference | |
3348 | term ::= string_expression | string_list | |
3349 | expression ::= term @{ & term @} -- Concatenation | |
3350 | @end smallexample | |
3351 | ||
3352 | @noindent | |
3353 | Concatenation involves strings and list of strings. As soon as a list of | |
3354 | strings is involved, the result of the concatenation is a list of strings. The | |
3355 | following Ada declarations show the existing operators: | |
3356 | ||
3357 | @smallexample @c ada | |
d77cfab2 AC |
3358 | @b{function} "&" (X : String; Y : String) @b{return} String; |
3359 | @b{function} "&" (X : String_List; Y : String) @b{return} String_List; | |
3360 | @b{function} "&" (X : String_List; Y : String_List) @b{return} String_List; | |
b2cacbfe AC |
3361 | @end smallexample |
3362 | ||
3363 | @noindent | |
3364 | Here are some specific examples: | |
3365 | ||
3366 | @smallexample @c projectfile | |
3367 | @group | |
d77cfab2 AC |
3368 | List := () & File_Name; --@i{ One string in this list} |
3369 | List2 := List & (File_Name & ".orig"); --@i{ Two strings} | |
3370 | Big_List := List & Lists2; --@i{ Three strings} | |
3371 | Illegal := "gnat.adc" & List2; --@i{ Illegal, must start with list} | |
b2cacbfe AC |
3372 | @end group |
3373 | @end smallexample | |
3374 | ||
3375 | @c --------------------------------------------- | |
3376 | @node External Values | |
3377 | @subsection External Values | |
3378 | @c --------------------------------------------- | |
3379 | ||
3380 | @noindent | |
3381 | An external value is an expression whose value is obtained from the command | |
3382 | that invoked the processing of the current project file (typically a | |
4bb43ffb | 3383 | @command{gnatmake} or @command{gprbuild} command). |
b2cacbfe | 3384 | |
ef237104 AC |
3385 | There are two kinds of external values, one that returns a single string, and |
3386 | one that returns a string list. | |
3387 | ||
3388 | The syntax of a single string external value is: | |
3389 | ||
b2cacbfe AC |
3390 | @smallexample |
3391 | external_value ::= @i{external} ( string_literal [, string_literal] ) | |
3392 | @end smallexample | |
3393 | ||
3394 | @noindent | |
3395 | The first string_literal is the string to be used on the command line or | |
3396 | in the environment to specify the external value. The second string_literal, | |
3397 | if present, is the default to use if there is no specification for this | |
3398 | external value either on the command line or in the environment. | |
3399 | ||
3400 | Typically, the external value will either exist in the | |
d77cfab2 | 3401 | environment variables |
b2cacbfe | 3402 | or be specified on the command line through the |
d77cfab2 | 3403 | @option{-X@emph{vbl}=@emph{value}} switch. If both |
b2cacbfe AC |
3404 | are specified, then the command line value is used, so that a user can more |
3405 | easily override the value. | |
3406 | ||
ef237104 | 3407 | The function @code{external} always returns a string. It is an error if the |
b2cacbfe AC |
3408 | value was not found in the environment and no default was specified in the |
3409 | call to @code{external}. | |
3410 | ||
3411 | An external reference may be part of a string expression or of a string | |
3412 | list expression, and can therefore appear in a variable declaration or | |
3413 | an attribute declaration. | |
3414 | ||
3415 | Most of the time, this construct is used to initialize typed variables, which | |
bb304287 | 3416 | are then used in @b{case} constructions to control the value assigned to |
b2cacbfe AC |
3417 | attributes in various scenarios. Thus such variables are often called |
3418 | @b{scenario variables}. | |
3419 | ||
ef237104 AC |
3420 | The syntax for a string list external value is: |
3421 | ||
3422 | @smallexample | |
3423 | external_value ::= @i{external_as_list} ( string_literal , string_literal ) | |
3424 | @end smallexample | |
3425 | ||
3426 | @noindent | |
3427 | The first string_literal is the string to be used on the command line or | |
3428 | in the environment to specify the external value. The second string_literal is | |
3429 | the separator between each component of the string list. | |
3430 | ||
3431 | If the external value does not exist in the environment or on the command line, | |
3432 | the result is an empty list. This is also the case, if the separator is an | |
3433 | empty string or if the external value is only one separator. | |
3434 | ||
3435 | Any separator at the beginning or at the end of the external value is | |
308e6f3a RW |
3436 | discarded. Then, if there is no separator in the external value, the result is |
3437 | a string list with only one string. Otherwise, any string between the beginning | |
ef237104 AC |
3438 | and the first separator, between two consecutive separators and between the |
3439 | last separator and the end are components of the string list. | |
3440 | ||
3441 | @smallexample | |
3442 | @i{external_as_list} ("SWITCHES", ",") | |
3443 | @end smallexample | |
3444 | ||
3445 | @noindent | |
d77cfab2 AC |
3446 | If the external value is "-O2,-g", |
3447 | the result is ("-O2", "-g"). | |
ef237104 | 3448 | |
d77cfab2 AC |
3449 | If the external value is ",-O2,-g,", |
3450 | the result is also ("-O2", "-g"). | |
ef237104 | 3451 | |
d77cfab2 AC |
3452 | if the external value is "-gnatv", |
3453 | the result is ("-gnatv"). | |
ef237104 AC |
3454 | |
3455 | If the external value is ",,", the result is (""). | |
3456 | ||
3457 | If the external value is ",", the result is (), the empty string list. | |
3458 | ||
b2cacbfe AC |
3459 | @c --------------------------------------------- |
3460 | @node Typed String Declaration | |
3461 | @subsection Typed String Declaration | |
3462 | @c --------------------------------------------- | |
3463 | ||
3464 | @noindent | |
3465 | A @b{type declaration} introduces a discrete set of string literals. | |
3466 | If a string variable is declared to have this type, its value | |
3467 | is restricted to the given set of literals. These are the only named | |
3468 | types in project files. A string type may only be declared at the project | |
3469 | level, not inside a package. | |
3470 | ||
3471 | @smallexample | |
3472 | typed_string_declaration ::= | |
3473 | @i{type} @i{<typed_string_>}_simple_name @i{is} ( string_literal @{, string_literal@} ); | |
3474 | @end smallexample | |
3475 | ||
3476 | @noindent | |
3477 | The string literals in the list are case sensitive and must all be different. | |
3478 | They may include any graphic characters allowed in Ada, including spaces. | |
3479 | Here is an example of a string type declaration: | |
3480 | ||
3481 | @smallexample @c projectfile | |
d77cfab2 | 3482 | @b{type} OS @b{is} ("NT", "nt", "Unix", "GNU/Linux", "other OS"); |
b2cacbfe AC |
3483 | @end smallexample |
3484 | ||
3485 | @noindent | |
3486 | Variables of a string type are called @b{typed variables}; all other | |
3487 | variables are called @b{untyped variables}. Typed variables are | |
3488 | particularly useful in @code{case} constructions, to support conditional | |
b671e31b | 3489 | attribute declarations. (@pxref{Case Constructions}). |
b2cacbfe AC |
3490 | |
3491 | A string type may be referenced by its name if it has been declared in the same | |
3492 | project file, or by an expanded name whose prefix is the name of the project | |
3493 | in which it is declared. | |
3494 | ||
3495 | @c --------------------------------------------- | |
3496 | @node Variables | |
3497 | @subsection Variables | |
3498 | @c --------------------------------------------- | |
3499 | ||
3500 | @noindent | |
3501 | @b{Variables} store values (strings or list of strings) and can appear | |
3502 | as part of an expression. The declaration of a variable creates the | |
3503 | variable and assigns the value of the expression to it. The name of the | |
3504 | variable is available immediately after the assignment symbol, if you | |
3505 | need to reuse its old value to compute the new value. Before the completion | |
3506 | of its first declaration, the value of a variable defaults to the empty | |
3507 | string (""). | |
3508 | ||
3509 | A @b{typed} variable can be used as part of a @b{case} expression to | |
3510 | compute the value, but it can only be declared once in the project file, | |
b671e31b | 3511 | so that all case constructions see the same value for the variable. This |
b2cacbfe AC |
3512 | provides more consistency and makes the project easier to understand. |
3513 | The syntax for its declaration is identical to the Ada syntax for an | |
3514 | object declaration. In effect, a typed variable acts as a constant. | |
3515 | ||
3516 | An @b{untyped} variable can be declared and overridden multiple times | |
3517 | within the same project. It is declared implicitly through an Ada | |
3518 | assignment. The first declaration establishes the kind of the variable | |
3519 | (string or list of strings) and successive declarations must respect | |
3520 | the initial kind. Assignments are executed in the order in which they | |
3521 | appear, so the new value replaces the old one and any subsequent reference | |
3522 | to the variable uses the new value. | |
3523 | ||
3524 | A variable may be declared at the project file level, or within a package. | |
3525 | ||
3526 | @smallexample | |
3527 | typed_variable_declaration ::= | |
3528 | @i{<typed_variable_>}simple_name : @i{<typed_string_>}name := string_expression; | |
3529 | variable_declaration ::= @i{<variable_>}simple_name := expression; | |
3530 | @end smallexample | |
3531 | ||
3532 | @noindent | |
3533 | Here are some examples of variable declarations: | |
3534 | ||
3535 | @smallexample @c projectfile | |
3536 | @group | |
d77cfab2 AC |
3537 | This_OS : OS := @b{external} ("OS"); --@i{ a typed variable declaration} |
3538 | That_OS := "GNU/Linux"; --@i{ an untyped variable declaration} | |
b2cacbfe AC |
3539 | |
3540 | Name := "readme.txt"; | |
3541 | Save_Name := Name & ".saved"; | |
3542 | ||
3543 | Empty_List := (); | |
3544 | List_With_One_Element := ("-gnaty"); | |
3545 | List_With_Two_Elements := List_With_One_Element & "-gnatg"; | |
3546 | Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada"); | |
3547 | @end group | |
3548 | @end smallexample | |
3549 | ||
3550 | @noindent | |
3551 | A @b{variable reference} may take several forms: | |
3552 | ||
3553 | @itemize @bullet | |
3554 | @item The simple variable name, for a variable in the current package (if any) | |
3555 | or in the current project | |
3556 | @item An expanded name, whose prefix is a context name. | |
3557 | ||
3558 | @end itemize | |
3559 | ||
3560 | @noindent | |
3561 | A @b{context} may be one of the following: | |
3562 | ||
3563 | @itemize @bullet | |
3564 | @item The name of an existing package in the current project | |
3565 | @item The name of an imported project of the current project | |
3566 | @item The name of an ancestor project (i.e., a project extended by the current | |
3567 | project, either directly or indirectly) | |
3568 | @item An expanded name whose prefix is an imported/parent project name, and | |
3569 | whose selector is a package name in that project. | |
3570 | @end itemize | |
3571 | ||
b671e31b VC |
3572 | @c --------------------------------------------- |
3573 | @node Case Constructions | |
3574 | @subsection Case Constructions | |
3575 | @c --------------------------------------------- | |
3576 | ||
3577 | @noindent | |
bb304287 AC |
3578 | A @b{case} construction is used in a project file to effect conditional |
3579 | behavior. Through this construction, you can set the value of attributes | |
b671e31b VC |
3580 | and variables depending on the value previously assigned to a typed |
3581 | variable. | |
3582 | ||
3583 | All choices in a choice list must be distinct. Unlike Ada, the choice | |
3584 | lists of all alternatives do not need to include all values of the type. | |
3585 | An @code{others} choice must appear last in the list of alternatives. | |
3586 | ||
bb304287 AC |
3587 | The syntax of a @code{case} construction is based on the Ada case construction |
3588 | (although the @code{null} declaration for empty alternatives is optional). | |
b671e31b | 3589 | |
bb304287 AC |
3590 | The case expression must be a string variable, either typed or not, whose value |
3591 | is often given by an external reference (@pxref{External Values}). | |
b671e31b VC |
3592 | |
3593 | Each alternative starts with the reserved word @code{when}, either a list of | |
3594 | literal strings separated by the @code{"|"} character or the reserved word | |
3595 | @code{others}, and the @code{"=>"} token. | |
bb304287 AC |
3596 | When the case expression is a typed string variable, each literal string must |
3597 | belong to the string type that is the type of the case variable. | |
3598 | After each @code{=>}, there are zero or more declarations. The only | |
3599 | declarations allowed in a case construction are other case constructions, | |
b671e31b VC |
3600 | attribute declarations and variable declarations. String type declarations and |
3601 | package declarations are not allowed. Variable declarations are restricted to | |
3602 | variables that have already been declared before the case construction. | |
3603 | ||
3604 | @smallexample | |
bb304287 AC |
3605 | case_construction ::= |
3606 | @i{case} @i{<variable_>}name @i{is} @{case_item@} @i{end case} ; | |
b671e31b VC |
3607 | |
3608 | case_item ::= | |
3609 | @i{when} discrete_choice_list => | |
bb304287 | 3610 | @{case_declaration |
b671e31b VC |
3611 | | attribute_declaration |
3612 | | variable_declaration | |
3613 | | empty_declaration@} | |
3614 | ||
3615 | discrete_choice_list ::= string_literal @{| string_literal@} | @i{others} | |
3616 | @end smallexample | |
3617 | ||
3618 | @noindent | |
bb304287 | 3619 | Here is a typical example, with a typed string variable: |
b671e31b VC |
3620 | |
3621 | @smallexample @c projectfile | |
3622 | @group | |
d77cfab2 AC |
3623 | @b{project} MyProj @b{is} |
3624 | @b{type} OS_Type @b{is} ("GNU/Linux", "Unix", "NT", "VMS"); | |
3625 | OS : OS_Type := @b{external} ("OS", "GNU/Linux"); | |
3626 | ||
3627 | @b{package} Compiler @b{is} | |
3628 | @b{case} OS @b{is} | |
3629 | @b{when} "GNU/Linux" | "Unix" => | |
3630 | @b{for} Switches ("Ada") | |
3631 | @b{use} ("-gnath"); | |
3632 | @b{when} "NT" => | |
3633 | @b{for} Switches ("Ada") | |
3634 | @b{use} ("-gnatP"); | |
3635 | @b{when} @b{others} => | |
3636 | @b{null}; | |
3637 | @b{end} @b{case}; | |
3638 | @b{end} Compiler; | |
3639 | @b{end} MyProj; | |
b671e31b VC |
3640 | @end group |
3641 | @end smallexample | |
3642 | ||
b2cacbfe AC |
3643 | @c --------------------------------------------- |
3644 | @node Attributes | |
3645 | @subsection Attributes | |
3646 | @c --------------------------------------------- | |
3647 | ||
761f7dcb AC |
3648 | @menu |
3649 | * Project Level Attributes:: | |
3650 | * Package Binder Attributes:: | |
3651 | * Package Builder Attributes:: | |
1037b0f4 | 3652 | @ifclear FSFEDITION |
761f7dcb | 3653 | * Package Check Attributes:: |
1037b0f4 | 3654 | @end ifclear |
761f7dcb AC |
3655 | * Package Clean Attributes:: |
3656 | * Package Compiler Attributes:: | |
3657 | * Package Cross_Reference Attributes:: | |
1037b0f4 | 3658 | @ifclear FSFEDITION |
761f7dcb | 3659 | * Package Eliminate Attributes:: |
1037b0f4 | 3660 | @end ifclear |
761f7dcb | 3661 | * Package Finder Attributes:: |
d77cfab2 | 3662 | * Package gnatls Attributes:: |
1037b0f4 | 3663 | @ifclear FSFEDITION |
d77cfab2 | 3664 | * Package gnatstub Attributes:: |
1037b0f4 | 3665 | @end ifclear |
761f7dcb AC |
3666 | * Package IDE Attributes:: |
3667 | * Package Install Attributes:: | |
3668 | * Package Linker Attributes:: | |
1037b0f4 | 3669 | @ifclear FSFEDITION |
761f7dcb | 3670 | * Package Metrics Attribute:: |
1037b0f4 | 3671 | @end ifclear |
761f7dcb | 3672 | * Package Naming Attributes:: |
1037b0f4 | 3673 | @ifclear FSFEDITION |
761f7dcb | 3674 | * Package Pretty_Printer Attributes:: |
1037b0f4 | 3675 | @end ifclear |
761f7dcb AC |
3676 | * Package Remote Attributes:: |
3677 | * Package Stack Attributes:: | |
3678 | * Package Synchronize Attributes:: | |
3679 | @end menu | |
3680 | ||
b2cacbfe AC |
3681 | @noindent |
3682 | A project (and its packages) may have @b{attributes} that define | |
3683 | the project's properties. Some attributes have values that are strings; | |
3684 | others have values that are string lists. | |
3685 | ||
3686 | @smallexample | |
3687 | attribute_declaration ::= | |
3688 | simple_attribute_declaration | indexed_attribute_declaration | |
3689 | simple_attribute_declaration ::= @i{for} attribute_designator @i{use} expression ; | |
3690 | indexed_attribute_declaration ::= | |
3691 | @i{for} @i{<indexed_attribute_>}simple_name ( string_literal) @i{use} expression ; | |
3692 | attribute_designator ::= | |
3693 | @i{<simple_attribute_>}simple_name | |
3694 | | @i{<indexed_attribute_>}simple_name ( string_literal ) | |
3695 | @end smallexample | |
3696 | ||
3697 | @noindent | |
3698 | There are two categories of attributes: @b{simple attributes} | |
3699 | and @b{indexed attributes}. | |
3700 | Each simple attribute has a default value: the empty string (for string | |
3701 | attributes) and the empty list (for string list attributes). | |
3702 | An attribute declaration defines a new value for an attribute, and overrides | |
3703 | the previous value. The syntax of a simple attribute declaration is similar to | |
3704 | that of an attribute definition clause in Ada. | |
3705 | ||
3706 | Some attributes are indexed. These attributes are mappings whose | |
3707 | domain is a set of strings. They are declared one association | |
3708 | at a time, by specifying a point in the domain and the corresponding image | |
3709 | of the attribute. | |
3710 | Like untyped variables and simple attributes, indexed attributes | |
3711 | may be declared several times. Each declaration supplies a new value for the | |
3712 | attribute, and replaces the previous setting. | |
3713 | ||
3714 | Here are some examples of attribute declarations: | |
3715 | ||
3716 | @smallexample @c projectfile | |
d77cfab2 AC |
3717 | --@i{ simple attributes} |
3718 | @b{for} Object_Dir @b{use} "objects"; | |
3719 | @b{for} Source_Dirs @b{use} ("units", "test/drivers"); | |
3720 | ||
3721 | --@i{ indexed attributes} | |
3722 | @b{for} Body ("main") @b{use} "Main.ada"; | |
3723 | @b{for} Switches ("main.ada") | |
3724 | @b{use} ("-v", "-gnatv"); | |
3725 | @b{for} Switches ("main.ada") @b{use} Builder'Switches ("main.ada") & "-g"; | |
3726 | ||
3727 | --@i{ indexed attributes copy (from package Builder in project Default)} | |
3728 | --@i{ The package name must always be specified, even if it is the current} | |
3729 | --@i{ package.} | |
3730 | @b{for} Default_Switches @b{use} Default.Builder'Default_Switches; | |
b2cacbfe AC |
3731 | @end smallexample |
3732 | ||
3733 | @noindent | |
8b1011c0 | 3734 | Attributes references may appear anywhere in expressions, and are used |
b2cacbfe AC |
3735 | to retrieve the value previously assigned to the attribute. If an attribute |
3736 | has not been set in a given package or project, its value defaults to the | |
af6478c8 | 3737 | empty string or the empty list, with some exceptions. |
b2cacbfe AC |
3738 | |
3739 | @smallexample | |
4887624e AC |
3740 | attribute_reference ::= |
3741 | attribute_prefix ' @i{<simple_attribute>_}simple_name [ (string_literal) ] | |
b2cacbfe AC |
3742 | attribute_prefix ::= @i{project} |
3743 | | @i{<project_>}simple_name | |
3744 | | package_identifier | |
3745 | | @i{<project_>}simple_name . package_identifier | |
3746 | @end smallexample | |
3747 | ||
3748 | @noindent | |
3749 | Examples are: | |
3750 | ||
3751 | @smallexample @c projectfile | |
d77cfab2 | 3752 | @b{project}'Object_Dir |
b2cacbfe AC |
3753 | Naming'Dot_Replacement |
3754 | Imported_Project'Source_Dirs | |
3755 | Imported_Project.Naming'Casing | |
3756 | Builder'Default_Switches ("Ada") | |
3757 | @end smallexample | |
3758 | ||
af6478c8 AC |
3759 | The exceptions to the empty defaults are: |
3760 | ||
3761 | @itemize @bullet | |
3762 | @item Object_Dir: default is "." | |
3763 | @item Exec_Dir: default is 'Object_Dir, that is the value of attribute | |
3764 | Object_Dir in the same project, declared or defaulted. | |
3765 | @item Source_Dirs: default is (".") | |
3766 | @end itemize | |
3767 | ||
b2cacbfe AC |
3768 | @noindent |
3769 | The prefix of an attribute may be: | |
3770 | ||
3771 | @itemize @bullet | |
3772 | @item @code{project} for an attribute of the current project | |
3773 | @item The name of an existing package of the current project | |
3774 | @item The name of an imported project | |
3775 | @item The name of a parent project that is extended by the current project | |
3776 | @item An expanded name whose prefix is imported/parent project name, | |
3777 | and whose selector is a package name | |
3778 | ||
3779 | @end itemize | |
3780 | ||
3781 | @noindent | |
761f7dcb AC |
3782 | |
3783 | In the following sections, all predefined attributes are succinctly described, | |
3784 | first the project level attributes, that is those attributes that are not in a | |
3785 | package, then the attributes in the different packages. | |
3786 | ||
4887624e AC |
3787 | It is possible for different tools to dynamically create new packages with |
3788 | attributes, or new attributes in predefined packages. These attributes are | |
761f7dcb AC |
3789 | not documented here. |
3790 | ||
3791 | The attributes under Configuration headings are usually found only in | |
3792 | configuration project files. | |
3793 | ||
3794 | The characteristics of each attribute are indicated as follows: | |
3795 | ||
3796 | @itemize @bullet | |
3797 | ||
3798 | @item @b{Type of value} | |
3799 | ||
3800 | The value of an attribute may be a single string, indicated by the word | |
3801 | "single", or a string list, indicated by the word "list". | |
3802 | ||
3803 | @item @b{Read-only} | |
3804 | ||
3805 | When the attribute is read-only, that is when it is not allowed to declare | |
3806 | the attribute, this is indicated by the words "read-only". | |
3807 | ||
3808 | @item @b{Optional index} | |
3809 | ||
3810 | If it is allowed in the value of the attribute (both single and list) to have | |
3811 | an optional index, this is indicated by the words "optional index". | |
3812 | ||
3813 | @item @b{Indexed attribute} | |
3814 | ||
3815 | When an it is an indexed attribute, this is indicated by the word "indexed". | |
3816 | ||
3817 | @item @b{Case-sensitivity of the index} | |
3818 | ||
3819 | For an indexed attribute, if the index is case-insensitive, this is indicated | |
3820 | by the words "case-insensitive index". | |
3821 | ||
3822 | @item @b{File name index} | |
3823 | ||
3824 | For an indexed attribute, when the index is a file name, this is indicated by | |
3825 | the words "file name index". The index may or may not be case-sensitive, | |
3826 | depending on the platform. | |
3827 | ||
3828 | @item @b{others allowed in index} | |
3829 | ||
3830 | For an indexed attribute, if it is allowed to use @b{others} as the index, | |
3831 | this is indicated by the words "others allowed". | |
3832 | ||
d66f9f0b AC |
3833 | When @b{others} is used as the index of an indexed attribute, the value of |
3834 | the attribute indexed by @b{others} is used when no other index would apply. | |
3835 | ||
761f7dcb AC |
3836 | @end itemize |
3837 | ||
3838 | @node Project Level Attributes | |
3839 | @subsubsection Project Level Attributes | |
3840 | @noindent | |
3841 | ||
3842 | @itemize @bullet | |
3843 | ||
3844 | @item @b{General} | |
3845 | ||
3846 | @itemize @bullet | |
3847 | ||
3848 | @item @b{Name}: single, read-only | |
3849 | ||
3850 | The name of the project. | |
3851 | ||
3852 | @item @b{Project_Dir}: single, read-only | |
3853 | ||
3854 | The path name of the project directory. | |
3855 | ||
3856 | @item @b{Main}: list, optional index | |
3857 | ||
3858 | The list of main sources for the executables. | |
3859 | ||
3860 | @item @b{Languages}: list | |
3861 | ||
3862 | The list of languages of the sources of the project. | |
3863 | ||
3864 | @item @b{Roots}: list, indexed, file name index | |
3865 | ||
f6820c2d AC |
3866 | The index is the file name of an executable source. Indicates the list of units |
3867 | from the main project that need to be bound and linked with their closures | |
3868 | with the executable. The index is either a file name, a language name or "*". | |
3869 | The roots for an executable source are those in @b{Roots} with an index that | |
3870 | is the executable source file name, if declared. Otherwise, they are those in | |
3871 | @b{Roots} with an index that is the language name of the executable source, | |
3872 | if present. Otherwise, they are those in @b{Roots ("*")}, if declared. If none | |
3873 | of these three possibilities are declared, then there are no roots for the | |
3874 | executable source. | |
761f7dcb AC |
3875 | |
3876 | @item @b{Externally_Built}: single | |
3877 | ||
3878 | Indicates if the project is externally built. | |
3879 | Only case-insensitive values allowed are "true" and "false", the default. | |
3880 | ||
3881 | @end itemize | |
3882 | @noindent | |
3883 | ||
3884 | @item @b{Directories} | |
3885 | ||
3886 | @itemize @bullet | |
3887 | ||
3888 | @item @b{Object_Dir}: single | |
3889 | ||
3890 | Indicates the object directory for the project. | |
3891 | ||
3892 | @item @b{Exec_Dir}: single | |
3893 | ||
3894 | Indicates the exec directory for the project, that is the directory where the | |
3895 | executables are. | |
3896 | ||
3897 | @item @b{Source_Dirs}: list | |
3898 | ||
3899 | The list of source directories of the project. | |
3900 | ||
3901 | @item @b{Inherit_Source_Path}: list, indexed, case-insensitive index | |
3902 | ||
3903 | Index is a language name. Value is a list of language names. Indicates that | |
3904 | in the source search path of the index language the source directories of | |
3905 | the languages in the list should be included. | |
3906 | ||
3907 | Example: | |
3908 | ||
3909 | for Inherit_Source_Path ("C++") use ("C"); | |
3910 | ||
3911 | @item @b{Exclude_Source_Dirs}: list | |
3912 | ||
3913 | The list of directories that are included in Source_Dirs but are not source | |
3914 | directories of the project. | |
3915 | ||
3916 | @item @b{Ignore_Source_Sub_Dirs}: list | |
3917 | ||
3918 | Value is a list of simple names for subdirectories that are removed from the | |
3919 | list of source directories, including theur subdirectories. | |
3920 | ||
3921 | @end itemize | |
3922 | ||
3923 | @item @b{Source Files} | |
3924 | ||
3925 | @itemize @bullet | |
3926 | ||
3927 | @item @b{Source_Files}: list | |
3928 | ||
3929 | Value is a list of source file simple names. | |
3930 | ||
3931 | @item @b{Locally_Removed_Files}: list | |
3932 | ||
3933 | Obsolescent. Equivalent to Excluded_Source_Files. | |
3934 | ||
3935 | @item @b{Excluded_Source_Files}: list | |
3936 | ||
3937 | Value is a list of simple file names that are not sources of the project. | |
3938 | Allows to remove sources that are inherited or found in the source directories | |
3939 | and that match the naming scheme. | |
3940 | ||
3941 | @item @b{Source_List_File}: single | |
3942 | ||
3943 | Value is a text file name that contains a list of source file simple names, | |
3944 | one on each line. | |
3945 | ||
3946 | @item @b{Excluded_Source_List_File}: single | |
3947 | ||
3948 | Value is a text file name that contains a list of file simple names that | |
3949 | are not sources of the project. | |
3950 | ||
3951 | @item @b{Interfaces}: list | |
3952 | ||
3953 | Value is a list of file names that constitutes the interfaces of the project. | |
3954 | ||
3955 | @end itemize | |
3956 | ||
3957 | @item @b{Aggregate Projects} | |
3958 | ||
3959 | @itemize @bullet | |
3960 | ||
3961 | @item @b{Project_Files}: list | |
3962 | ||
3963 | Value is the list of aggregated projects. | |
3964 | ||
3965 | @item @b{Project_Path}: list | |
3966 | ||
3967 | Value is a list of directories that are added to the project search path when | |
3968 | looking for the aggregated projects. | |
3969 | ||
3970 | @item @b{External}: single, indexed | |
3971 | ||
3972 | Index is the name of an external reference. Value is the value of the | |
3973 | external reference to be used when parsing the aggregated projects. | |
3974 | ||
3975 | @end itemize | |
3976 | ||
3977 | @item @b{Libraries} | |
3978 | ||
3979 | @itemize @bullet | |
3980 | ||
3981 | @item @b{Library_Dir}: single | |
3982 | ||
3983 | Value is the name of the library directory. This attribute needs to be | |
3984 | declared for each library project. | |
3985 | ||
3986 | @item @b{Library_Name}: single | |
3987 | ||
3988 | Value is the name of the library. This attribute needs to be declared or | |
3989 | inherited for each library project. | |
3990 | ||
3991 | @item @b{Library_Kind}: single | |
3992 | ||
3993 | Specifies the kind of library: static library (archive) or shared library. | |
3994 | Case-insensitive values must be one of "static" for archives (the default) or | |
3995 | "dynamic" or "relocatable" for shared libraries. | |
3996 | ||
3997 | @item @b{Library_Version}: single | |
3998 | ||
3999 | Value is the name of the library file. | |
4000 | ||
4001 | @item @b{Library_Interface}: list | |
4002 | ||
4003 | Value is the list of unit names that constitutes the interfaces | |
4004 | of a Stand-Alone Library project. | |
4005 | ||
4006 | @item @b{Library_Standalone}: single | |
4007 | ||
4008 | Specifies if a Stand-Alone Library (SAL) is encapsulated or not. | |
4009 | Only authorized case-insensitive values are "standard" for non encapsulated | |
4010 | SALs, "encapsulated" for encapsulated SALs or "no" for non SAL library project. | |
4011 | ||
4012 | @item @b{Library_Encapsulated_Options}: list | |
4013 | ||
4014 | Value is a list of options that need to be used when linking an encapsulated | |
4015 | Stand-Alone Library. | |
4016 | ||
4017 | @item @b{Library_Encapsulated_Supported}: single | |
4018 | ||
4019 | Indicates if encapsulated Stand-Alone Libraries are supported. Only | |
4020 | authorized case-insensitive values are "true" and "false" (the default). | |
4021 | ||
4022 | @item @b{Library_Auto_Init}: single | |
4023 | ||
4024 | Indicates if a Stand-Alone Library is auto-initialized. Only authorized | |
4025 | case-insentive values are "true" and "false". | |
4026 | ||
4027 | @item @b{Leading_Library_Options}: list | |
4028 | ||
4029 | Value is a list of options that are to be used at the beginning of | |
4030 | the command line when linking a shared library. | |
4031 | ||
4032 | @item @b{Library_Options}: list | |
4033 | ||
4034 | Value is a list of options that are to be used when linking a shared library. | |
4035 | ||
e74d643a AC |
4036 | @item @b{Library_Rpath_Options}: list, indexed, case-insensitive index |
4037 | ||
4038 | Index is a language name. Value is a list of options for an invocation of the | |
4039 | compiler of the language. This invocation is done for a shared library project | |
4040 | with sources of the language. The output of the invocation is the path name | |
4041 | of a shared library file. The directory name is to be put in the run path | |
4042 | option switch when linking the shared library for the project. | |
4043 | ||
761f7dcb AC |
4044 | @item @b{Library_Src_Dir}: single |
4045 | ||
4046 | Value is the name of the directory where copies of the sources of the | |
4047 | interfaces of a Stand-Alone Library are to be copied. | |
4048 | ||
4049 | @item @b{Library_ALI_Dir}: single | |
4050 | ||
4051 | Value is the name of the directory where the ALI files of the interfaces | |
4052 | of a Stand-Alone Library are to be copied. When this attribute is not declared, | |
4053 | the directory is the library directory. | |
4054 | ||
4055 | @item @b{Library_gcc}: single | |
4056 | ||
4057 | Obsolescent attribute. Specify the linker driver used to link a shared library. | |
4058 | Use instead attribute Linker'Driver. | |
4059 | ||
4060 | @item @b{Library_Symbol_File}: single | |
4061 | ||
4062 | Value is the name of the library symbol file. | |
4063 | ||
4064 | @item @b{Library_Symbol_Policy}: single | |
4065 | ||
4066 | Indicates the symbol policy kind. Only authorized case-insensitive values are | |
4067 | "autonomous", "default", "compliant", "controlled" or "direct". | |
4068 | ||
4069 | @item @b{Library_Reference_Symbol_File}: single | |
4070 | ||
4071 | Value is the name of the reference symbol file. | |
4072 | ||
4073 | @end itemize | |
4074 | ||
4075 | @item @b{Configuration - General} | |
4076 | ||
4077 | @itemize @bullet | |
4078 | ||
4079 | @item @b{Default_Language}: single | |
4080 | ||
4081 | Value is the case-insensitive name of the language of a project when attribute | |
4082 | Languages is not specified. | |
4083 | ||
4084 | @item @b{Run_Path_Option}: list | |
4085 | ||
4086 | Value is the list of switches to be used when specifying the run path option | |
4087 | in an executable. | |
4088 | ||
4089 | @item @b{Run_Path_Origin}: single | |
4090 | ||
026c3cfd | 4091 | Value is the string that may replace the path name of the executable |
761f7dcb AC |
4092 | directory in the run path options. |
4093 | ||
4094 | @item @b{Separate_Run_Path_Options}: single | |
4095 | ||
4887624e AC |
4096 | Indicates if there may be several run path options specified when linking an |
4097 | executable. Only authorized case-insensitive values are "true" or "false" (the | |
4098 | default). | |
761f7dcb AC |
4099 | |
4100 | @item @b{Toolchain_Version}: single, indexed, case-insensitive index | |
4101 | ||
4102 | Index is a language name. Specify the version of a toolchain for a language. | |
4103 | ||
4104 | @item @b{Toolchain_Description}: single, indexed, case-insensitive index | |
4105 | ||
4106 | Obsolescent. No longer used. | |
4107 | ||
4108 | @item @b{Object_Generated}: single, indexed, case-insensitive index | |
4109 | ||
4110 | Index is a language name. Indicates if invoking the compiler for a language | |
4111 | produces an object file. Only authorized case-insensitive values are "false" | |
4112 | and "true" (the default). | |
4113 | ||
4114 | @item @b{Objects_Linked}: single, indexed, case-insensitive index | |
4115 | ||
4116 | Index is a language name. Indicates if the object files created by the compiler | |
4117 | for a language need to be linked in the executable. Only authorized | |
4118 | case-insensitive values are "false" and "true" (the default). | |
4119 | ||
4120 | @item @b{Target}: single | |
4121 | ||
88305f17 AC |
4122 | Value is the name of the target platform. Taken into account only in the main |
4123 | project. | |
4124 | ||
4125 | @item @b{Runtime}: single, indexed, case-insensitive index | |
4126 | ||
4127 | Index is a language name. Indicates the runtime directory that is to be used | |
4128 | when using the compiler of the language. Taken into account only in the main | |
4129 | project. | |
761f7dcb AC |
4130 | |
4131 | @end itemize | |
4132 | ||
4133 | @item @b{Configuration - Libraries} | |
4134 | ||
4135 | @itemize @bullet | |
4136 | ||
4137 | @item @b{Library_Builder}: single | |
4138 | ||
4139 | Value is the path name of the application that is to be used to build | |
4140 | libraries. Usually the path name of "gprlib". | |
4141 | ||
4142 | @item @b{Library_Support}: single | |
4143 | ||
4144 | Indicates the level of support of libraries. Only authorized case-insensitive | |
4145 | values are "static_only", "full" or "none" (the default). | |
4146 | ||
4147 | @end itemize | |
4148 | ||
4149 | @item @b{Configuration - Archives} | |
4150 | ||
4151 | @itemize @bullet | |
4152 | ||
4153 | @item @b{Archive_Builder}: list | |
4154 | ||
4155 | Value is the name of the application to be used to create a static library | |
4156 | (archive), followed by the options to be used. | |
4157 | ||
4158 | @item @b{Archive_Builder_Append_Option}: list | |
4159 | ||
4160 | Value is the list of options to be used when invoking the archive builder | |
4161 | to add project files into an archive. | |
4162 | ||
4163 | @item @b{Archive_Indexer}: list | |
4164 | ||
4165 | Value is the name of the archive indexer, followed by the required options. | |
4166 | ||
4167 | @item @b{Archive_Suffix}: single | |
4168 | ||
4169 | Value is the extension of archives. When not declared, the extension is ".a". | |
4170 | ||
4171 | @item @b{Library_Partial_Linker}: list | |
4172 | ||
4173 | Value is the name of the partial linker executable, followed by the required | |
4174 | options. | |
4175 | ||
4176 | @end itemize | |
4177 | ||
4178 | @item @b{Configuration - Shared Libraries} | |
4179 | ||
4180 | @itemize @bullet | |
4181 | ||
4182 | @item @b{Shared_Library_Prefix}: single | |
4183 | ||
4184 | Value is the prefix in the name of shared library files. When not declared, | |
4185 | the prefix is "lib". | |
4186 | ||
4187 | @item @b{Shared_Library_Suffix}: single | |
4188 | ||
026c3cfd | 4189 | Value is the extension of the name of shared library files. When not |
761f7dcb AC |
4190 | declared, the extension is ".so". |
4191 | ||
4192 | @item @b{Symbolic_Link_Supported}: single | |
4193 | ||
4194 | Indicates if symbolic links are supported on the platform. Only authorized | |
4195 | case-insensitive values are "true" and "false" (the default). | |
4196 | ||
4197 | @item @b{Library_Major_Minor_Id_Supported}: single | |
4198 | ||
4199 | Indicates if major and minor ids for shared library names are supported on | |
4200 | the platform. Only authorized case-insensitive values are "true" and "false" | |
4201 | (the default). | |
4202 | ||
4203 | @item @b{Library_Auto_Init_Supported}: single | |
4204 | ||
4205 | Indicates if auto-initialization of Stand-Alone Libraries is supported. Only | |
4206 | authorized case-insensitive values are "true" and "false" (the default). | |
4207 | ||
4208 | @item @b{Shared_Library_Minimum_Switches}: list | |
4209 | ||
4210 | Value is the list of required switches when linking a shared library. | |
4211 | ||
4212 | @item @b{Library_Version_Switches}: list | |
4213 | ||
4214 | Value is the list of switches to specify a internal name for a shared library. | |
4215 | ||
4216 | @item @b{Library_Install_Name_Option}: single | |
4217 | ||
4218 | Value is the name of the option that needs to be used, concatenated with the | |
4219 | path name of the library file, when linking a shared library. | |
4220 | ||
4221 | @item @b{Runtime_Library_Dir}: single, indexed, case-insensitive index | |
4222 | ||
4223 | Index is a language name. Value is the path name of the directory where the | |
4224 | runtime libraries are located. | |
4225 | ||
4226 | @item @b{Runtime_Source_Dir}: single, indexed, case-insensitive index | |
4227 | ||
4228 | Index is a language name. Value is the path name of the directory where the | |
4229 | sources of runtime libraries are located. | |
4230 | ||
4231 | @end itemize | |
4232 | ||
4233 | @end itemize | |
4234 | ||
4235 | @node Package Binder Attributes | |
4236 | @subsubsection Package Binder Attributes | |
4237 | ||
4238 | @itemize @bullet | |
4239 | ||
4240 | @item @b{General} | |
4241 | ||
4242 | @itemize @bullet | |
4243 | ||
4244 | @item @b{Default_Switches}: list, indexed, case-insensitive index | |
4245 | ||
4246 | Index is a language name. Value is the list of switches to be used when binding | |
d77cfab2 | 4247 | code of the language, if there is no applicable attribute Switches. |
761f7dcb | 4248 | |
d77cfab2 | 4249 | @item @b{Switches}: list, optional index, indexed, |
455f3336 | 4250 | case-insensitive index, others allowed |
761f7dcb AC |
4251 | |
4252 | Index is either a language name or a source file name. Value is the list of | |
4253 | switches to be used when binding code. Index is either the source file name | |
4254 | of the executable to be bound or the language name of the code to be bound. | |
4255 | ||
4256 | @end itemize | |
4257 | ||
4258 | @item @b{Configuration - Binding} | |
4259 | ||
4260 | @itemize @bullet | |
4261 | ||
4262 | @item @b{Driver}: single, indexed, case-insensitive index | |
4263 | ||
4264 | Index is a language name. Value is the name of the application to be used when | |
4265 | binding code of the language. | |
4266 | ||
4267 | @item @b{Required_Switches}: list, indexed, case-insensitive index | |
4268 | ||
4269 | Index is a language name. Value is the list of the required switches to be | |
4270 | used when binding code of the language. | |
4271 | ||
4272 | @item @b{Prefix}: single, indexed, case-insensitive index | |
4273 | ||
4274 | Index is a language name. Value is a prefix to be used for the binder exchange | |
4275 | file name for the language. Used to have different binder exchange file names | |
4276 | when binding different languages. | |
4277 | ||
4278 | @item @b{Objects_Path}: single,indexed, case-insensitive index | |
4279 | ||
4280 | Index is a language name. Value is the name of the environment variable that | |
4281 | contains the path for the object directories. | |
4282 | ||
4283 | @item @b{Object_Path_File}: single,indexed, case-insensitive index | |
4284 | ||
4285 | Index is a language name. Value is the name of the environment variable. The | |
4286 | value of the environment variable is the path name of a text file that | |
4287 | contains the list of object directories. | |
4288 | ||
4289 | @end itemize | |
4290 | ||
4291 | @end itemize | |
4292 | ||
4293 | @node Package Builder Attributes | |
4294 | @subsubsection Package Builder Attributes | |
4295 | ||
4296 | @itemize @bullet | |
4297 | ||
4298 | @item @b{Default_Switches}: list, indexed, case-insensitive index | |
4299 | ||
4300 | Index is a language name. Value is the list of builder switches to be used when | |
4301 | building an executable of the language, if there is no applicable attribute | |
4302 | Switches. | |
4303 | ||
d77cfab2 | 4304 | @item @b{Switches}: list, optional index, indexed, case-insensitive index, |
761f7dcb AC |
4305 | others allowed |
4306 | ||
4307 | Index is either a language name or a source file name. Value is the list of | |
4308 | builder switches to be used when building an executable. Index is either the | |
4309 | source file name of the executable to be built or its language name. | |
4310 | ||
4311 | @item @b{Global_Compilation_Switches}: list, optional index, indexed, | |
4312 | case-insensitive index | |
4313 | ||
4314 | Index is either a language name or a source file name. Value is the list of | |
4315 | compilation switches to be used when building an executable. Index is either | |
4316 | the source file name of the executable to be built or its language name. | |
4317 | ||
4318 | @item @b{Executable}: single, indexed, case-insensitive index | |
4319 | ||
4320 | Index is an executable source file name. Value is the simple file name of the | |
4321 | executable to be built. | |
4322 | ||
4323 | @item @b{Executable_Suffix}: single | |
4324 | ||
4325 | Value is the extension of the file names of executable. When not specified, | |
4326 | the extension is the default extension of executables on the platform. | |
4327 | ||
4328 | @item @b{Global_Configuration_Pragmas}: single | |
4329 | ||
4330 | Value is the file name of a configuration pragmas file that is specified to | |
4331 | the Ada compiler when compiling any Ada source in the project tree. | |
4332 | ||
4333 | @item @b{Global_Config_File}: single, indexed, case-insensitive index | |
4334 | ||
4335 | Index is a language name. Value is the file name of a configuration file that | |
4336 | is specified to the compiler when compiling any source of the language in the | |
4337 | project tree. | |
4338 | ||
4339 | @end itemize | |
4340 | ||
1037b0f4 | 4341 | @ifclear FSFEDITION |
761f7dcb AC |
4342 | @node Package Check Attributes |
4343 | @subsubsection Package Check Attributes | |
4344 | ||
4345 | @itemize @bullet | |
4346 | ||
4347 | @item @b{Default_Switches}: list, indexed, case-insensitive index | |
4348 | ||
4349 | Index is a language name. Value is a list of switches to be used when invoking | |
4350 | @code{gnatcheck} for a source of the language, if there is no applicable | |
d77cfab2 | 4351 | attribute Switches. |
761f7dcb | 4352 | |
d77cfab2 | 4353 | @item @b{Switches}: list, optional index, indexed, case-insensitive index, |
761f7dcb AC |
4354 | others allowed |
4355 | ||
4356 | Index is a source file name. Value is the list of switches to be used when | |
4357 | invoking @code{gnatcheck} for the source. | |
4358 | ||
4359 | @end itemize | |
1037b0f4 | 4360 | @end ifclear |
761f7dcb AC |
4361 | |
4362 | @node Package Clean Attributes | |
4363 | @subsubsection Package Clean Attributes | |
4364 | ||
4365 | @itemize @bullet | |
4366 | ||
d77cfab2 | 4367 | @item @b{Switches}: list |
761f7dcb AC |
4368 | |
4369 | Value is a list of switches to be used by the cleaning application. | |
4370 | ||
4371 | @item @b{Source_Artifact_Extensions}: list, indexed, case-insensitive index | |
4372 | ||
4373 | Index is a language names. Value is the list of extensions for file names | |
4374 | derived from object file names that need to be cleaned in the object | |
4375 | directory of the project. | |
4376 | ||
4377 | @item @b{Object_Artifact_Extensions}: list, indexed, case-insensitive index | |
4378 | ||
4379 | Index is a language names. Value is the list of extensions for file names | |
4380 | derived from source file names that need to be cleaned in the object | |
4381 | directory of the project. | |
4382 | ||
747412b8 AC |
4383 | @item @b{Artifacts_In_Object_Dir}: single |
4384 | ||
4385 | Value is a list of file names expressed as regular expressions that are to be | |
4386 | deleted by gprclean in the object directory of the project. | |
4387 | ||
4388 | @item @b{Artifacts_In_Exec_Dir}: single | |
4389 | ||
4390 | Value is list of file names expressed as regular expressions that are to be | |
4391 | deleted by gprclean in the exec directory of the main project. | |
4392 | ||
761f7dcb AC |
4393 | @end itemize |
4394 | ||
4395 | @node Package Compiler Attributes | |
4396 | @subsubsection Package Compiler Attributes | |
4397 | ||
4398 | @itemize @bullet | |
4399 | ||
4400 | @item @b{General} | |
4401 | ||
4402 | @itemize @bullet | |
4403 | ||
4404 | @item @b{Default_Switches}: list, indexed, case-insensitive index | |
4405 | ||
4406 | Index is a language name. Value is a list of switches to be used when invoking | |
4407 | the compiler for the language for a source of the project, if there is no | |
4408 | applicable attribute Switches. | |
4409 | ||
d77cfab2 | 4410 | @item @b{Switches}: list, optional index, indexed, case-insensitive index, |
761f7dcb AC |
4411 | others allowed |
4412 | ||
4413 | Index is a source file name or a language name. Value is the list of switches | |
4414 | to be used when invoking the compiler for the source or for its language. | |
4415 | ||
4416 | @item @b{Local_Configuration_Pragmas}: single | |
4417 | ||
4418 | Value is the file name of a configuration pragmas file that is specified to | |
4419 | the Ada compiler when compiling any Ada source in the project. | |
4420 | ||
4421 | @item @b{Local_Config_File}: single, indexed, case-insensitive index | |
4422 | ||
4423 | Index is a language name. Value is the file name of a configuration file that | |
4424 | is specified to the compiler when compiling any source of the language in the | |
4425 | project. | |
4426 | ||
4427 | @end itemize | |
4428 | ||
4429 | @item @b{Configuration - Compiling} | |
4430 | ||
4431 | @itemize @bullet | |
4432 | ||
4433 | @item @b{Driver}: single, indexed, case-insensitive index | |
4434 | ||
4435 | Index is a language name. Value is the name of the executable for the compiler | |
4436 | of the language. | |
4437 | ||
4438 | @item @b{Language_Kind}: single, indexed, case-insensitive index | |
4439 | ||
4440 | Index is a language name. Indicates the kind of the language, either file based | |
4441 | or unit based. Only authorized case-insensitive values are "unit_based" and | |
4442 | "file_based" (the default). | |
4443 | ||
cc55f9be | 4444 | @item @b{Dependency_Kind}: single, indexed, case-insensitive index |
761f7dcb AC |
4445 | |
4446 | Index is a language name. Indicates how the dependencies are handled for the | |
4447 | language. Only authorized case-insensitive values are "makefile", "ali_file", | |
cc55f9be | 4448 | "ali_closure" or "none" (the default). |
761f7dcb AC |
4449 | |
4450 | @item @b{Required_Switches}: list, indexed, case-insensitive index | |
4451 | ||
4452 | Equivalent to attribute Leading_Required_Switches. | |
4453 | ||
4454 | @item @b{Leading_Required_Switches}: list, indexed, case-insensitive index | |
4455 | ||
4456 | Index is a language name. Value is the list of the minimum switches to be used | |
4457 | at the beginning of the command line when invoking the compiler for the | |
4458 | language. | |
4459 | ||
4460 | @item @b{Trailing_Required_Switches}: list, indexed, case-insensitive index | |
4461 | ||
4462 | Index is a language name. Value is the list of the minimum switches to be used | |
4463 | at the end of the command line when invoking the compiler for the language. | |
4464 | ||
4465 | @item @b{PIC_Option}: list, indexed, case-insensitive index | |
4466 | ||
4467 | Index is a language name. Value is the list of switches to be used when | |
4468 | compiling a source of the language when the project is a shared library | |
4469 | project. | |
4470 | ||
4471 | @item @b{Path_Syntax}: single, indexed, case-insensitive index | |
4472 | ||
4473 | Index is a language name. Value is the kind of path syntax to be used when | |
4474 | invoking the compiler for the language. Only authorized case-insensitive | |
4475 | values are "canonical" and "host" (the default). | |
4476 | ||
4477 | @item @b{Source_File_Switches}: single, indexed, case-insensitive index | |
4478 | ||
4479 | Index is a language name. Value is a list of switches to be used just before | |
4480 | the path name of the source to compile when invoking the compiler for a source | |
4481 | of the language. | |
4482 | ||
4483 | @item @b{Object_File_Suffix}: single, indexed, case-insensitive index | |
4484 | ||
4485 | Index is a language name. Value is the extension of the object files created | |
4486 | by the compiler of the language. When not specified, the extension is the | |
4487 | default one for the platform. | |
4488 | ||
4489 | @item @b{Object_File_Switches}: list, indexed, case-insensitive index | |
4490 | ||
4491 | Index is a language name. Value is the list of switches to be used by the | |
4492 | compiler of the language to specify the path name of the object file. When not | |
4493 | specified, the switch used is "-o". | |
4494 | ||
4495 | @item @b{Multi_Unit_Switches}: list, indexed, case-insensitive index | |
4496 | ||
4497 | Index is a language name. Value is the list of switches to be used to compile | |
4498 | a unit in a multi unit source of the language. The index of the unit in the | |
4499 | source is concatenated with the last switches in the list. | |
4500 | ||
4501 | @item @b{Multi_Unit_Object_Separator}: single, indexed, case-insensitive index | |
4502 | ||
4503 | Index is a language name. Value is the string to be used in the object file | |
4504 | name before the index of the unit, when compiling a unit in a multi unit source | |
4505 | of the language. | |
4506 | ||
4507 | @end itemize | |
4508 | ||
4509 | @item @b{Configuration - Mapping Files} | |
4510 | ||
4511 | @itemize @bullet | |
4512 | ||
4513 | @item @b{Mapping_File_Switches}: list, indexed, case-insensitive index | |
4514 | ||
4515 | Index is a language name. Value is the list of switches to be used to specify | |
4516 | a mapping file when invoking the compiler for a source of the language. | |
4517 | ||
4518 | @item @b{Mapping_Spec_Suffix}: single, indexed, case-insensitive index | |
4519 | ||
4520 | Index is a language name. Value is the suffix to be used in a mapping file | |
4521 | to indicate that the source is a spec. | |
4522 | ||
4523 | @item @b{Mapping_Body_Suffix}: single, indexed, case-insensitive index | |
4524 | ||
4525 | Index is a language name. Value is the suffix to be used in a mapping file | |
4526 | to indicate that the source is a body. | |
4527 | ||
4528 | @end itemize | |
4529 | ||
4530 | @item @b{Configuration - Config Files} | |
4531 | ||
4532 | @itemize @bullet | |
4533 | ||
4534 | @item @b{Config_File_Switches}: list: single, indexed, case-insensitive index | |
4535 | ||
4536 | Index is a language name. Value is the list of switches to specify to the | |
4537 | compiler of the language a configuration file. | |
4538 | ||
4539 | @item @b{Config_Body_File_Name}: single, indexed, case-insensitive index | |
4540 | ||
4541 | Index is a language name. Value is the template to be used to indicate a | |
4542 | configuration specific to a body of the language in a configuration | |
4543 | file. | |
4544 | ||
4545 | @item @b{Config_Body_File_Name_Index}: single, indexed, case-insensitive index | |
4546 | ||
4547 | Index is a language name. Value is the template to be used to indicate a | |
4548 | configuration specific to the body a unit in a multi unit source of the | |
4549 | language in a configuration file. | |
4550 | ||
4551 | @item @b{Config_Body_File_Name_Pattern}: single, indexed, | |
4552 | case-insensitive index | |
4553 | ||
4554 | Index is a language name. Value is the template to be used to indicate a | |
4555 | configuration for all bodies of the languages in a configuration file. | |
4556 | ||
4557 | @item @b{Config_Spec_File_Name}: single, indexed, case-insensitive index | |
4558 | ||
4559 | Index is a language name. Value is the template to be used to indicate a | |
4560 | configuration specific to a spec of the language in a configuration | |
4561 | file. | |
4562 | ||
4563 | @item @b{Config_Spec_File_Name_Index}: single, indexed, case-insensitive index | |
4564 | ||
4565 | Index is a language name. Value is the template to be used to indicate a | |
4566 | configuration specific to the spec a unit in a multi unit source of the | |
4567 | language in a configuration file. | |
4568 | ||
4569 | @item @b{Config_Spec_File_Name_Pattern}: single, indexed, | |
4570 | case-insensitive index | |
4571 | ||
4572 | Index is a language name. Value is the template to be used to indicate a | |
4573 | configuration for all specs of the languages in a configuration file. | |
4574 | ||
4575 | @item @b{Config_File_Unique}: single, indexed, case-insensitive index | |
4576 | ||
4577 | Index is a language name. Indicates if there should be only one configuration | |
4578 | file specified to the compiler of the language. Only authorized | |
4579 | case-insensitive values are "true" and "false" (the default). | |
4580 | ||
4581 | @end itemize | |
4582 | ||
4583 | @item @b{Configuration - Dependencies} | |
4584 | ||
4585 | @itemize @bullet | |
4586 | ||
4587 | @item @b{Dependency_Switches}: list, indexed, case-insensitive index | |
4588 | ||
4589 | Index is a language name. Value is the list of switches to be used to specify | |
4590 | to the compiler the dependency file when the dependency kind of the language is | |
4591 | file based, and when Dependency_Driver is not specified for the language. | |
4592 | ||
4593 | @item @b{Dependency_Driver}: list, indexed, case-insensitive index | |
4594 | ||
4595 | Index is a language name. Value is the name of the executable to be used to | |
4596 | create the dependency file for a source of the language, followed by the | |
4597 | required switches. | |
4598 | ||
4599 | @end itemize | |
4600 | ||
4601 | @item @b{Configuration - Search Paths} | |
4602 | ||
4603 | @itemize @bullet | |
4604 | ||
4605 | @item @b{Include_Switches}: list, indexed, case-insensitive index | |
4606 | ||
4607 | Index is a language name. Value is the list of switches to specify to the | |
4608 | compiler of the language to indicate a directory to look for sources. | |
4609 | ||
4610 | @item @b{Include_Path}: single, indexed, case-insensitive index | |
4611 | ||
4612 | Index is a language name. Value is the name of an environment variable that | |
4613 | contains the path of all the directories that the compiler of the language | |
4614 | may search for sources. | |
4615 | ||
4616 | @item @b{Include_Path_File}: single, indexed, case-insensitive index | |
4617 | ||
4618 | Index is a language name. Value is the name of an environment variable the | |
4619 | value of which is the path name of a text file that contains the directories | |
4620 | that the compiler of the language may search for sources. | |
4621 | ||
4622 | @item @b{Object_Path_Switches}: list, indexed, case-insensitive index | |
4623 | ||
4624 | Index is a language name. Value is the list of switches to specify to the | |
4625 | compiler of the language the name of a text file that contains the list of | |
4626 | object directories. When this attribute is not declared, the text file is | |
4627 | not created. | |
4628 | ||
4629 | @end itemize | |
4630 | ||
4631 | @end itemize | |
4632 | ||
4633 | @node Package Cross_Reference Attributes | |
4634 | @subsubsection Package Cross_Reference Attributes | |
4635 | ||
4636 | @itemize @bullet | |
4637 | ||
4638 | @item @b{Default_Switches}: list, indexed, case-insensitive index | |
4639 | ||
4640 | Index is a language name. Value is a list of switches to be used when invoking | |
4641 | @code{gnatxref} for a source of the language, if there is no applicable | |
4642 | attribute Switches. | |
4643 | ||
d77cfab2 | 4644 | @item @b{Switches}: list, optional index, indexed, case-insensitive index, |
761f7dcb AC |
4645 | others allowed |
4646 | ||
4647 | Index is a source file name. Value is the list of switches to be used when | |
4648 | invoking @code{gnatxref} for the source. | |
4649 | ||
4650 | @end itemize | |
4651 | ||
1037b0f4 | 4652 | @ifclear FSFEDITION |
761f7dcb AC |
4653 | @node Package Eliminate Attributes |
4654 | @subsubsection Package Eliminate Attributes | |
4655 | ||
4656 | @itemize @bullet | |
4657 | ||
4658 | @item @b{Default_Switches}: list, indexed, case-insensitive index | |
4659 | ||
4660 | Index is a language name. Value is a list of switches to be used when invoking | |
4661 | @code{gnatelim} for a source of the language, if there is no applicable | |
4662 | attribute Switches. | |
4663 | ||
d77cfab2 | 4664 | @item @b{Switches}: list, optional index, indexed, case-insensitive index, |
761f7dcb AC |
4665 | others allowed |
4666 | ||
4667 | Index is a source file name. Value is the list of switches to be used when | |
4668 | invoking @code{gnatelim} for the source. | |
4669 | ||
4670 | @end itemize | |
1037b0f4 | 4671 | @end ifclear |
761f7dcb AC |
4672 | |
4673 | @node Package Finder Attributes | |
4674 | @subsubsection Package Finder Attributes | |
4675 | ||
4676 | @itemize @bullet | |
4677 | ||
4678 | @item @b{Default_Switches}: list, indexed, case-insensitive index | |
4679 | ||
4680 | Index is a language name. Value is a list of switches to be used when invoking | |
4681 | @code{gnatfind} for a source of the language, if there is no applicable | |
4682 | attribute Switches. | |
4683 | ||
d77cfab2 | 4684 | @item @b{Switches}: list, optional index, indexed, case-insensitive index, |
761f7dcb AC |
4685 | others allowed |
4686 | ||
4687 | Index is a source file name. Value is the list of switches to be used when | |
4688 | invoking @code{gnatfind} for the source. | |
4689 | ||
4690 | @end itemize | |
4691 | ||
d77cfab2 AC |
4692 | @node Package gnatls Attributes |
4693 | @subsubsection Package gnatls Attributes | |
761f7dcb AC |
4694 | |
4695 | @itemize @bullet | |
4696 | ||
d77cfab2 | 4697 | @item @b{Switches}: list |
761f7dcb AC |
4698 | |
4699 | Value is a list of switches to be used when invoking @code{gnatls}. | |
4700 | ||
4701 | @end itemize | |
4702 | ||
1037b0f4 | 4703 | @ifclear FSFEDITION |
d77cfab2 AC |
4704 | @node Package gnatstub Attributes |
4705 | @subsubsection Package gnatstub Attributes | |
761f7dcb AC |
4706 | |
4707 | @itemize @bullet | |
4708 | ||
4709 | @item @b{Default_Switches}: list, indexed, case-insensitive index | |
4710 | ||
4711 | Index is a language name. Value is a list of switches to be used when invoking | |
4712 | @code{gnatstub} for a source of the language, if there is no applicable | |
d77cfab2 | 4713 | attribute Switches. |
761f7dcb | 4714 | |
d77cfab2 | 4715 | @item @b{Switches}: list, optional index, indexed, case-insensitive index, |
761f7dcb AC |
4716 | others allowed |
4717 | ||
4718 | Index is a source file name. Value is the list of switches to be used when | |
4719 | invoking @code{gnatstub} for the source. | |
4720 | ||
4721 | @end itemize | |
1037b0f4 | 4722 | @end ifclear |
761f7dcb AC |
4723 | |
4724 | @node Package IDE Attributes | |
4725 | @subsubsection Package IDE Attributes | |
4726 | ||
4727 | @itemize @bullet | |
4728 | ||
4729 | @item @b{Default_Switches}: list, indexed | |
4730 | ||
4731 | Index is the name of an external tool that the GNAT Programming System (GPS) | |
4732 | is supporting. Value is a list of switches to use when invoking that tool. | |
4733 | ||
4734 | @item @b{Remote_Host}: single | |
4735 | ||
4736 | Value is a string that designates the remote host in a cross-compilation | |
4737 | environment, to be used for remote compilation and debugging. This attribute | |
4738 | should not be specified when running on the local machine. | |
4739 | ||
4740 | @item @b{Program_Host}: single | |
4741 | ||
4742 | Value is a string that specifies the name of IP address of the embedded target | |
4743 | in a cross-compilation environment, on which the program should execute. | |
4744 | ||
4745 | @item @b{Communication_Protocol}: single | |
4746 | ||
4747 | Value is the name of the protocol to use to communicate with the target | |
4748 | in a cross-compilation environment, for example @code{"wtx"} or | |
4749 | @code{"vxworks"}. | |
4750 | ||
4751 | @item @b{Compiler_Command}: single, indexed, case-insensitive index | |
4752 | ||
4753 | Index is a language Name. Value is a string that denotes the command to be | |
4754 | used to invoke the compiler. The value of @code{Compiler_Command ("Ada")} is | |
4755 | expected to be compatible with @command{gnatmake}, in particular in | |
4756 | the handling of switches. | |
4757 | ||
4758 | @item @b{Debugger_Command}: single | |
4759 | ||
4760 | Value is a string that specifies the name of the debugger to be used, such as | |
4761 | gdb, powerpc-wrs-vxworks-gdb or gdb-4. | |
4762 | ||
d77cfab2 | 4763 | @item @b{gnatlist}: single |
761f7dcb | 4764 | |
d77cfab2 | 4765 | Value is a string that specifies the name of the @command{gnatls} utility |
761f7dcb | 4766 | to be used to retrieve information about the predefined path; for example, |
d77cfab2 | 4767 | @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}. |
761f7dcb AC |
4768 | |
4769 | @item @b{VCS_Kind}: single | |
4770 | ||
4771 | Value is a string used to specify the Version Control System (VCS) to be used | |
7b56a91b AC |
4772 | for this project, for example "Subversion", "ClearCase". If the |
4773 | value is set to "Auto", the IDE will try to detect the actual VCS used | |
4774 | on the list of supported ones. | |
761f7dcb AC |
4775 | |
4776 | @item @b{VCS_File_Check}: single | |
4777 | ||
4778 | Value is a string that specifies the command used by the VCS to check | |
4779 | the validity of a file, either when the user explicitly asks for a check, | |
4780 | or as a sanity check before doing the check-in. | |
4781 | ||
4782 | @item @b{VCS_Log_Check}: single | |
4783 | ||
4784 | Value is a string that specifies the command used by the VCS to check | |
4785 | the validity of a log file. | |
4786 | ||
4787 | @item @b{Documentation_Dir}: single | |
4788 | ||
4789 | Value is the directory used to generate the documentation of source code. | |
4790 | ||
4791 | @end itemize | |
4792 | ||
4793 | @node Package Install Attributes | |
4794 | @subsubsection Package Install Attributes | |
4795 | ||
4796 | @itemize @bullet | |
4797 | ||
88305f17 AC |
4798 | @item @b{Artifacts}: list, indexed |
4799 | ||
4800 | An array attribute to declare a set of files not part of the sources | |
4801 | to be installed. The array discriminant is the directory where the | |
4802 | file is to be installed. If a relative directory then Prefix (see | |
4803 | below) is prepended. | |
4804 | ||
761f7dcb AC |
4805 | @item @b{Prefix}: single |
4806 | ||
4807 | Value is the install destination directory. | |
4808 | ||
4809 | @item @b{Sources_Subdir}: single | |
4810 | ||
4811 | Value is the sources directory or subdirectory of Prefix. | |
4812 | ||
4813 | @item @b{Exec_Subdir}: single | |
4814 | ||
4815 | Value is the executables directory or subdirectory of Prefix. | |
4816 | ||
4817 | @item @b{Lib_Subdir}: single | |
4818 | ||
4819 | Value is library directory or subdirectory of Prefix. | |
4820 | ||
4821 | @item @b{Project_Subdir}: single | |
4822 | ||
4823 | Value is the project directory or subdirectory of Prefix. | |
4824 | ||
4825 | @item @b{Active}: single | |
4826 | ||
4827 | Indicates that the project is to be installed or not. Case-insensitive value | |
4828 | "false" means that the project is not to be installed, all other values mean | |
4829 | that the project is to be installed. | |
4830 | ||
bb6c60f4 AC |
4831 | @item @b{Mode}: single |
4832 | ||
4833 | Value is the installation mode, it is either @b{dev} (default) or @b{usage}. | |
4834 | ||
4835 | @item @b{Install_Name}: single | |
4836 | ||
4837 | Specify the name to use for recording the installation. The default is | |
4838 | the project name without the extension. | |
4839 | ||
761f7dcb AC |
4840 | @end itemize |
4841 | ||
4842 | @node Package Linker Attributes | |
4843 | @subsubsection Package Linker Attributes | |
4844 | ||
4845 | @itemize @bullet | |
4846 | ||
4847 | @item @b{General} | |
4848 | ||
4849 | @itemize @bullet | |
4850 | ||
4851 | @item @b{Required_Switches}: list | |
4852 | ||
4853 | Value is a list of switches that are required when invoking the linker to link | |
4854 | an executable. | |
4855 | ||
4856 | @item @b{Default_Switches}: list, indexed, case-insensitive index | |
4857 | ||
4858 | Index is a language name. Value is a list of switches for the linker when | |
4859 | linking an executable for a main source of the language, when there is no | |
4860 | applicable Switches. | |
4861 | ||
4862 | @item @b{Leading_Switches}: list, optional index, indexed, | |
4863 | case-insensitive index, others allowed | |
4864 | ||
4865 | Index is a source file name or a language name. Value is the list of switches | |
4866 | to be used at the beginning of the command line when invoking the linker to | |
4867 | build an executable for the source or for its language. | |
4868 | ||
d77cfab2 | 4869 | @item @b{Switches}: list, optional index, indexed, case-insensitive index, |
761f7dcb AC |
4870 | others allowed |
4871 | ||
4872 | Index is a source file name or a language name. Value is the list of switches | |
4873 | to be used when invoking the linker to build an executable for the source or | |
4874 | for its language. | |
4875 | ||
4876 | @item @b{Trailing_Switches}: list, optional index, indexed, | |
4877 | case-insensitive index, others allowed | |
4878 | ||
4879 | Index is a source file name or a language name. Value is the list of switches | |
4880 | to be used at the end of the command line when invoking the linker to | |
4881 | build an executable for the source or for its language. These switches may | |
4882 | override the Required_Switches. | |
4883 | ||
4884 | @item @b{Linker_Options}: list | |
4885 | ||
4886 | Value is a list of switches/options that are to be added when linking an | |
4887 | executable from a project importing the current project directly or indirectly. | |
4888 | Linker_Options are not used when linking an executable from the current | |
4889 | project. | |
4890 | ||
4891 | @item @b{Map_File_Option}: single | |
4892 | ||
4893 | Value is the switch to specify the map file name that the linker needs to | |
4894 | create. | |
4895 | ||
4896 | @end itemize | |
4897 | ||
4898 | @item @b{Configuration - Linking} | |
4899 | ||
4900 | @itemize @bullet | |
4901 | ||
4902 | @item @b{Driver}: single | |
4903 | ||
4904 | Value is the name of the linker executable. | |
4905 | ||
4906 | @end itemize | |
4907 | ||
4908 | @item @b{Configuration - Response Files} | |
4909 | ||
4910 | @itemize @bullet | |
4911 | ||
4912 | @item @b{Max_Command_Line_Length}: single | |
4913 | ||
4914 | Value is the maximum number of character in the command line when invoking | |
4915 | the linker to link an executable. | |
4916 | ||
4917 | @item @b{Response_File_Format}: single | |
4918 | ||
4919 | Indicates the kind of response file to create when the length of the linking | |
4920 | command line is too large. Only authorized case-insensitive values are "none", | |
4921 | "gnu", "object_list", "gcc_gnu", "gcc_option_list" and "gcc_object_list". | |
4922 | ||
4923 | @item @b{Response_File_Switches}: list | |
4924 | ||
4925 | Value is the list of switches to specify a response file to the linker. | |
4926 | ||
4927 | @end itemize | |
4928 | ||
4929 | @end itemize | |
4930 | ||
1037b0f4 | 4931 | @ifclear FSFEDITION |
761f7dcb AC |
4932 | @node Package Metrics Attribute |
4933 | @subsubsection Package Metrics Attribute | |
4934 | ||
4935 | @itemize @bullet | |
4936 | ||
4937 | @item @b{Default_Switches}: list, indexed, case-insensitive index | |
4938 | ||
4939 | Index is a language name. Value is a list of switches to be used when invoking | |
4940 | @code{gnatmetric} for a source of the language, if there is no applicable | |
4941 | attribute Switches. | |
4942 | ||
d77cfab2 | 4943 | @item @b{Switches}: list, optional index, indexed, case-insensitive index, |
761f7dcb AC |
4944 | others allowed |
4945 | ||
4946 | Index is a source file name. Value is the list of switches to be used when | |
4947 | invoking @code{gnatmetric} for the source. | |
4948 | ||
4949 | @end itemize | |
1037b0f4 | 4950 | @end ifclear |
761f7dcb AC |
4951 | |
4952 | @node Package Naming Attributes | |
4953 | @subsubsection Package Naming Attributes | |
4954 | ||
4955 | @itemize @bullet | |
4956 | ||
4957 | @item @b{Specification_Suffix}: single, indexed, case-insensitive index | |
4958 | ||
4959 | Equivalent to attribute Spec_Suffix. | |
4960 | ||
4961 | @item @b{Spec_Suffix}: single, indexed, case-insensitive index | |
4962 | ||
4963 | Index is a language name. Value is the extension of file names for specs of | |
4964 | the language. | |
4965 | ||
4966 | @item @b{Implementation_Suffix}: single, indexed, case-insensitive index | |
4967 | ||
4968 | Equivalent to attribute Body_Suffix. | |
4969 | ||
4970 | @item @b{Body_Suffix}: single, indexed, case-insensitive index | |
4971 | ||
4972 | Index is a language name. Value is the extension of file names for bodies of | |
4973 | the language. | |
4974 | ||
4975 | @item @b{Separate_Suffix}: single | |
4976 | ||
4977 | Value is the extension of file names for subunits of Ada. | |
4978 | ||
4979 | @item @b{Casing}: single | |
4980 | ||
4981 | Indicates the casing of sources of the Ada language. Only authorized | |
4982 | case-insensitive values are "lowercase", "uppercase" and "mixedcase". | |
4983 | ||
4984 | @item @b{Dot_Replacement}: single | |
4985 | ||
4986 | Value is the string that replace the dot of unit names in the source file names | |
4987 | of the Ada language. | |
4988 | ||
4989 | @item @b{Specification}: single, optional index, indexed, | |
4990 | case-insensitive index | |
4991 | ||
4992 | Equivalent to attribute Spec. | |
4993 | ||
4994 | @item @b{Spec}: single, optional index, indexed, case-insensitive index | |
4995 | ||
4996 | Index is a unit name. Value is the file name of the spec of the unit. | |
4997 | ||
4998 | @item @b{Implementation}: single, optional index, indexed, | |
4999 | case-insensitive index | |
5000 | ||
5001 | Equivalent to attribute Body. | |
5002 | ||
5003 | @item @b{Body}: single, optional index, indexed, case-insensitive index | |
5004 | ||
5005 | Index is a unit name. Value is the file name of the body of the unit. | |
5006 | ||
5007 | @item @b{Specification_Exceptions}: list, indexed, case-insensitive index | |
5008 | ||
5009 | Index is a language name. Value is a list of specs for the language that do not | |
5010 | necessarily follow the naming scheme for the language and that may or may not | |
5011 | be found in the source directories of the project. | |
5012 | ||
5013 | @item @b{Implementation_Exceptions}: list, indexed, case-insensitive index | |
5014 | ||
5015 | Index is a language name. Value is a list of bodies for the language that do not | |
5016 | necessarily follow the naming scheme for the language and that may or may not | |
5017 | be found in the source directories of the project. | |
5018 | ||
5019 | @end itemize | |
5020 | ||
1037b0f4 | 5021 | @ifclear FSFEDITION |
761f7dcb AC |
5022 | @node Package Pretty_Printer Attributes |
5023 | @subsubsection Package Pretty_Printer Attributes | |
5024 | ||
5025 | @itemize @bullet | |
5026 | ||
5027 | @item @b{Default_Switches}: list, indexed, case-insensitive index | |
5028 | ||
5029 | Index is a language name. Value is a list of switches to be used when invoking | |
5030 | @code{gnatpp} for a source of the language, if there is no applicable | |
5031 | attribute Switches. | |
5032 | ||
d77cfab2 | 5033 | @item @b{Switches}: list, optional index, indexed, case-insensitive index, |
761f7dcb AC |
5034 | others allowed |
5035 | ||
5036 | Index is a source file name. Value is the list of switches to be used when | |
5037 | invoking @code{gnatpp} for the source. | |
5038 | ||
5039 | @end itemize | |
1037b0f4 | 5040 | @end ifclear |
761f7dcb AC |
5041 | |
5042 | @node Package Remote Attributes | |
5043 | @subsubsection Package Remote Attributes | |
5044 | ||
5045 | @itemize @bullet | |
5046 | ||
5216b599 AC |
5047 | @item @b{Included_Patterns}: list |
5048 | ||
5049 | If this attribute is defined it sets the patterns to | |
5050 | synchronized from the master to the slaves. It is exclusive | |
5051 | with Excluded_Patterns, that is it is an error to define | |
5052 | both. | |
5053 | ||
5054 | @item @b{Included_Artifact_Patterns}: list | |
5055 | ||
5056 | If this attribute is defined it sets the patterns of compilation | |
5057 | artifacts to synchronized from the slaves to the build master. | |
5058 | This attribute replace the default hard-coded patterns. | |
5059 | ||
0567ae8d | 5060 | @item @b{Excluded_Patterns}: list |
761f7dcb | 5061 | |
0567ae8d AC |
5062 | Set of patterns to ignore when synchronizing sources from the build |
5063 | master to the slaves. A set of predefined patterns are supported | |
5064 | (e.g. *.o, *.ali, *.exe, etc.), this attributes make it possible to | |
5065 | add some more patterns. | |
761f7dcb AC |
5066 | |
5067 | @item @b{Root_Dir}: single | |
5068 | ||
5069 | Value is the root directory used by the slave machines. | |
5070 | ||
5071 | @end itemize | |
5072 | ||
5073 | @node Package Stack Attributes | |
5074 | @subsubsection Package Stack Attributes | |
5075 | ||
5076 | @itemize @bullet | |
5077 | ||
d77cfab2 | 5078 | @item @b{Switches}: list |
761f7dcb AC |
5079 | |
5080 | Value is the list of switches to be used when invoking @code{gnatstack}. | |
5081 | ||
5082 | @end itemize | |
5083 | ||
5084 | @node Package Synchronize Attributes | |
5085 | @subsubsection Package Synchronize Attributes | |
5086 | ||
5087 | @itemize @bullet | |
5088 | ||
5089 | @item @b{Default_Switches}: list, indexed, case-insensitive index | |
5090 | ||
5091 | Index is a language name. Value is a list of switches to be used when invoking | |
5092 | @code{gnatsync} for a source of the language, if there is no applicable | |
5093 | attribute Switches. | |
5094 | ||
d77cfab2 | 5095 | @item @b{Switches}: list, optional index, indexed, case-insensitive index, |
761f7dcb AC |
5096 | others allowed |
5097 | ||
5098 | Index is a source file name. Value is the list of switches to be used when | |
5099 | invoking @code{gnatsync} for the source. | |
5100 | ||
5101 | @end itemize |