From 5f5f7b7d730a2065a784c089af386a593ee4b575 Mon Sep 17 00:00:00 2001 From: Arnaud Charlet Date: Mon, 4 Jul 2016 12:57:30 +0000 Subject: [PATCH] Update documentation. From-SVN: r237979 --- gcc/ada/ChangeLog | 18 + .../implementation_defined_attributes.rst | 8 +- .../implementation_defined_pragmas.rst | 36 +- .../representation_clauses_and_pragmas.rst | 8 +- ...nd_implementation_defined_restrictions.rst | 28 +- gcc/ada/doc/gnat_ugn.rst | 2 - gcc/ada/doc/gnat_ugn/about_this_guide.rst | 6 - ...building_executable_programs_with_gnat.rst | 22 +- .../elaboration_order_handling_in_gnat.rst | 93 +- .../gnat_ugn/gnat_and_program_execution.rst | 8 + gcc/ada/doc/gnat_ugn/gnat_project_manager.rst | 4887 ----------------- .../doc/gnat_ugn/gnat_utility_programs.rst | 319 +- .../platform_specific_information.rst | 83 +- .../gnat_ugn/the_gnat_compilation_model.rst | 30 +- .../tools_supporting_project_files.rst | 745 --- 15 files changed, 487 insertions(+), 5806 deletions(-) delete mode 100644 gcc/ada/doc/gnat_ugn/gnat_project_manager.rst delete mode 100644 gcc/ada/doc/gnat_ugn/tools_supporting_project_files.rst diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog index 44ee116c017..399452bdcd6 100644 --- a/gcc/ada/ChangeLog +++ b/gcc/ada/ChangeLog @@ -1,3 +1,21 @@ +2016-07-04 Arnaud Charlet + + * gnat_rm.texi, gnat_ugn.texi, + doc/gnat_ugn/gnat_project_manager.rst, + doc/gnat_ugn/building_executable_programs_with_gnat.rst, + doc/gnat_ugn/elaboration_order_handling_in_gnat.rst, + doc/gnat_ugn/about_this_guide.rst, + doc/gnat_ugn/platform_specific_information.rst, + doc/gnat_ugn/tools_supporting_project_files.rst, + doc/gnat_ugn/gnat_and_program_execution.rst, + doc/gnat_ugn/gnat_utility_programs.rst, + doc/gnat_ugn/the_gnat_compilation_model.rst, + doc/gnat_rm/implementation_defined_attributes.rst, + doc/gnat_rm/implementation_defined_pragmas.rst, + doc/gnat_rm/representation_clauses_and_pragmas.rst, + doc/gnat_rm/standard_and_implementation_defined_restrictions.rst, + doc/gnat_ugn.rst: Update documentation. + 2016-07-04 Arnaud Charlet * gcc-interface/Makefile.in: Cleanups. diff --git a/gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst b/gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst index 958ab2413f7..5c7f8012104 100644 --- a/gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst +++ b/gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst @@ -966,9 +966,6 @@ types. This may be overridden for the derived type by giving an explicit scalar storage order for the derived type. For a record extension, the derived type must have the same scalar storage order as the parent type. -If a component of `T` is of a record or array type, then that type must -also have a `Scalar_Storage_Order` attribute definition clause. - A component of a record or array type that is a bit-packed array, or that does not start on a byte boundary, must have the same scalar storage order as the enclosing record or array type. @@ -1005,6 +1002,11 @@ inheritance in the case of a derived type), then the default is normally the native ordering of the target, but this default can be overridden using pragma `Default_Scalar_Storage_Order`. +Note that if a component of `T` is itself of a record or array type, +the specfied `Scalar_Storage_Order` does *not* apply to that nested type: +an explicit attribute definition clause must be provided for the component +type as well if desired. + Note that the scalar storage order only affects the in-memory data representation. It has no effect on the representation used by stream attributes. diff --git a/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst b/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst index b2cb149a252..78ee2f65d04 100644 --- a/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst +++ b/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst @@ -196,7 +196,7 @@ Ada 83, Ada 95, or Ada 2005 programs. The one argument form, which is not a configuration pragma, is used for managing the transition from Ada 2005 to Ada 2012 in the run-time library. If an entity is marked -as Ada_201 only, then referencing the entity in any pre-Ada_2012 +as Ada_2012 only, then referencing the entity in any pre-Ada_2012 mode will generate a warning. In addition, in any pre-Ada_2012 mode, a preference rule is established which does not choose such an entity unless it is unambiguously specified. This avoids @@ -6821,6 +6821,40 @@ the handling of existing code which depends on the interpretation of Size as implemented in the VADS compiler. See description of the VADS_Size attribute for further details. +.. _Pragma-Unused: + +Pragma Unused +============= +.. index:: Warnings, unused + +Syntax: + + +:: + + pragma Unused (LOCAL_NAME {, LOCAL_NAME}); + + +This pragma signals that the assignable entities (variables, +`out` parameters, and `in out` parameters) whose names are listed +deliberately do not get assigned or referenced in the current source unit +after the occurrence of the pragma in the current source unit. This +suppresses warnings about the entities that are unreferenced and/or not +assigned, and, in addition, a warning will be generated if one of these +entities gets assigned or subsequently referenced in the same unit as the +pragma (in the corresponding body or one of its subunits). + +This is particularly useful for clearly signaling that a particular +parameter is not modified or referenced, even though the spec suggests +that it might be. + +For the variable case, warnings are never given for unreferenced +variables whose name contains one of the substrings +`DISCARD, DUMMY, IGNORE, JUNK, UNUSED` in any casing. Such names +are typically to be used in cases where such warnings are expected. +Thus it is never necessary to use `pragma Unmodified` for such +variables, though it is harmless to do so. + Pragma Validity_Checks ====================== diff --git a/gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst b/gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst index 0a3dd4a9112..0af4ce74ccb 100644 --- a/gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst +++ b/gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst @@ -53,9 +53,9 @@ values are as follows: For arrays, the alignment is equal to the alignment of the component type for the normal case where no packing or component size is given. If the array is packed, and the packing is effective (see separate section on - packed arrays), then the alignment will be either 4, 2 or 1 for long packed + packed arrays), then the alignment will be either 4, 2, or 1 for long packed arrays or arrays whose length is not known at compile time, depending on - whether the component size is divisible by 4, 2 or is odd. For short packed + whether the component size is divisible by 4, 2, or is odd. For short packed arrays, which are handled internally as modular types, the alignment will be as described for elementary types, e.g. a packed array of length 31 bits will have an object size of four bytes, and an alignment of 4. @@ -490,7 +490,7 @@ discrete types are as follows: The `Object_Size` for base subtypes reflect the natural hardware size in bits (run the compiler with *-gnatS* to find those values for numeric types). Enumeration types and fixed-point base subtypes have - 8, 16, 32 or 64 bits for this size, depending on the range of values + 8, 16, 32, or 64 bits for this size, depending on the range of values to be stored. * @@ -1187,7 +1187,7 @@ taken by components. We distinguish between *packable* components and Components of the following types are considered packable: * Components of an elementary type are packable unless they are aliased, - independent or of an atomic type. + independent, or of an atomic type. * Small packed arrays, where the size is statically known, are represented internally as modular integers, and so they are also packable. diff --git a/gcc/ada/doc/gnat_rm/standard_and_implementation_defined_restrictions.rst b/gcc/ada/doc/gnat_rm/standard_and_implementation_defined_restrictions.rst index 6288ebfa70b..da49056d4f1 100644 --- a/gcc/ada/doc/gnat_rm/standard_and_implementation_defined_restrictions.rst +++ b/gcc/ada/doc/gnat_rm/standard_and_implementation_defined_restrictions.rst @@ -445,20 +445,6 @@ No_Implicit_Heap_Allocations [RM D.7] No constructs are allowed to cause implicit heap allocation. -No_Implicit_Loops ------------------ -.. index:: No_Implicit_Loops - -[GNAT] This restriction ensures that the generated code does not contain any -implicit `for` loops, either by modifying -the generated code where possible, -or by rejecting any construct that would otherwise generate an implicit -`for` loop. If this restriction is active, it is possible to build -large array aggregates with all static components without generating an -intermediate temporary, and without generating a loop to initialize individual -components. Otherwise, a loop is created for arrays larger than about 5000 -scalar components. - No_Implicit_Protected_Object_Allocations ---------------------------------------- .. index:: No_Implicit_Protected_Object_Allocations @@ -969,6 +955,20 @@ Unrestricted_Access is forbidden is that it would require the prefix to be aliased, and in such cases, it can always be replaced by the standard attribute Unchecked_Access which is preferable. +No_Implicit_Loops +----------------- +.. index:: No_Implicit_Loops + +[GNAT] This restriction ensures that the generated code of the unit marked +with this restriction does not contain any implicit `for` loops, either by +modifying the generated code where possible, or by rejecting any construct +that would otherwise generate an implicit `for` loop. If this restriction is +active, it is possible to build large array aggregates with all static +components without generating an intermediate temporary, and without generating +a loop to initialize individual components. Otherwise, a loop is created for +arrays larger than about 5000 scalar components. Note that if this restriction +is set in the spec of a package, it will not apply to its body. + No_Obsolescent_Features ----------------------- .. index:: No_Obsolescent_Features diff --git a/gcc/ada/doc/gnat_ugn.rst b/gcc/ada/doc/gnat_ugn.rst index 7892160b477..d6d2ba9756b 100644 --- a/gcc/ada/doc/gnat_ugn.rst +++ b/gcc/ada/doc/gnat_ugn.rst @@ -42,8 +42,6 @@ included in the section entitled :ref:`gnu_fdl`. gnat_ugn/getting_started_with_gnat gnat_ugn/the_gnat_compilation_model gnat_ugn/building_executable_programs_with_gnat - gnat_ugn/gnat_project_manager - gnat_ugn/tools_supporting_project_files gnat_ugn/gnat_utility_programs gnat_ugn/gnat_and_program_execution diff --git a/gcc/ada/doc/gnat_ugn/about_this_guide.rst b/gcc/ada/doc/gnat_ugn/about_this_guide.rst index 467d3366b66..308a1e6ee58 100644 --- a/gcc/ada/doc/gnat_ugn/about_this_guide.rst +++ b/gcc/ada/doc/gnat_ugn/about_this_guide.rst @@ -37,12 +37,6 @@ This guide contains the following chapters: main GNAT tools to build executable programs, and it also gives examples of using the GNU make utility with GNAT. -* :ref:`GNAT_Project_Manager` describes how to use project files - to organize large projects. - -* :ref:`Tools_Supporting_Project_Files` described how to use the project - facility in conjunction with various GNAT tools. - * :ref:`GNAT_Utility_Programs` explains the various utility programs that are included in the GNAT environment diff --git a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst index 6952ee37701..d981f467057 100644 --- a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst +++ b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst @@ -27,6 +27,15 @@ Finally, this chapter provides examples of how to make use of the general GNU make mechanism in a GNAT context (see :ref:`Using_the_GNU_make_Utility`). +.. only:: PRO or GPL + + For building large systems with components possibly written + in different languages (such as Ada, C, C++ and Fortran) + and organized into subsystems and libraries, the GPRbuild + tool can be used. This tool, and the Project Manager + facility that it is based upon, is described in + *GPRbuild and GPR Companion Tools User's Guide*. + .. _The_GNAT_Make_Program_gnatmake: @@ -67,8 +76,9 @@ changes to the source program cause corresponding changes in dependencies, they will always be tracked exactly correctly by *gnatmake*. -Note that for advanced description of project structure, we recommend creating -a project file as explained in :ref:`GNAT_Project_Manager` and use the +Note that for advanced forms of project structure, we recommend creating +a project file as explained in the *GNAT_Project_Manager* chapter in the +*GPRbuild User's Guide*, and using the *gprbuild* tool which supports building with project files and works similarly to *gnatmake*. @@ -516,6 +526,8 @@ You may specify any of the following switches to *gnatmake*: :samp:`-P{project}` Use project file `project`. Only one such switch can be used. + +.. -- Comment: :ref:`gnatmake_and_Project_Files`. @@ -545,8 +557,10 @@ You may specify any of the following switches to *gnatmake*: :samp:`-u` Unique. Recompile at most the main files. It implies -c. Combined with -f, it is equivalent to calling the compiler directly. Note that using - -u with a project file and no main has a special meaning - (:ref:`Project_Files_and_Main_Subprograms`). + -u with a project file and no main has a special meaning. + +.. --Comment: + (See :ref:`Project_Files_and_Main_Subprograms`.) .. index:: -U (gnatmake) diff --git a/gcc/ada/doc/gnat_ugn/elaboration_order_handling_in_gnat.rst b/gcc/ada/doc/gnat_ugn/elaboration_order_handling_in_gnat.rst index 90b64a7f17a..4f0c3752dbf 100644 --- a/gcc/ada/doc/gnat_ugn/elaboration_order_handling_in_gnat.rst +++ b/gcc/ada/doc/gnat_ugn/elaboration_order_handling_in_gnat.rst @@ -75,7 +75,7 @@ of that unit before elaborating the unit doing the |withing|: with Unit_1; package Unit_2 is ... - + would require that both the body and spec of `Unit_1` be elaborated before the spec of `Unit_2`. However, a rule like that would be far too restrictive. In particular, it would make it impossible to have routines @@ -94,7 +94,7 @@ of the body of `Unit_1`: .. code-block:: ada Sqrt_1 : Float := Sqrt (0.1); - + The elaboration code of the body of `Unit_1` also contains: .. code-block:: ada @@ -111,7 +111,7 @@ the body `Unit_2`: .. code-block:: ada Sqrt_2 : Float := Sqrt (0.1); - + The elaboration code of the body of `Unit_2` also contains: .. code-block:: ada @@ -119,7 +119,7 @@ The elaboration code of the body of `Unit_2` also contains: if expression_2 = 2 then Q := Unit_1.Func_1; end if; - + Now the question is, which of the following orders of elaboration is acceptable: @@ -129,7 +129,7 @@ acceptable: Spec of Unit_2 Body of Unit_1 Body of Unit_2 - + or :: @@ -138,7 +138,7 @@ or Spec of Unit_1 Body of Unit_2 Body of Unit_1 - + If you carefully analyze the flow here, you will see that you cannot tell at compile time the answer to this question. If `expression_1` is not equal to 1, @@ -378,7 +378,7 @@ order of elaboration of the servers on which they depend: Unit A |withs| unit B and calls B.Func in elab code Unit B |withs| unit C, and B.Func calls C.Func - + Now if we put a pragma `Elaborate (B)` in unit `A`, this ensures that the @@ -481,14 +481,14 @@ example writing: .. code-block:: ada function One return Float; - + Q : Float := One; - + function One return Float is begin return 1.0; end One; - + will obviously raise `Program_Error` at run time, because function One will be called before its body is elaborated. In this case GNAT will generate a warning that the call will raise `Program_Error`:: @@ -510,7 +510,7 @@ generate a warning that the call will raise `Program_Error`:: 11. begin 12. null; 13. end; - + Note that in this particular case, it is likely that the call is safe, because the function `One` does not access any global variables. @@ -527,7 +527,7 @@ would prevent this reordering, and if we write: .. code-block:: ada function One return Float; - + function One return Float is begin return 1.0; @@ -586,7 +586,7 @@ raised at the point of the call. Let's look at the warning:: 13. begin 14. null; 15. end; - + Note that the message here says 'may raise', instead of the direct case, where the message says 'will be raised'. That's because whether @@ -677,7 +677,7 @@ Consider the following: begin ... end Main; - + where `Main` is the main program. When this program is executed, the elaboration code must first be executed, and one of the jobs of the binder is to determine the order in which the units of a program are @@ -813,7 +813,7 @@ switch, then the compiler outputs an information message:: | >>> info: call to "r" may raise Program_Error >>> info: missing pragma Elaborate_All for "k" - + 4. end; and these messages can be used as a guide for supplying manually @@ -840,7 +840,7 @@ the *-gnatE* switch on the compiler (*gcc* or .. code-block:: ada pragma Elaboration_Checks (DYNAMIC); - + Either approach will cause the unit affected to be compiled using the standard dynamic run-time elaboration checks described in the Ada Reference Manual. The static model is generally preferable, since it @@ -976,7 +976,7 @@ the following example begin Decls.Lib_Task.Start; end; - + If the above example is compiled in the default static elaboration mode, then a circularity occurs. The circularity comes from the call `Utils.Put_Val` in the task body of `Decls.Lib_Task`. Since @@ -1112,7 +1112,7 @@ We have four possible answers to this question: begin Decls1.Lib_Task.Start; end; - + All we have done is to split `Decls` into two packages, one containing the library task, and one containing everything else. Now @@ -1179,7 +1179,7 @@ We have four possible answers to this question: begin Declst.Lib_Task.Start; end; - + What we have done here is to replace the `task` declaration in package `Decls` with a `task type` declaration. Then we @@ -1227,7 +1227,7 @@ We have four possible answers to this question: .. code-block:: ada pragma Restrictions (No_Entry_Calls_In_Elaboration_Code); - + This pragma can be placed in the :file:`gnat.adc` file in the usual manner. If we take our original unmodified program and compile it in the presence of a :file:`gnat.adc` containing the above pragma, @@ -1288,7 +1288,7 @@ similar to that in the following example:: warning: "x.ads" has dynamic elaboration checks and with's warning: "y.ads" which has static elaboration checks - + These warnings indicate that the rule has been violated, and that as a result elaboration checks may be missed in the resulting executable file. This warning may be suppressed using the *-ws* binder switch @@ -1456,7 +1456,7 @@ Faced with a circularity of this kind, you have three different options. begin Ada.Text_IO.Put_Line(Pack1.X1'Img); -- 101 end Proc3; - + In the absence of any pragmas, an attempt to bind this program produces the following diagnostics:: @@ -1473,7 +1473,7 @@ Faced with a circularity of this kind, you have three different options. info: "pack2 (spec)" info: which is withed by: info: "pack1 (body)" - + The sources of the circularity are the two calls to `Pack2.Pure` and `Pack2.F2` in the body of `Pack1`. We can see that the call to F2 is safe, even though F2 calls F1, because the call appears after the @@ -1541,19 +1541,24 @@ fall back to run-time checks; premature calls to any primitive operation of a tagged type before the body of the operation has been elaborated will raise `Program_Error`. -Access-to-subprogram types, however, are handled conservatively, and -do not require run-time checks. This was not true in earlier versions -of the compiler; you can use the *-gnatd.U* debug switch to -revert to the old behavior if the new conservative behavior causes -elaboration cycles. Here, 'conservative' means that if you do -`P'Access` during elaboration, the compiler will assume that you -might call `P` indirectly during elaboration, so it adds an -implicit `pragma Elaborate_All` on the library unit containing -`P`. The *-gnatd.U* switch is safe if you know there are -no such calls. If the program worked before, it will continue to work -with *-gnatd.U*. But beware that code modifications such as -adding an indirect call can cause erroneous behavior in the presence -of *-gnatd.U*. +Access-to-subprogram types, however, are handled conservatively in many +cases. This was not true in earlier versions of the compiler; you can use +the *-gnatd.U* debug switch to revert to the old behavior if the new +conservative behavior causes elaboration cycles. Here, 'conservative' means +that if you do `P'Access` during elaboration, the compiler will normally +assume that you might call `P` indirectly during elaboration, so it adds an +implicit `pragma Elaborate_All` on the library unit containing `P`. The +*-gnatd.U* switch is safe if you know there are no such calls. If the +program worked before, it will continue to work with *-gnatd.U*. But beware +that code modifications such as adding an indirect call can cause erroneous +behavior in the presence of *-gnatd.U*. + +These implicit Elaborate_All pragmas are not added in all cases, because +they cause elaboration cycles in certain common code patterns. If you want +even more conservative handling of P'Access, you can use the *-gnatd.o* +switch. + +See `debug.adb` for documentation on the *-gnatd...* debug switches. .. _Summary_of_Procedures_for_Elaboration_Control: @@ -1564,7 +1569,7 @@ Summary of Procedures for Elaboration Control .. index:: Elaboration control First, compile your program with the default options, using none of -the special elaboration control switches. If the binder successfully +the special elaboration-control switches. If the binder successfully binds your program, then you can be confident that, apart from issues raised by the use of access-to-subprogram types and dynamic dispatching, the program is free of elaboration errors. If it is important that the @@ -1621,7 +1626,7 @@ requirements. Consider this example: package Init_Constants is procedure P; --* require a body* end Init_Constants; - + with Constants; package body Init_Constants is procedure P is begin null; end; @@ -1641,7 +1646,7 @@ requirements. Consider this example: begin Put_Line (Calc.Z'Img); end Main; - + In this example, there is more than one valid order of elaboration. For example both the following are correct orders:: @@ -1654,13 +1659,13 @@ example both the following are correct orders:: and :: - + Init_Constants spec Init_Constants body Constants spec Calc spec Main body - + There is no language rule to prefer one or the other, both are correct from an order of elaboration point of view. But the programmatic effects of the two orders are very different. In the first, the elaboration routine @@ -1684,7 +1689,7 @@ case, that could have been achieved by adding to the spec of Calc: .. code-block:: ada pragma Elaborate_All (Constants); - + which requires that the body (if any) and spec of `Constants`, as well as the body and spec of any unit |withed| by `Constants` be elaborated before `Calc` is elaborated. @@ -1719,7 +1724,7 @@ following output: $ gnatmake -f -q main -bargs -p $ main 0 - + It is of course quite unlikely that both these results are correct, so it is up to you in a case like this to investigate the source of the difference, by looking at the two elaboration orders that are chosen, @@ -1768,7 +1773,7 @@ the last part of the file:`b~xxx.adb` binder output file. Here is an example:: Ada.Text_Io'Elab_Spec; Ada.Text_Io'Elab_Body; E07 := True; - + Here Elab_Spec elaborates the spec and Elab_Body elaborates the body. The assignments to the :samp:`E{xx}` flags flag that the corresponding body is now elaborated. diff --git a/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst b/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst index 6cf6c6c39ab..ddce9218b36 100644 --- a/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst +++ b/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst @@ -2605,6 +2605,14 @@ appropriate options. subprograms and helps the compiler to create a smaller executable for your program. + *gnatelim* is a project-aware tool. + (See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of + the project-related switches but note that *gnatelim* does not support + the :samp:`-U`, :samp:`-U {main_unit}`, :samp:`--subdirs={dir}`, or + :samp:`--no_objects_dir` switches.) + The project file package that can specify + *gnatelim* switches is named ``Eliminate``. + .. _About_gnatelim: About `gnatelim` diff --git a/gcc/ada/doc/gnat_ugn/gnat_project_manager.rst b/gcc/ada/doc/gnat_ugn/gnat_project_manager.rst deleted file mode 100644 index 95f6ebd7183..00000000000 --- a/gcc/ada/doc/gnat_ugn/gnat_project_manager.rst +++ /dev/null @@ -1,4887 +0,0 @@ -.. |with| replace:: *with* -.. |withs| replace:: *with*\ s -.. |withed| replace:: *with*\ ed -.. |withing| replace:: *with*\ ing - -.. -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit - - -.. _GNAT_Project_Manager: - -******************** -GNAT Project Manager -******************** - - -.. _GNAT_Project_Manager_Introduction: - -Introduction -============ - -This chapter describes GNAT's *Project Manager*, a facility that allows -you to manage complex builds involving a number of source files, directories, -and options for different system configurations. In particular, -project files allow you to specify: - -* The directory or set of directories containing the source files, and/or the - names of the specific source files themselves -* The directory in which the compiler's output - (:file:`ALI` files, object files, tree files, etc.) is to be placed -* The directory in which the executable programs are to be placed -* Switch settings for any of the project-enabled tools; - you can apply these settings either globally or to individual compilation units. -* The source files containing the main subprogram(s) to be built -* The source programming language(s) -* Source file naming conventions; you can specify these either globally or for - individual compilation units (see :ref:`Naming_Schemes`). -* Change any of the above settings depending on external values, thus enabling - the reuse of the projects in various **scenarios** (see :ref:`Scenarios_in_Projects`). -* Automatically build libraries as part of the build process - (see :ref:`Library_Projects`). - - -Project files are written in a syntax close to that of Ada, using familiar -notions such as packages, context clauses, declarations, default values, -assignments, and inheritance (see :ref:`Project_File_Reference`). - -Project files can be built hierarchically from other project files, simplifying -complex system integration and project reuse (see :ref:`Organizing_Projects_into_Subsystems`). - -* One project can import other projects containing needed source files. - More generally, the Project Manager lets you structure large development - efforts into hierarchical subsystems, where build decisions are delegated - to the subsystem level, and thus different compilation environments - (switch settings) used for different subsystems. -* You can organize GNAT projects in a hierarchy: a child project - can extend a parent project, inheriting the parent's source files and - optionally overriding any of them with alternative versions - (see :ref:`Project_Extension`). - - -Several tools support project files, generally in addition to specifying -the information on the command line itself). They share common switches -to control the loading of the project (in particular -:samp:`-P{projectfile}` and -:samp:`-X{vbl}={value}`). - -The Project Manager supports a wide range of development strategies, -for systems of all sizes. Here are some typical practices that are -easily handled: - -* Using a common set of source files and generating object files in different - directories via different switch settings. It can be used for instance, for - generating separate sets of object files for debugging and for production. -* Using a mostly-shared set of source files with different versions of - some units or subunits. It can be used for instance, for grouping and hiding - all OS dependencies in a small number of implementation units. - -Project files can be used to achieve some of the effects of a source -versioning system (for example, defining separate projects for -the different sets of sources that comprise different releases) but the -Project Manager is independent of any source configuration management tool -that might be used by the developers. - -The various sections below introduce the different concepts related to -projects. Each section starts with examples and use cases, and then goes into -the details of related project file capabilities. - -.. _Building_With_Projects: - -Building With Projects -====================== - -In its simplest form, a unique project is used to build a single executable. -This section concentrates on such a simple setup. Later sections will extend -this basic model to more complex setups. - -The following concepts are the foundation of project files, and will be further -detailed later in this documentation. They are summarized here as a reference. - -**Project file**: - A text file using an Ada-like syntax, generally using the :file:`.gpr` - extension. It defines build-related characteristics of an application. - The characteristics include the list of sources, the location of those - sources, the location for the generated object files, the name of - the main program, and the options for the various tools involved in the - build process. - - -**Project attribute**: - A specific project characteristic is defined by an attribute clause. Its - value is a string or a sequence of strings. All settings in a project - are defined through a list of predefined attributes with precise - semantics. See :ref:`Attributes`. - - -**Package in a project**: - Global attributes are defined at the top level of a project. - Attributes affecting specific tools are grouped in a - package whose name is related to tool's function. The most common - packages are `Builder`, `Compiler`, `Binder`, - and `Linker`. See :ref:`Packages`. - - -**Project variables**: - In addition to attributes, a project can use variables to store intermediate - values and avoid duplication in complex expressions. It can be initialized - with a value coming from the environment. - A frequent use of variables is to define scenarios. - See :ref:`External_Values`, :ref:`Scenarios_in_Projects`, and :ref:`Variables`. - - -**Source files** and **source directories**: - A source file is associated with a language through a naming convention. For - instance, `foo.c` is typically the name of a C source file; - `bar.ads` or `bar.1.ada` are two common naming conventions for a - file containing an Ada spec. A compilation unit is often composed of a main - source file and potentially several auxiliary ones, such as header files in C. - The naming conventions can be user defined :ref:`Naming_Schemes`, and will - drive the builder to call the appropriate compiler for the given source file. - Source files are searched for in the source directories associated with the - project through the **Source_Dirs** attribute. By default, all the files (in - these source directories) following the naming conventions associated with the - declared languages are considered to be part of the project. It is also - possible to limit the list of source files using the **Source_Files** or - **Source_List_File** attributes. Note that those last two attributes only - accept basenames with no directory information. - - -**Object files** and **object directory**: - An object file is an intermediate file produced by the compiler from a - compilation unit. It is used by post-compilation tools to produce - final executables or libraries. Object files produced in the context of - a given project are stored in a single directory that can be specified by the - **Object_Dir** attribute. In order to store objects in - two or more object directories, the system must be split into - distinct subsystems with their own project file. - - -The following subsections introduce gradually all the attributes of interest -for simple build needs. Here is the simple setup that will be used in the -following examples. - -The Ada source files :file:`pack.ads`, :file:`pack.adb`, and :file:`proc.adb` are in -the :file:`common/` directory. The file :file:`proc.adb` contains an Ada main -subprogram `Proc` that |withs| package `Pack`. We want to compile -these source files with the switch -*-O2*, and put the resulting files in -the directory :file:`obj/`. - -:: - - common/ - pack.ads - pack.adb - proc.adb - common/obj/ - proc.ali, proc.o pack.ali, pack.o - - -Our project is to be called *Build*. The name of the -file is the name of the project (case-insensitive) with the -:file:`.gpr` extension, therefore the project file name is :file:`build.gpr`. This -is not mandatory, but a warning is issued when this convention is not followed. - -This is a very simple example, and as stated above, a single project -file is enough for it. We will thus create a new file, that for now -should contain the following code: - -.. code-block:: gpr - - project Build is - end Build; - - -.. _Source_Files_and_Directories: - -Source Files and Directories ----------------------------- - -When you create a new project, the first thing to describe is how to find the -corresponding source files. These are the only settings that are needed by all -the tools that will use this project (builder, compiler, binder and linker for -the compilation, IDEs to edit the source files,...). - -.. index:: Source directories (GNAT Project Manager) - -The first step is to declare the source directories, which are the directories -to be searched to find source files. In the case of the example, -the :file:`common` directory is the only source directory. - -.. index:: Source_Dirs (GNAT Project Manager) - -There are several ways of defining source directories: - -* When the attribute **Source_Dirs** is not used, a project contains a - single source directory which is the one where the project file itself - resides. In our example, if :file:`build.gpr` is placed in the :file:`common` - directory, the project has the needed implicit source directory. - -* The attribute **Source_Dirs** can be set to a list of path names, one - for each of the source directories. Such paths can either be absolute - names (for instance :file:`"/usr/local/common/"` on UNIX), or relative to the - directory in which the project file resides (for instance "." if - :file:`build.gpr` is inside :file:`common/`, or "common" if it is one level up). - Each of the source directories must exist and be readable. - - .. index:: portability of path names (GNAT Project Manager) - - The syntax for directories is platform specific. For portability, however, - the project manager will always properly translate UNIX-like path names to - the native format of the specific platform. For instance, when the same - project file is to be used both on Unix and Windows, "/" should be used as - the directory separator rather than "\\". - -* The attribute **Source_Dirs** can automatically include subdirectories - using a special syntax inspired by some UNIX shells. If any of the paths in - the list ends with ":file:`**`", then that path and all its subdirectories - (recursively) are included in the list of source directories. For instance, - :file:`**` and :file:`./**` represent the complete directory tree rooted at - the directory in which the project file resides. - - .. index:: Source directories (GNAT Project Manager) - - .. index:: Excluded_Source_Dirs (GNAT Project Manager) - - When using that construct, it can sometimes be convenient to also use the - attribute **Excluded_Source_Dirs**, which is also a list of paths. Each entry - specifies a directory whose immediate content, not including subdirs, is to - be excluded. It is also possible to exclude a complete directory subtree - using the "**" notation. - - .. index:: Ignore_Source_Sub_Dirs (GNAT Project Manager) - - It is often desirable to remove, from the source directories, directory - subtrees rooted at some subdirectories. An example is the subdirectories - created by a Version Control System such as Subversion that creates directory - subtrees rooted at subdirectories ".svn". To do that, attribute - **Ignore_Source_Sub_Dirs** can be used. It specifies the list of simple - file names for the roots of these undesirable directory subtrees. - - - .. code-block:: gpr - - for Source_Dirs use ("./**"); - for Ignore_Source_Sub_Dirs use (".svn"); - - -When applied to the simple example, and because we generally prefer to have -the project file at the toplevel directory rather than mixed with the sources, -we will create the following file - - -.. code-block:: gpr - - build.gpr - project Build is - for Source_Dirs use ("common"); -- <<<< - end Build; - - -Once source directories have been specified, one may need to indicate -source files of interest. By default, all source files present in the source -directories are considered by the project manager. When this is not desired, -it is possible to specify the list of sources to consider explicitly. -In such a case, only source file base names are indicated and not -their absolute or relative path names. The project manager is in charge of -locating the specified source files in the specified source directories. - -* By default, the project manager searches for all source files of all - specified languages in all the source directories. - - Since the project manager was initially developed for Ada environments, the - default language is usually Ada and the above project file is complete: it - defines without ambiguity the sources composing the project: that is to say, - all the sources in subdirectory "common" for the default language (Ada) using - the default naming convention. - - .. index:: Languages (GNAT Project Manager) - - However, when compiling a multi-language application, or a pure C - application, the project manager must be told which languages are of - interest, which is done by setting the **Languages** attribute to a list of - strings, each of which is the name of a language. - - .. index:: Naming scheme (GNAT Project Manager) - - Even when using only Ada, the default naming might not be suitable. Indeed, - how does the project manager recognizes an "Ada file" from any other - file? Project files can describe the naming scheme used for source files, - and override the default (see :ref:`Naming_Schemes`). The default is the - standard GNAT extension (:file:`.adb` for bodies and :file:`.ads` for - specs), which is what is used in our example, explaining why no naming scheme - is explicitly specified. - See :ref:`Naming_Schemes`. - - .. index:: Source_Files (GNAT Project Manager) - -* `Source_Files`. - In some cases, source directories might contain files that should not be - included in a project. One can specify the explicit list of file names to - be considered through the **Source_Files** attribute. - When this attribute is defined, instead of looking at every file in the - source directories, the project manager takes only those names into - consideration reports errors if they cannot be found in the source - directories or does not correspond to the naming scheme. - -* For various reasons, it is sometimes useful to have a project with no - sources (most of the time because the attributes defined in the project - file will be reused in other projects, as explained in - :ref:`Organizing_Projects_into_Subsystems`. To do this, the attribute - *Source_Files* is set to the empty list, i.e. `()`. Alternatively, - *Source_Dirs* can be set to the empty list, with the same - result. - - .. index:: Source_List_File (GNAT Project Manager) - -* `Source_List_File`. - If there is a great number of files, it might be more convenient to use - the attribute **Source_List_File**, which specifies the full path of a file. - This file must contain a list of source file names (one per line, no - directory information) that are searched as if they had been defined - through *Source_Files*. Such a file can easily be created through - external tools. - - A warning is issued if both attributes `Source_Files` and - `Source_List_File` are given explicit values. In this case, the - attribute `Source_Files` prevails. - - .. index:: Excluded_Source_Files (GNAT Project Manager) - .. index:: Locally_Removed_Files (GNAT Project Manager) - .. index:: Excluded_Source_List_File (GNAT Project Manager) - -* `Excluded_Source_Files`. - Specifying an explicit list of files is not always convenient.It might be - more convenient to use the default search rules with specific exceptions. - This can be done thanks to the attribute **Excluded_Source_Files** - (or its synonym **Locally_Removed_Files**). - Its value is the list of file names that should not be taken into account. - This attribute is often used when extending a project, - see :ref:`Project_Extension`. A similar attribute - **Excluded_Source_List_File** plays the same - role but takes the name of file containing file names similarly to - `Source_List_File`. - - -In most simple cases, such as the above example, the default source file search -behavior provides the expected result, and we do not need to add anything after -setting `Source_Dirs`. The project manager automatically finds -:file:`pack.ads`, :file:`pack.adb`, and :file:`proc.adb` as source files of the -project. - -Note that by default a warning is issued when a project has no sources attached -to it and this is not explicitly indicated in the project file. - -.. _Duplicate_Sources_in_Projects: - -Duplicate Sources in Projects ------------------------------ - -If the order of the source directories is known statically, that is if -`"/**"` is not used in the string list `Source_Dirs`, then there may -be several files with the same name sitting in different directories of the -project. In this case, only the file in the first directory is considered as a -source of the project and the others are hidden. If `"/**"` is used in the -string list `Source_Dirs`, it is an error to have several files with the -same name in the same directory `"/**"` subtree, since there would be an -ambiguity as to which one should be used. However, two files with the same name -may exist in two single directories or directory subtrees. In this case, the -one in the first directory or directory subtree is a source of the project. - -If there are two sources in different directories of the same `"/**"` -subtree, one way to resolve the problem is to exclude the directory of the -file that should not be used as a source of the project. - -.. _Object_and_Exec_Directory: - -Object and Exec Directory -------------------------- - -The next step when writing a project is to indicate where the compiler should -put the object files. In fact, the compiler and other tools might create -several different kind of files (for GNAT, there is the object file and the ALI -file for instance). One of the important concepts in projects is that most -tools may consider source directories as read-only and do not attempt to create -new or temporary files there. Instead, all files are created in the object -directory. It is of course not true for project-aware IDEs, whose purpose it is -to create the source files. - -.. index:: Object_Dir (GNAT Project Manager) - -The object directory is specified through the **Object_Dir** attribute. -Its value is the path to the object directory, either absolute or -relative to the directory containing the project file. This -directory must already exist and be readable and writable, although -some tools have a switch to create the directory if needed (See -the switch `-p` for *gprbuild*). - -If the attribute `Object_Dir` is not specified, it defaults to -the project directory, that is the directory containing the project file. - -For our example, we can specify the object dir in this way: - -.. code-block:: gpr - - project Build is - for Source_Dirs use ("common"); - for Object_Dir use "obj"; -- <<<< - end Build; - -As mentioned earlier, there is a single object directory per project. As a -result, if you have an existing system where the object files are spread across -several directories, you can either move all of them into the same directory if -you want to build it with a single project file, or study the section on -subsystems (see :ref:`Organizing_Projects_into_Subsystems`) to see how each -separate object directory can be associated with one of the subsystems -constituting the application. - -When the *linker* is called, it usually creates an executable. By -default, this executable is placed in the object directory of the project. It -might be convenient to store it in its own directory. - -.. index:: Exec_Dir (GNAT Project Manager) - -This can be done through the `Exec_Dir` attribute, which, like -*Object_Dir* contains a single absolute or relative path and must point to -an existing and writable directory, unless you ask the tool to create it on -your behalf. When not specified, It defaults to the object directory and -therefore to the project file's directory if neither *Object_Dir* nor -*Exec_Dir* was specified. - -In the case of the example, let's place the executable in the root -of the hierarchy, ie the same directory as :file:`build.gpr`. Hence -the project file is now - -.. code-block:: gpr - - project Build is - for Source_Dirs use ("common"); - for Object_Dir use "obj"; - for Exec_Dir use "."; -- <<<< - end Build; - - -.. _Main_Subprograms: - -Main Subprograms ----------------- - -In the previous section, executables were mentioned. The project manager needs -to be taught what they are. In a project file, an executable is indicated by -pointing to the source file of a main subprogram. In C this is the file that -contains the `main` function, and in Ada the file that contains the main -unit. - -There can be any number of such main files within a given project, and thus -several executables can be built in the context of a single project file. Of -course, one given executable might not (and in fact will not) need all the -source files referenced by the project. As opposed to other build environments -such as *makefile*, one does not need to specify the list of -dependencies of each executable, the project-aware builder knows enough of the -semantics of the languages to build and link only the necessary elements. - -.. index:: Main (GNAT Project Manager) - -The list of main files is specified via the **Main** attribute. It contains -a list of file names (no directories). If a project defines this -attribute, it is not necessary to identify main files on the -command line when invoking a builder, and editors like -*GPS* will be able to create extra menus to spawn or debug the -corresponding executables. - -.. code-block:: gpr - - project Build is - for Source_Dirs use ("common"); - for Object_Dir use "obj"; - for Exec_Dir use "."; - for Main use ("proc.adb"); -- <<<< - end Build; - - -If this attribute is defined in the project, then spawning the builder -with a command such as - -.. code-block:: sh - - gprbuild -Pbuild - - -automatically builds all the executables corresponding to the files -listed in the *Main* attribute. It is possible to specify one -or more executables on the command line to build a subset of them. - -.. _Tools_Options_in_Project_Files: - -Tools Options in Project Files ------------------------------- - -We now have a project file that fully describes our environment, and can be -used to build the application with a simple *gprbuild* command as seen -in the previous section. In fact, the empty project we showed immediately at -the beginning (with no attribute at all) could already fulfill that need if it -was put in the :file:`common` directory. - -Of course, we might want more control. This section shows you how to specify -the compilation switches that the various tools involved in the building of the -executable should use. - -.. index:: command line length (GNAT Project Manager) - -Since source names and locations are described in the project file, it is not -necessary to use switches on the command line for this purpose (switches such -as -I for gcc). This removes a major source of command line length overflow. -Clearly, the builders will have to communicate this information one way or -another to the underlying compilers and tools they call but they usually use -response files for this and thus are not subject to command line overflows. - -Several tools participate to the creation of an executable: the compiler -produces object files from the source files; the binder (in the Ada case) -creates a "source" file that takes care, among other things, of elaboration -issues and global variable initialization; and the linker gathers everything -into a single executable that users can execute. All these tools are known to -the project manager and will be called with user defined switches from the -project files. However, we need to introduce a new project file concept to -express the switches to be used for any of the tools involved in the build. - -.. index:: project file packages (GNAT Project Manager) - -A project file is subdivided into zero or more **packages**, each of which -contains the attributes specific to one tool (or one set of tools). Project -files use an Ada-like syntax for packages. Package names permitted in project -files are restricted to a predefined set (see :ref:`Packages`), and the contents -of packages are limited to a small set of constructs and attributes -(see :ref:`Attributes`). - -Our example project file can be extended with the following empty packages. At -this stage, they could all be omitted since they are empty, but they show which -packages would be involved in the build process. - -.. code-block:: gpr - - project Build is - for Source_Dirs use ("common"); - for Object_Dir use "obj"; - for Exec_Dir use "."; - for Main use ("proc.adb"); - - package Builder is --<<< for gprbuild - end Builder; - - package Compiler is --<<< for the compiler - end Compiler; - - package Binder is --<<< for the binder - end Binder; - - package Linker is --<<< for the linker - end Linker; - end Build; - -Let's first examine the compiler switches. As stated in the initial description -of the example, we want to compile all files with *-O2*. This is a -compiler switch, although it is usual, on the command line, to pass it to the -builder which then passes it to the compiler. It is recommended to use directly -the right package, which will make the setup easier to understand for other -people. - -Several attributes can be used to specify the switches: - -.. index:: Default_Switches (GNAT Project Manager) - -**Default_Switches**: - - This is the first mention in this manual of an **indexed attribute**. When - this attribute is defined, one must supply an *index* in the form of a - literal string. - In the case of *Default_Switches*, the index is the name of the - language to which the switches apply (since a different compiler will - likely be used for each language, and each compiler has its own set of - switches). The value of the attribute is a list of switches. - - In this example, we want to compile all Ada source files with the switch - *-O2*, and the resulting project file is as follows - (only the `Compiler` package is shown): - - .. code-block:: gpr - - package Compiler is - for Default_Switches ("Ada") use ("-O2"); - end Compiler; - -.. index:: Switches (GNAT Project Manager) - -**Switches**: - - In some cases, we might want to use specific switches - for one or more files. For instance, compiling :file:`proc.adb` might not be - possible at high level of optimization because of a compiler issue. - In such a case, the *Switches* - attribute (indexed on the file name) can be used and will override the - switches defined by *Default_Switches*. Our project file would - become: - - .. code-block:: gpr - - - package Compiler is - for Default_Switches ("Ada") - use ("-O2"); - for Switches ("proc.adb") - use ("-O0"); - end Compiler; - - - `Switches` may take a pattern as an index, such as in: - - .. code-block:: gpr - - package Compiler is - for Default_Switches ("Ada") - use ("-O2"); - for Switches ("pkg*") - use ("-O0"); - end Compiler; - - Sources :file:`pkg.adb` and :file:`pkg-child.adb` would be compiled with -O0, - not -O2. - - `Switches` can also be given a language name as index instead of a file - name in which case it has the same semantics as *Default_Switches*. - However, indexes with wild cards are never valid for language name. - - -.. index:: Local_Configuration_Pragmas (GNAT Project Manager) - -**Local_Configuration_Pragmas**: - - This attribute may specify the path - of a file containing configuration pragmas for use by the Ada compiler, - such as `pragma Restrictions (No_Tasking)`. These pragmas will be - used for all the sources of the project. - - -The switches for the other tools are defined in a similar manner through the -**Default_Switches** and **Switches** attributes, respectively in the -*Builder* package (for *gprbuild*), -the *Binder* package (binding Ada executables) and the *Linker* -package (for linking executables). - - -.. _Compiling_with_Project_Files: - -Compiling with Project Files ----------------------------- - -Now that our project files are written, let's build our executable. -Here is the command we would use from the command line: - -.. code-block:: sh - - gprbuild -Pbuild - -This will automatically build the executables specified through the -*Main* attribute: for each, it will compile or recompile the -sources for which the object file does not exist or is not up-to-date; it -will then run the binder; and finally run the linker to create the -executable itself. - -The *gprbuild* builder, can automatically manage C files the -same way: create the file :file:`utils.c` in the :file:`common` directory, -set the attribute *Languages* to `"(Ada, C)"`, and re-run - -.. code-block:: sh - - gprbuild -Pbuild - -Gprbuild knows how to recompile the C files and will -recompile them only if one of their dependencies has changed. No direct -indication on how to build the various elements is given in the -project file, which describes the project properties rather than a -set of actions to be executed. Here is the invocation of -*gprbuild* when building a multi-language program: - -.. code-block:: sh - - $ gprbuild -Pbuild - gcc -c proc.adb - gcc -c pack.adb - gcc -c utils.c - gprbind proc - ... - gcc proc.o -o proc - -Notice the three steps described earlier: - -* The first three gcc commands correspond to the compilation phase. -* The gprbind command corresponds to the post-compilation phase. -* The last gcc command corresponds to the final link. - - -.. index:: -v option (for GPRbuild) - -The default output of GPRbuild's execution is kept reasonably simple and easy -to understand. In particular, some of the less frequently used commands are not -shown, and some parameters are abbreviated. So it is not possible to rerun the -effect of the *gprbuild* command by cut-and-pasting its output. -GPRbuild's option `-v` provides a much more verbose output which includes, -among other information, more complete compilation, post-compilation and link -commands. - - -.. _Executable_File_Names: - -Executable File Names ---------------------- - -.. index:: Executable (GNAT Project Manager) - -By default, the executable name corresponding to a main file is -computed from the main source file name. Through the attribute -**Builder.Executable**, it is possible to change this default. - -For instance, instead of building *proc* (or *proc.exe* -on Windows), we could configure our project file to build "proc1" -(resp proc1.exe) with the following addition: - -.. code-block:: gpr - - project Build is - ... -- same as before - package Builder is - for Executable ("proc.adb") use "proc1"; - end Builder - end Build; - -.. index:: Executable_Suffix (GNAT Project Manager) - -Attribute **Executable_Suffix**, when specified, may change the suffix -of the executable files, when no attribute `Executable` applies: -its value replaces the platform-specific executable suffix. -The default executable suffix is empty on UNIX and ".exe" on Windows. - -It is also possible to change the name of the produced executable by using the -command line switch *-o*. When several mains are defined in the project, -it is not possible to use the *-o* switch and the only way to change the -names of the executable is provided by Attributes `Executable` and -`Executable_Suffix`. - - -.. _Avoid_Duplication_With_Variables: - -Avoid Duplication With Variables --------------------------------- - -To illustrate some other project capabilities, here is a slightly more complex -project using similar sources and a main program in C: - - -.. code-block:: gpr - - project C_Main is - for Languages use ("Ada", "C"); - for Source_Dirs use ("common"); - for Object_Dir use "obj"; - for Main use ("main.c"); - package Compiler is - C_Switches := ("-pedantic"); - for Default_Switches ("C") use C_Switches; - for Default_Switches ("Ada") use ("-gnaty"); - for Switches ("main.c") use C_Switches & ("-g"); - end Compiler; - end C_Main; - -This project has many similarities with the previous one. -As expected, its `Main` attribute now refers to a C source. -The attribute *Exec_Dir* is now omitted, thus the resulting -executable will be put in the directory :file:`obj`. - -The most noticeable difference is the use of a variable in the -*Compiler* package to store settings used in several attributes. -This avoids text duplication, and eases maintenance (a single place to -modify if we want to add new switches for C files). We will revisit -the use of variables in the context of scenarios (see :ref:`Scenarios_in_Projects`). - -In this example, we see how the file :file:`main.c` can be compiled with -the switches used for all the other C files, plus *-g*. -In this specific situation the use of a variable could have been -replaced by a reference to the `Default_Switches` attribute: - -.. code-block:: gpr - - for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g"); - -Note the tick (*'*) used to refer to attributes defined in a package. - -Here is the output of the GPRbuild command using this project: - -.. code-block:: sh - - $ gprbuild -Pc_main - gcc -c -pedantic -g main.c - gcc -c -gnaty proc.adb - gcc -c -gnaty pack.adb - gcc -c -pedantic utils.c - gprbind main.bexch - ... - gcc main.o -o main - -The default switches for Ada sources, -the default switches for C sources (in the compilation of :file:`lib.c`), -and the specific switches for :file:`main.c` have all been taken into -account. - - -.. _Naming_Schemes: - -Naming Schemes --------------- - -Sometimes an Ada software system is ported from one compilation environment to -another (say GNAT), and the file are not named using the default GNAT -conventions. Instead of changing all the file names, which for a variety of -reasons might not be possible, you can define the relevant file naming scheme -in the **Naming** package of your project file. - -The naming scheme has two distinct goals for the project manager: it -allows finding of source files when searching in the source -directories, and given a source file name it makes it possible to guess -the associated language, and thus the compiler to use. - -Note that the use by the Ada compiler of pragmas Source_File_Name is not -supported when using project files. You must use the features described in this -paragraph. You can however specify other configuration pragmas. - -The following attributes can be defined in package `Naming`: - -.. index:: Casing (GNAT Project Manager) - -**Casing**: - - Its value must be one of `"lowercase"` (the default if - unspecified), `"uppercase"` or `"mixedcase"`. It describes the - casing of file names with regards to the Ada unit name. Given an Ada unit - My_Unit, the file name will respectively be :file:`my_unit.adb` (lowercase), - :file:`MY_UNIT.ADB` (uppercase) or :file:`My_Unit.adb` (mixedcase). - On Windows, file names are case insensitive, so this attribute is - irrelevant. - - -.. index:: Dot_Replacement (GNAT Project Manager) - -**Dot_Replacement**: - - This attribute specifies the string that should replace the "." in unit - names. Its default value is `"-"` so that a unit - `Parent.Child` is expected to be found in the file - :file:`parent-child.adb`. The replacement string must satisfy the following - requirements to avoid ambiguities in the naming scheme: - - * It must not be empty - - * It cannot start or end with an alphanumeric character - - * It cannot be a single underscore - - * It cannot start with an underscore followed by an alphanumeric - - * It cannot contain a dot `'.'` except if the entire string is `"."` - -.. index:: Spec_Suffix (GNAT Project Manager) -.. index:: Specification_Suffix (GNAT Project Manager) - -**Spec_Suffix** and **Specification_Suffix**: - - For Ada, these attributes give the suffix used in file names that contain - specifications. For other languages, they give the extension for files - that contain declaration (header files in C for instance). The attribute - is indexed on the language. - The two attributes are equivalent, but the latter is obsolescent. - - If the value of the attribute is the empty string, it indicates to the - Project Manager that the only specifications/header files for the language - are those specified with attributes `Spec` or - `Specification_Exceptions`. - - If `Spec_Suffix ("Ada")` is not specified, then the default is - `".ads"`. - - A non empty value must satisfy the following requirements: - - * It must include at least one dot - - * If `Dot_Replacement` is a single dot, then it cannot include - more than one dot. - -.. index:: Body_Suffix (GNAT Project Manager) -.. index:: Implementation_Suffix (GNAT Project Manager) - -**Body_Suffix** and **Implementation_Suffix**: - - These attributes give the extension used for file names that contain - code (bodies in Ada). They are indexed on the language. The second - version is obsolescent and fully replaced by the first attribute. - - For each language of a project, one of these two attributes need to be - specified, either in the project itself or in the configuration project file. - - If the value of the attribute is the empty string, it indicates to the - Project Manager that the only source files for the language - are those specified with attributes `Body` or - `Implementation_Exceptions`. - - These attributes must satisfy the same requirements as `Spec_Suffix`. - In addition, they must be different from any of the values in - `Spec_Suffix`. - If `Body_Suffix ("Ada")` is not specified, then the default is - `".adb"`. - - If `Body_Suffix ("Ada")` and `Spec_Suffix ("Ada")` end with the - same string, then a file name that ends with the longest of these two - suffixes will be a body if the longest suffix is `Body_Suffix ("Ada")` - or a spec if the longest suffix is `Spec_Suffix ("Ada")`. - - If the suffix does not start with a '.', a file with a name exactly equal to - the suffix will also be part of the project (for instance if you define the - suffix as `Makefile.in`, a file called :file:`Makefile.in` will be part - of the project. This capability is usually not interesting when building. - However, it might become useful when a project is also used to - find the list of source files in an editor, like the GNAT Programming System - (GPS). - -.. index:: Separate_Suffix (GNAT Project Manager) - -**Separate_Suffix**: - - This attribute is specific to Ada. It denotes the suffix used in file names - that contain separate bodies. If it is not specified, then it defaults to - same value as `Body_Suffix ("Ada")`. - - The value of this attribute cannot be the empty string. - - Otherwise, the same rules apply as for the - `Body_Suffix` attribute. The only accepted index is "Ada". - - -**Spec** or **Specification**: - - .. index:: Spec (GNAT Project Manager) - - .. index:: Specification (GNAT Project Manager) - - This attribute `Spec` can be used to define the source file name for a - given Ada compilation unit's spec. The index is the literal name of the Ada - unit (case insensitive). The value is the literal base name of the file that - contains this unit's spec (case sensitive or insensitive depending on the - operating system). This attribute allows the definition of exceptions to the - general naming scheme, in case some files do not follow the usual - convention. - - When a source file contains several units, the relative position of the unit - can be indicated. The first unit in the file is at position 1 - - - .. code-block:: gpr - - for Spec ("MyPack.MyChild") use "mypack.mychild.spec"; - for Spec ("top") use "foo.a" at 1; - for Spec ("foo") use "foo.a" at 2; - - -.. index:: Body (GNAT Project Manager) - -.. index:: Implementation (GNAT Project Manager) - -**Body** or **Implementation**: - - These attribute play the same role as *Spec* for Ada bodies. - - -.. index:: Specification_Exceptions (GNAT Project Manager) - -.. index:: Implementation_Exceptions (GNAT Project Manager) - -**Specification_Exceptions** and **Implementation_Exceptions**: - - These attributes define exceptions to the naming scheme for languages - other than Ada. They are indexed on the language name, and contain - a list of file names respectively for headers and source code. - - -For example, the following package models the Apex file naming rules: - -.. code-block:: gpr - - package Naming is - for Casing use "lowercase"; - for Dot_Replacement use "."; - for Spec_Suffix ("Ada") use ".1.ada"; - for Body_Suffix ("Ada") use ".2.ada"; - end Naming; - - -.. _Installation: - -Installation ------------- - -After building an application or a library it is often required to -install it into the development environment. For instance this step is -required if the library is to be used by another application. -The *gprinstall* tool provides an easy way to install -libraries, executable or object code generated during the build. The -**Install** package can be used to change the default locations. - -The following attributes can be defined in package `Install`: - -.. index:: Active (GNAT Project Manager) - -**Active** - Whether the project is to be installed, values are `true` - (default) or `false`. - - -.. index:: Artifacts (GNAT Project Manager) - -**Artifacts** - - An array attribute to declare a set of files not part of the sources - to be installed. The array discriminant is the directory where the - file is to be installed. If a relative directory then Prefix (see - below) is prepended. Note also that if the same file name occurs - multiple time in the attribute list, the last one will be the one - installed. - - -.. index:: Prefix (GNAT Project Manager) - -**Prefix**: - - Root directory for the installation. - - -**Exec_Subdir** - - Subdirectory of **Prefix** where executables are to be - installed. Default is **bin**. - - -**Lib_Subdir** - - Subdirectory of **Prefix** where directory with the library or object - files is to be installed. Default is **lib**. - - -**Sources_Subdir** - - Subdirectory of **Prefix** where directory with sources is to be - installed. Default is **include**. - - -**Project_Subdir** - - Subdirectory of **Prefix** where the generated project file is to be - installed. Default is **share/gpr**. - - -**Mode** - - The installation mode, it is either **dev** (default) or **usage**. - See **gprbuild** user's guide for details. - - -**Install_Name** - - Specify the name to use for recording the installation. The default is - the project name without the extension. - - -.. _Distributed_support: - -Distributed support -------------------- - -For large projects the compilation time can become a limitation in -the development cycle. To cope with that, GPRbuild supports -distributed compilation. - -The following attributes can be defined in package `Remote`: - -.. index:: Root_Dir (GNAT Project Manager) - -**Root_Dir**: - - Root directory of the project's sources. The default value is the - project's directory. - - -.. _Organizing_Projects_into_Subsystems: - -Organizing Projects into Subsystems -=================================== - -A **subsystem** is a coherent part of the complete system to be built. It is -represented by a set of sources and one single object directory. A system can -be composed of a single subsystem when it is simple as we have seen in the -first section. Complex systems are usually composed of several interdependent -subsystems. A subsystem is dependent on another subsystem if knowledge of the -other one is required to build it, and in particular if visibility on some of -the sources of this other subsystem is required. Each subsystem is usually -represented by its own project file. - -In this section, the previous example is being extended. Let's assume some -sources of our `Build` project depend on other sources. -For instance, when building a graphical interface, it is usual to depend upon -a graphical library toolkit such as GtkAda. Furthermore, we also need -sources from a logging module we had previously written. - -.. _Project_Dependencies: - -Project Dependencies --------------------- - -GtkAda comes with its own project file (appropriately called -:file:`gtkada.gpr`), and we will assume we have already built a project -called :file:`logging.gpr` for the logging module. With the information provided -so far in :file:`build.gpr`, building the application would fail with an error -indicating that the gtkada and logging units that are relied upon by the sources -of this project cannot be found. - -This is solved by adding the following **with** clauses at the beginning of our -project: - -.. code-block:: gpr - - with "gtkada.gpr"; - with "a/b/logging.gpr"; - project Build is - ... -- as before - end Build; - - -.. index:: Externally_Built (GNAT Project Manager) - -When such a project is compiled, *gprbuild* will automatically check -the other projects and recompile their sources when needed. It will also -recompile the sources from `Build` when needed, and finally create the -executable. In some cases, the implementation units needed to recompile a -project are not available, or come from some third party and you do not want to -recompile it yourself. In this case, set the attribute **Externally_Built** to -"true", indicating to the builder that this project can be assumed to be -up-to-date, and should not be considered for recompilation. In Ada, if the -sources of this externally built project were compiled with another version of -the compiler or with incompatible options, the binder will issue an error. - -The project's |with| clause has several effects. It provides source -visibility between projects during the compilation process. It also guarantees -that the necessary object files from `Logging` and `GtkAda` are -available when linking `Build`. - -As can be seen in this example, the syntax for importing projects is similar -to the syntax for importing compilation units in Ada. However, project files -use literal strings instead of names, and the |with| clause identifies -project files rather than packages. - -Each literal string after |with| is the path -(absolute or relative) to a project file. The `.gpr` extension is -optional, although we recommend adding it. If no extension is specified, -and no project file with the :file:`.gpr` extension is found, then -the file is searched for exactly as written in the |with| clause, -that is with no extension. - -As mentioned above, the path after a |with| has to be a literal -string, and you cannot use concatenation, or lookup the value of external -variables to change the directories from which a project is loaded. -A solution if you need something like this is to use aggregate projects -(see :ref:`Aggregate_Projects`). - -.. index:: project path (GNAT Project Manager) - -When a relative path or a base name is used, the -project files are searched relative to each of the directories in the -**project path**. This path includes all the directories found with the -following algorithm, in this order; the first matching file is used: - -* First, the file is searched relative to the directory that contains the - current project file. - - .. index:: GPR_PROJECT_PATH_FILE (GNAT Project Manager) - .. index:: GPR_PROJECT_PATH (GNAT Project Manager) - .. index:: ADA_PROJECT_PATH (GNAT Project Manager) - -* Then it is searched relative to all the directories specified in the - environment variables **GPR_PROJECT_PATH_FILE**, - **GPR_PROJECT_PATH** and **ADA_PROJECT_PATH** (in that order) if they exist. - The value of **GPR_PROJECT_PATH_FILE**, when defined, is the path name of - a text file that contains project directory path names, one per line. - **GPR_PROJECT_PATH** and **ADA_PROJECT_PATH**, when defined, contain - project directory path names separated by directory separators. - **ADA_PROJECT_PATH** is used for compatibility, it is recommended to - use **GPR_PROJECT_PATH_FILE** or **GPR_PROJECT_PATH**. - -* Finally, it is searched relative to the default project directories. - Such directories depend on the tool used. The locations searched in the - specified order are: - - * :file:`//lib/gnat` if option *--target* is specified - * :file:`//share/gpr` if option *--target* is specified - * :file:`/share/gpr/` - * :file:`/lib/gnat/` - - In our example, :file:`gtkada.gpr` is found in the predefined directory if - it was installed at the same root as GNAT. - -Some tools also support extending the project path from the command line, -generally through the *-aP*. You can see the value of the project -path by using the *gnatls -v* command. - -Any symbolic link will be fully resolved in the directory of the -importing project file before the imported project file is examined. - -Any source file in the imported project can be used by the sources of the -importing project, transitively. -Thus if `A` imports `B`, which imports `C`, the sources of -`A` may depend on the sources of `C`, even if `A` does not -import `C` explicitly. However, this is not recommended, because if -and when `B` ceases to import `C`, some sources in `A` will -no longer compile. *gprbuild* has a switch *--no-indirect-imports* -that will report such indirect dependencies. - -.. note:: - - One very important aspect of a project hierarchy is that - **a given source can only belong to one project** (otherwise the project manager - would not know which settings apply to it and when to recompile it). It means - that different project files do not usually share source directories or - when they do, they need to specify precisely which project owns which sources - using attribute `Source_Files` or equivalent. By contrast, 2 projects - can each own a source with the same base file name as long as they live in - different directories. The latter is not true for Ada Sources because of the - correlation between source files and Ada units. - -.. _Cyclic_Project_Dependencies: - -Cyclic Project Dependencies ---------------------------- - -Cyclic dependencies are mostly forbidden: -if `A` imports `B` (directly or indirectly) then `B` -is not allowed to import `A`. However, there are cases when cyclic -dependencies would be beneficial. For these cases, another form of import -between projects exists: the **limited with**. A project `A` that -imports a project `B` with a straight |with| may also be imported, -directly or indirectly, by `B` through a `limited with`. - -The difference between straight |with| and `limited with` is that -the name of a project imported with a `limited with` cannot be used in the -project importing it. In particular, its packages cannot be renamed and -its variables cannot be referred to. - -.. code-block:: gpr - - with "b.gpr"; - with "c.gpr"; - project A is - for Exec_Dir use B'Exec_Dir; -- ok - end A; - - limited with "a.gpr"; -- Cyclic dependency: A -> B -> A - project B is - for Exec_Dir use A'Exec_Dir; -- not ok - end B; - - with "d.gpr"; - project C is - end C; - - limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A - project D is - for Exec_Dir use A'Exec_Dir; -- not ok - end D; - - -.. _Sharing_Between_Projects: - -Sharing Between Projects ------------------------- - -When building an application, it is common to have similar needs in several of -the projects corresponding to the subsystems under construction. For instance, -they will all have the same compilation switches. - -As seen before (see :ref:`Tools_Options_in_Project_Files`), setting compilation -switches for all sources of a subsystem is simple: it is just a matter of -adding a `Compiler.Default_Switches` attribute to each project files with -the same value. Of course, that means duplication of data, and both places need -to be changed in order to recompile the whole application with different -switches. It can become a real problem if there are many subsystems and thus -many project files to edit. - -There are two main approaches to avoiding this duplication: - -* Since :file:`build.gpr` imports :file:`logging.gpr`, we could change it - to reference the attribute in Logging, either through a package renaming, - or by referencing the attribute. The following example shows both cases: - - .. code-block:: gpr - - project Logging is - package Compiler is - for Switches ("Ada") - use ("-O2"); - end Compiler; - package Binder is - for Switches ("Ada") - use ("-E"); - end Binder; - end Logging; - - with "logging.gpr"; - project Build is - package Compiler renames Logging.Compiler; - package Binder is - for Switches ("Ada") use Logging.Binder'Switches ("Ada"); - end Binder; - end Build; - - The solution used for `Compiler` gets the same value for all - attributes of the package, but you cannot modify anything from the - package (adding extra switches or some exceptions). The second - version is more flexible, but more verbose. - - If you need to refer to the value of a variable in an imported - project, rather than an attribute, the syntax is similar but uses - a "." rather than an apostrophe. For instance: - - .. code-block:: gpr - - with "imported"; - project Main is - Var1 := Imported.Var; - end Main; - -* The second approach is to define the switches in a third project. - That project is set up without any sources (so that, as opposed to - the first example, none of the project plays a special role), and - will only be used to define the attributes. Such a project is - typically called :file:`shared.gpr`. - - .. code-block:: gpr - - abstract project Shared is - for Source_Files use (); -- no sources - package Compiler is - for Switches ("Ada") - use ("-O2"); - end Compiler; - end Shared; - - with "shared.gpr"; - project Logging is - package Compiler renames Shared.Compiler; - end Logging; - - with "shared.gpr"; - project Build is - package Compiler renames Shared.Compiler; - end Build; - - As for the first example, we could have chosen to set the attributes - one by one rather than to rename a package. The reason we explicitly - indicate that `Shared` has no sources is so that it can be created - in any directory and we are sure it shares no sources with `Build` - or `Logging`, which of course would be invalid. - - .. index:: project qualifier (GNAT Project Manager) - - Note the additional use of the **abstract** qualifier in :file:`shared.gpr`. - This qualifier is optional, but helps convey the message that we do not - intend this project to have sources (see :ref:`Qualified_Projects` for - more qualifiers). - - -.. _Global_Attributes: - -Global Attributes ------------------ - -We have already seen many examples of attributes used to specify a special -option of one of the tools involved in the build process. Most of those -attributes are project specific. That it to say, they only affect the invocation -of tools on the sources of the project where they are defined. - -There are a few additional attributes that apply to all projects in a -hierarchy as long as they are defined on the "main" project. -The main project is the project explicitly mentioned on the command-line. -The project hierarchy is the "with"-closure of the main project. - -Here is a list of commonly used global attributes: - -.. index:: Global_Configuration_Pragmas (GNAT Project Manager) - -**Builder.Global_Configuration_Pragmas**: - - This attribute points to a file that contains configuration pragmas - to use when building executables. These pragmas apply for all - executables built from this project hierarchy. As we have seen before, - additional pragmas can be specified on a per-project basis by setting the - `Compiler.Local_Configuration_Pragmas` attribute. - -.. index:: Global_Compilation_Switches (GNAT Project Manager) - -**Builder.Global_Compilation_Switches**: - - This attribute is a list of compiler switches to use when compiling any - source file in the project hierarchy. These switches are used in addition - to the ones defined in the `Compiler` package, which only apply to - the sources of the corresponding project. This attribute is indexed on - the name of the language. - -Using such global capabilities is convenient. It can also lead to unexpected -behavior. Especially when several subsystems are shared among different main -projects and the different global attributes are not -compatible. Note that using aggregate projects can be a safer and more powerful -replacement to global attributes. - -.. _Scenarios_in_Projects: - -Scenarios in Projects -===================== - -Various aspects of the projects can be modified based on **scenarios**. These -are user-defined modes that change the behavior of a project. Typical -examples are the setup of platform-specific compiler options, or the use of -a debug and a release mode (the former would activate the generation of debug -information, while the second will focus on improving code optimization). - -Let's enhance our example to support debug and release modes. The issue is to -let the user choose what kind of system he is building: use *-g* as -compiler switches in debug mode and *-O2* in release mode. We will also -set up the projects so that we do not share the same object directory in both -modes; otherwise switching from one to the other might trigger more -recompilations than needed or mix objects from the two modes. - -One naive approach is to create two different project files, say -:file:`build_debug.gpr` and :file:`build_release.gpr`, that set the appropriate -attributes as explained in previous sections. This solution does not scale -well, because in the presence of multiple projects depending on each other, you -will also have to duplicate the complete hierarchy and adapt the project files -to point to the right copies. - -.. index:: scenarios (GNAT Project Manager) - -Instead, project files support the notion of scenarios controlled -by external values. Such values can come from several sources (in decreasing -order of priority): - -.. index:: -X (usage with GNAT Project Manager) - -**Command line**: - When launching *gprbuild*, the user can pass - extra *-X* switches to define the external value. In - our case, the command line might look like - - .. code-block:: sh - - gprbuild -Pbuild.gpr -Xmode=release - - -**Environment variables**: - When the external value does not come from the command line, it can come from - the value of environment variables of the appropriate name. - In our case, if an environment variable called "mode" - exists, its value will be taken into account. - - - -.. index:: external (GNAT Project Manager) - -**External function second parameter**. - -We now need to get that value in the project. The general form is to use -the predefined function **external** which returns the current value of -the external. For instance, we could set up the object directory to point to -either :file:`obj/debug` or :file:`obj/release` by changing our project to - -.. code-block:: gpr - - project Build is - for Object_Dir use "obj/" & external ("mode", "debug"); - ... -- as before - end Build; - -The second parameter to `external` is optional, and is the default -value to use if "mode" is not set from the command line or the environment. - -In order to set the switches according to the different scenarios, other -constructs have to be introduced such as typed variables and case constructions. - -.. index:: typed variable (GNAT Project Manager) -.. index:: case construction (GNAT Project Manager) - -A **typed variable** is a variable that -can take only a limited number of values, similar to an enumeration in Ada. -Such a variable can then be used in a **case construction** and create conditional -sections in the project. The following example shows how this can be done: - -.. code-block:: gpr - - project Build is - type Mode_Type is ("debug", "release"); -- all possible values - Mode : Mode_Type := external ("mode", "debug"); -- a typed variable - - package Compiler is - case Mode is - when "debug" => - for Switches ("Ada") - use ("-g"); - when "release" => - for Switches ("Ada") - use ("-O2"); - end case; - end Compiler; - end Build; - -The project has suddenly grown in size, but has become much more flexible. -`Mode_Type` defines the only valid values for the `mode` variable. If -any other value is read from the environment, an error is reported and the -project is considered as invalid. - -The `Mode` variable is initialized with an external value -defaulting to `"debug"`. This default could be omitted and that would -force the user to define the value. Finally, we can use a case construction to set the -switches depending on the scenario the user has chosen. - -Most aspects of the projects can depend on scenarios. The notable exception -are project dependencies (|with| clauses), which cannot depend on a scenario. - -Scenarios work the same way with **project hierarchies**: you can either -duplicate a variable similar to `Mode` in each of the project (as long -as the first argument to `external` is always the same and the type is -the same), or simply set the variable in the :file:`shared.gpr` project -(see :ref:`Sharing_Between_Projects`). - - -.. _Library_Projects: - -Library Projects -================ - -So far, we have seen examples of projects that create executables. However, -it is also possible to create libraries instead. A **library** is a specific -type of subsystem where, for convenience, objects are grouped together -using system-specific means such as archives or windows DLLs. - -Library projects provide a system- and language-independent way of building -both **static** and **dynamic** libraries. They also support the concept of -**standalone libraries** (SAL) which offer two significant properties: the -elaboration (e.g. initialization) of the library is either automatic or -very simple; a change in the -implementation part of the library implies minimal post-compilation actions on -the complete system and potentially no action at all for the rest of the -system in the case of dynamic SALs. - -There is a restriction on shared library projects: by default, they are only -allowed to import other shared library projects. They are not allowed to -import non library projects or static library projects. - -The GNAT Project Manager takes complete care of the library build, rebuild and -installation tasks, including recompilation of the source files for which -objects do not exist or are not up to date, assembly of the library archive, and -installation of the library (i.e., copying associated source, object and -:file:`ALI` files to the specified location). - - -.. _Building_Libraries: - -Building Libraries ------------------- - -Let's enhance our example and transform the `logging` subsystem into a -library. In order to do so, a few changes need to be made to -:file:`logging.gpr`. Some attributes need to be defined: at least -`Library_Name` and `Library_Dir`; in addition, some other attributes -can be used to specify specific aspects of the library. For readability, it is -also recommended (although not mandatory), to use the qualifier `library` -in front of the `project` keyword. - -.. index:: Library_Name (GNAT Project Manager) - -**Library_Name**: - - This attribute is the name of the library to be built. There is no - restriction on the name of a library imposed by the project manager, except - for stand-alone libraries whose names must follow the syntax of Ada - identifiers; however, there may be system-specific restrictions on the name. - In general, it is recommended to stick to alphanumeric characters (and - possibly single underscores) to help portability. - -.. index:: Library_Dir (GNAT Project Manager) - -**Library_Dir**: - - This attribute is the path (absolute or relative) of the directory where - the library is to be installed. In the process of building a library, - the sources are compiled, the object files end up in the explicit or - implicit `Object_Dir` directory. When all sources of a library - are compiled, some of the compilation artifacts, including the library itself, - are copied to the library_dir directory. This directory must exist and be - writable. It must also be different from the object directory so that cleanup - activities in the Library_Dir do not affect recompilation needs. - -Here is the new version of :file:`logging.gpr` that makes it a library: - -.. code-block:: gpr - - library project Logging is -- "library" is optional - for Library_Name use "logging"; -- will create "liblogging.a" on Unix - for Object_Dir use "obj"; - for Library_Dir use "lib"; -- different from object_dir - end Logging; - -Once the above two attributes are defined, the library project is valid and -is enough for building a library with default characteristics. -Other library-related attributes can be used to change the defaults: - -.. index:: Library_Kind (GNAT Project Manager) - -**Library_Kind**: - - The value of this attribute must be either `"static"`, `"dynamic"` or - `"relocatable"` (the latter is a synonym for dynamic). It indicates - which kind of library should be built (the default is to build a - static library, that is an archive of object files that can potentially - be linked into a static executable). When the library is set to be dynamic, - a separate image is created that will be loaded independently, usually - at the start of the main program execution. Support for dynamic libraries is - very platform specific, for instance on Windows it takes the form of a DLL - while on GNU/Linux, it is a dynamic elf image whose suffix is usually - :file:`.so`. Library project files, on the other hand, can be written in - a platform independent way so that the same project file can be used to build - a library on different operating systems. - - If you need to build both a static and a dynamic library, it is recommended - to use two different object directories, since in some cases some extra code - needs to be generated for the latter. For such cases, one can either define - two different project files, or a single one that uses scenarios to indicate - the various kinds of library to be built and their corresponding object_dir. - -.. index:: Library_ALI_Dir (GNAT Project Manager) - -**Library_ALI_Dir**: - - This attribute may be specified to indicate the directory where the ALI - files of the library are installed. By default, they are copied into the - `Library_Dir` directory, but as for the executables where we have a - separate `Exec_Dir` attribute, you might want to put them in a separate - directory since there can be hundreds of them. The same restrictions as for - the `Library_Dir` attribute apply. - -.. index:: Library_Version (GNAT Project Manager) - -**Library_Version**: - - This attribute is platform dependent, and has no effect on Windows. - On Unix, it is used only for dynamic libraries as the internal - name of the library (the `"soname"`). If the library file name (built - from the `Library_Name`) is different from the `Library_Version`, - then the library file will be a symbolic link to the actual file whose name - will be `Library_Version`. This follows the usual installation schemes - for dynamic libraries on many Unix systems. - - .. code-block:: gpr - - project Logging is - Version := "1"; - for Library_Dir use "lib"; - for Library_Name use "logging"; - for Library_Kind use "dynamic"; - for Library_Version use "liblogging.so." & Version; - end Logging; - - - After the compilation, the directory :file:`lib` will contain both a - :file:`libdummy.so.1` library and a symbolic link to it called - :file:`libdummy.so`. - -.. index:: Library_GCC (GNAT Project Manager) - -**Library_GCC**: - - This attribute is the name of the tool to use instead of "gcc" to link shared - libraries. A common use of this attribute is to define a wrapper script that - accomplishes specific actions before calling gcc (which itself calls the - linker to build the library image). - -.. index:: Library_Options (GNAT Project Manager) - -**Library_Options**: - - This attribute may be used to specify additional switches (last switches) - when linking a shared library. - - It may also be used to add foreign object files to a static library. - Each string in Library_Options is an absolute or relative path of an object - file. When a relative path, it is relative to the object directory. - -.. index:: Leading_Library_Options (GNAT Project Manager) - -**Leading_Library_Options**: - - This attribute, that is taken into account only by *gprbuild*, may be - used to specified leading options (first switches) when linking a shared - library. - -.. index:: Linker_Options (GNAT Project Manager) - -**Linker.Linker_Options**: - - This attribute specifies additional switches to be given to the linker when - linking an executable. It is ignored when defined in the main project and - taken into account in all other projects that are imported directly or - indirectly. These switches complement the `Linker.Switches` - defined in the main project. This is useful when a particular subsystem - depends on an external library: adding this dependency as a - `Linker_Options` in the project of the subsystem is more convenient than - adding it to all the `Linker.Switches` of the main projects that depend - upon this subsystem. - - -.. _Using_Library_Projects: - -Using Library Projects ----------------------- - -When the builder detects that a project file is a library project file, it -recompiles all sources of the project that need recompilation and rebuild the -library if any of the sources have been recompiled. It then groups all object -files into a single file, which is a shared or a static library. This library -can later on be linked with multiple executables. Note that the use -of shard libraries reduces the size of the final executable and can also reduce -the memory footprint at execution time when the library is shared among several -executables. - -*gprbuild also allows to build **multi-language libraries** when specifying -sources from multiple languages. - -A non-library project can import a library project. When the builder is invoked -on the former, the library of the latter is only rebuilt when absolutely -necessary. For instance, if a unit of the library is not up-to-date but none of -the executables need this unit, then the unit is not recompiled and the library -is not reassembled. For instance, let's assume in our example that logging has -the following sources: :file:`log1.ads`, :file:`log1.adb`, :file:`log2.ads` and -:file:`log2.adb`. If :file:`log1.adb` has been modified, then the library -:file:`liblogging` will be rebuilt when compiling all the sources of -`Build` only if :file:`proc.ads`, :file:`pack.ads` or :file:`pack.adb` -include a `"with Log1"`. - -To ensure that all the sources in the `Logging` library are -up to date, and that all the sources of `Build` are also up to date, -the following two commands need to be used: - -.. code-block:: sh - - gprbuild -Plogging.gpr - gprbuild -Pbuild.gpr - -All :file:`ALI` files will also be copied from the object directory to the -library directory. To build executables, *gprbuild* will use the -library rather than the individual object files. - -Library projects can also be useful to describe a library that needs to be used -but, for some reason, cannot be rebuilt. For instance, it is the case when some -of the library sources are not available. Such library projects need to use the -`Externally_Built` attribute as in the example below: - -.. code-block:: gpr - - library project Extern_Lib is - for Languages use ("Ada", "C"); - for Source_Dirs use ("lib_src"); - for Library_Dir use "lib2"; - for Library_Kind use "dynamic"; - for Library_Name use "l2"; - for Externally_Built use "true"; -- <<<< - end Extern_Lib; - -In the case of externally built libraries, the `Object_Dir` -attribute does not need to be specified because it will never be -used. - -The main effect of using such an externally built library project is mostly to -affect the linker command in order to reference the desired library. It can -also be achieved by using `Linker.Linker_Options` or `Linker.Switches` -in the project corresponding to the subsystem needing this external library. -This latter method is more straightforward in simple cases but when several -subsystems depend upon the same external library, finding the proper place -for the `Linker.Linker_Options` might not be easy and if it is -not placed properly, the final link command is likely to present ordering issues. -In such a situation, it is better to use the externally built library project -so that all other subsystems depending on it can declare this dependency thanks -to a project |with| clause, which in turn will trigger the builder to find -the proper order of libraries in the final link command. - - -.. _Stand-alone_Library_Projects: - -Stand-alone Library Projects ----------------------------- - -.. index:: standalone libraries (usage with GNAT Project Manager) - -A **stand-alone library** is a library that contains the necessary code to -elaborate the Ada units that are included in the library. A stand-alone -library is a convenient way to add an Ada subsystem to a more global system -whose main is not in Ada since it makes the elaboration of the Ada part mostly -transparent. However, stand-alone libraries are also useful when the main is in -Ada: they provide a means for minimizing relinking & redeployment of complex -systems when localized changes are made. - -The name of a stand-alone library, specified with attribute -`Library_Name`, must have the syntax of an Ada identifier. - -The most prominent characteristic of a stand-alone library is that it offers a -distinction between interface units and implementation units. Only the former -are visible to units outside the library. A stand-alone library project is thus -characterised by a third attribute, usually **Library_Interface**, in addition -to the two attributes that make a project a Library Project -(`Library_Name` and `Library_Dir`). This third attribute may also be -**Interfaces**. **Library_Interface** only works when the interface is in Ada -and takes a list of units as parameter. **Interfaces** works for any supported -language and takes a list of sources as parameter. - -.. index:: Library_Interface (GNAT Project Manager) - -**Library_Interface**: - - This attribute defines an explicit subset of the units of the project. Units - from projects importing this library project may only "with" units whose - sources are listed in the `Library_Interface`. Other sources are - considered implementation units. - - .. code-block:: gpr - - for Library_Dir use "lib"; - for Library_Name use "logging"; - for Library_Interface use ("lib1", "lib2"); -- unit names - -**Interfaces** - - This attribute defines an explicit subset of the source files of a project. - Sources from projects importing this project, can only depend on sources from - this subset. This attribute can be used on non library projects. It can also - be used as a replacement for attribute `Library_Interface`, in which - case, units have to be replaced by source files. For multi-language library - projects, it is the only way to make the project a Stand-Alone Library project - whose interface is not purely Ada. - - -.. index:: Library_Standalone (GNAT Project Manager) - -**Library_Standalone**: - - This attribute defines the kind of standalone library to - build. Values are either `standard` (the default), `no` or - `encapsulated`. When `standard` is used the code to elaborate and - finalize the library is embedded, when `encapsulated` is used the - library can furthermore depend only on static libraries (including - the GNAT runtime). This attribute can be set to `no` to make it clear - that the library should not be standalone in which case the - `Library_Interface` should not defined. Note that this attribute - only applies to shared libraries, so `Library_Kind` must be set - to `dynamic`. - - .. code-block:: gpr - - for Library_Dir use "lib"; - for Library_Name use "logging"; - for Library_Kind use "dynamic"; - for Library_Interface use ("lib1", "lib2"); -- unit names - for Library_Standalone use "encapsulated"; - -In order to include the elaboration code in the stand-alone library, the binder -is invoked on the closure of the library units creating a package whose name -depends on the library name (b~logging.ads/b in the example). -This binder-generated package includes **initialization** and **finalization** -procedures whose names depend on the library name (`logginginit` and -`loggingfinal` in the example). The object corresponding to this package is -included in the library. - -.. index:: Library_Auto_Init (GNAT Project Manager) - -**Library_Auto_Init**: - - A dynamic stand-alone Library is automatically initialized - if automatic initialization of Stand-alone Libraries is supported on the - platform and if attribute **Library_Auto_Init** is not specified or - is specified with the value "true". A static Stand-alone Library is never - automatically initialized. Specifying "false" for this attribute - prevents automatic initialization. - - When a non-automatically initialized stand-alone library is used in an - executable, its initialization procedure must be called before any service of - the library is used. When the main subprogram is in Ada, it may mean that the - initialization procedure has to be called during elaboration of another - package. - - -.. index:: Library_Dir (GNAT Project Manager) - -**Library_Dir**: - - For a stand-alone library, only the :file:`ALI` files of the interface units - (those that are listed in attribute `Library_Interface`) are copied to - the library directory. As a consequence, only the interface units may be - imported from Ada units outside of the library. If other units are imported, - the binding phase will fail. - - -**Binder.Default_Switches**: - - When a stand-alone library is bound, the switches that are specified in - the attribute **Binder.Default_Switches ("Ada")** are - used in the call to *gnatbind*. - - -.. index:: Library_Src_Dir (GNAT Project Manager) - -**Library_Src_Dir**: - - This attribute defines the location (absolute or relative to the project - directory) where the sources of the interface units are copied at - installation time. - These sources includes the specs of the interface units along with the - closure of sources necessary to compile them successfully. That may include - bodies and subunits, when pragmas `Inline` are used, or when there are - generic units in specs. This directory cannot point to the object directory - or one of the source directories, but it can point to the library directory, - which is the default value for this attribute. - - -.. index:: Library_Symbol_Policy (GNAT Project Manager) - -**Library_Symbol_Policy**: - - This attribute controls the export of symbols and, on some platforms (like - VMS) that have the notions of major and minor IDs built in the library - files, it controls the setting of these IDs. It is not supported on all - platforms (where it will just have no effect). It may have one of the - following values: - - * `"autonomous"` or `"default"`: exported symbols are not controlled - - * `"compliant"`: if attribute **Library_Reference_Symbol_File** - is not defined, then it is equivalent to policy "autonomous". If there - are exported symbols in the reference symbol file that are not in the - object files of the interfaces, the major ID of the library is increased. - If there are symbols in the object files of the interfaces that are not - in the reference symbol file, these symbols are put at the end of the list - in the newly created symbol file and the minor ID is increased. - - * `"controlled"`: the attribute **Library_Reference_Symbol_File** must be - defined. The library will fail to build if the exported symbols in the - object files of the interfaces do not match exactly the symbol in the - symbol file. - - * `"restricted"`: The attribute **Library_Symbol_File** must be defined. - The library will fail to build if there are symbols in the symbol file that - are not in the exported symbols of the object files of the interfaces. - Additional symbols in the object files are not added to the symbol file. - - * `"direct"`: The attribute **Library_Symbol_File** must be defined and - must designate an existing file in the object directory. This symbol file - is passed directly to the underlying linker without any symbol processing. - - -.. index:: Library_Reference_Symbol_File (GNAT Project Manager) - -**Library_Reference_Symbol_File** - - This attribute may define the path name of a reference symbol file that is - read when the symbol policy is either "compliant" or "controlled", on - platforms that support symbol control, such as VMS, when building a - stand-alone library. The path may be an absolute path or a path relative - to the project directory. - - -.. index:: Library_Symbol_File (GNAT Project Manager) - -**Library_Symbol_File** - - This attribute may define the name of the symbol file to be created when - building a stand-alone library when the symbol policy is either "compliant", - "controlled" or "restricted", on platforms that support symbol control, - such as VMS. When symbol policy is "direct", then a file with this name - must exist in the object directory. - - -.. _Installing_a_library_with_project_files: - -Installing a library with project files ---------------------------------------- - -When using project files, a usable version of the library is created in the -directory specified by the `Library_Dir` attribute of the library -project file. Thus no further action is needed in order to make use of -the libraries that are built as part of the general application build. - -You may want to install a library in a context different from where the library -is built. This situation arises with third party suppliers, who may want -to distribute a library in binary form where the user is not expected to be -able to recompile the library. The simplest option in this case is to provide -a project file slightly different from the one used to build the library, by -using the `externally_built` attribute. See :ref:`Using_Library_Projects` - -Another option is to use *gprinstall* to install the library in a -different context than the build location. *gprinstall* automatically -generates a project to use this library, and also copies the minimum set of -sources needed to use the library to the install location. -:ref:`Installation` - - -.. _Project_Extension: - -Project Extension -================= - -During development of a large system, it is sometimes necessary to use -modified versions of some of the source files, without changing the original -sources. This can be achieved through the **project extension** facility. - -Suppose for instance that our example `Build` project is built every night -for the whole team, in some shared directory. A developer usually needs to work -on a small part of the system, and might not want to have a copy of all the -sources and all the object files (mostly because that would require too much -disk space, time to recompile everything). He prefers to be able to override -some of the source files in his directory, while taking advantage of all the -object files generated at night. - -Another example can be taken from large software systems, where it is common to have -multiple implementations of a common interface; in Ada terms, multiple -versions of a package body for the same spec. For example, one implementation -might be safe for use in tasking programs, while another might be used only -in sequential applications. This can be modeled in GNAT using the concept -of *project extension*. If one project (the 'child') *extends* -another project (the 'parent') then by default all source files of the -parent project are inherited by the child, but the child project can -override any of the parent's source files with new versions, and can also -add new files or remove unnecessary ones. -This facility is the project analog of a type extension in -object-oriented programming. Project hierarchies are permitted (an extending -project may itself be extended), and a project that -extends a project can also import other projects. - -A third example is that of using project extensions to provide different -versions of the same system. For instance, assume that a `Common` -project is used by two development branches. One of the branches has now -been frozen, and no further change can be done to it or to `Common`. -However, the other development branch still needs evolution of `Common`. -Project extensions provide a flexible solution to create a new version -of a subsystem while sharing and reusing as much as possible from the original -one. - -A project extension implicitly inherits all the sources and objects from the -project it extends. It is possible to create a new version of some of the -sources in one of the additional source directories of the extending -project. Those new versions hide the original versions. Adding new sources or -removing existing ones is also possible. Here is an example on how to extend -the project `Build` from previous examples: - -.. code-block:: gpr - - project Work extends "../bld/build.gpr" is - end Work; - -The project after **extends** is the one being extended. As usual, it can be -specified using an absolute path, or a path relative to any of the directories -in the project path (see :ref:`Project_Dependencies`). This project does not -specify source or object directories, so the default values for these -attributes will be used that is to say the current directory (where project -`Work` is placed). We can compile that project with - -.. code-block:: sh - - gprbuild -Pwork - -If no sources have been placed in the current directory, this command -won't do anything, since this project does not change the -sources it inherited from `Build`, therefore all the object files -in `Build` and its dependencies are still valid and are reused -automatically. - -Suppose we now want to supply an alternate version of :file:`pack.adb` but use -the existing versions of :file:`pack.ads` and :file:`proc.adb`. We can create -the new file in Work's current directory (likely by copying the one from the -`Build` project and making changes to it. If new packages are needed at -the same time, we simply create new files in the source directory of the -extending project. - -When we recompile, *gprbuild* will now automatically recompile -this file (thus creating :file:`pack.o` in the current directory) and -any file that depends on it (thus creating :file:`proc.o`). Finally, the -executable is also linked locally. - -Note that we could have obtained the desired behavior using project import -rather than project inheritance. A `base` project would contain the -sources for :file:`pack.ads` and :file:`proc.adb`, and `Work` would -import `base` and add :file:`pack.adb`. In this scenario, `base` -cannot contain the original version of :file:`pack.adb` otherwise there would be -2 versions of the same unit in the closure of the project and this is not -allowed. Generally speaking, it is not recommended to put the spec and the -body of a unit in different projects since this affects their autonomy and -reusability. - -In a project file that extends another project, it is possible to -indicate that an inherited source is **not part** of the sources of the -extending project. This is necessary sometimes when a package spec has -been overridden and no longer requires a body: in this case, it is -necessary to indicate that the inherited body is not part of the sources -of the project, otherwise there will be a compilation error -when compiling the spec. - -.. index:: Excluded_Source_Files (GNAT Project Manager) - -.. index:: Excluded_Source_List_File (GNAT Project Manager) - -For that purpose, the attribute **Excluded_Source_Files** is used. -Its value is a list of file names. -It is also possible to use attribute `Excluded_Source_List_File`. -Its value is the path of a text file containing one file name per -line. - -.. code-block:: gpr - - project Work extends "../bld/build.gpr" is - for Source_Files use ("pack.ads"); - -- New spec of Pkg does not need a completion - for Excluded_Source_Files use ("pack.adb"); - end Work; - - -All packages that are not declared in the extending project are inherited from -the project being extended, with their attributes, with the exception of -`Linker'Linker_Options` which is never inherited. In particular, an -extending project retains all the switches specified in the project being -extended. - -At the project level, if they are not declared in the extending project, some -attributes are inherited from the project being extended. They are: -`Languages`, `Main` (for a root non library project) and -`Library_Name` (for a project extending a library project). - -.. _Project_Hierarchy_Extension: - -Project Hierarchy Extension ---------------------------- - -One of the fundamental restrictions in project extension is the following: -**A project is not allowed to import directly or indirectly at the same time an extending project and one of its ancestors**. - -For example, consider the following hierarchy of projects. - -:: - - a.gpr contains package A1 - b.gpr, imports a.gpr and contains B1, which depends on A1 - c.gpr, imports b.gpr and contains C1, which depends on B1 - -If we want to locally extend the packages `A1` and `C1`, we need to -create several extending projects: - -:: - - a_ext.gpr which extends a.gpr, and overrides A1 - b_ext.gpr which extends b.gpr and imports a_ext.gpr - c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1 - -.. code-block:: gpr - - project A_Ext extends "a.gpr" is - for Source_Files use ("a1.adb", "a1.ads"); - end A_Ext; - - with "a_ext.gpr"; - project B_Ext extends "b.gpr" is - end B_Ext; - - with "b_ext.gpr"; - project C_Ext extends "c.gpr" is - for Source_Files use ("c1.adb"); - end C_Ext; - -The extension :file:`b_ext.gpr` is required, even though we are not overriding -any of the sources of :file:`b.gpr` because otherwise :file:`c_expr.gpr` would -import :file:`b.gpr` which itself knows nothing about :file:`a_ext.gpr`. - -.. index:: extends all (GNAT Project Manager) - -When extending a large system spanning multiple projects, it is often -inconvenient to extend every project in the hierarchy that is impacted by a -small change introduced in a low layer. In such cases, it is possible to create -an **implicit extension** of an entire hierarchy using **extends all** -relationship. - -When the project is extended using `extends all` inheritance, all projects -that are imported by it, both directly and indirectly, are considered virtually -extended. That is, the project manager creates implicit projects -that extend every project in the hierarchy; all these implicit projects do not -control sources on their own and use the object directory of -the "extending all" project. - -It is possible to explicitly extend one or more projects in the hierarchy -in order to modify the sources. These extending projects must be imported by -the "extending all" project, which will replace the corresponding virtual -projects with the explicit ones. - -When building such a project hierarchy extension, the project manager will -ensure that both modified sources and sources in implicit extending projects -that depend on them are recompiled. - -Thus, in our example we could create the following projects instead: - -:: - - a_ext.gpr, extends a.gpr and overrides A1 - c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1 - -.. code-block:: gpr - - project A_Ext extends "a.gpr" is - for Source_Files use ("a1.adb", "a1.ads"); - end A_Ext; - - with "a_ext.gpr"; - project C_Ext extends all "c.gpr" is - for Source_Files use ("c1.adb"); - end C_Ext; - - -When building project :file:`c_ext.gpr`, the entire modified project space is -considered for recompilation, including the sources of :file:`b.gpr` that are -impacted by the changes in `A1` and `C1`. - - -.. _Aggregate_Projects: - -Aggregate Projects -================== - -Aggregate projects are an extension of the project paradigm, and are -meant to solve a few specific use cases that cannot be solved directly -using standard projects. This section will go over a few of these use -cases to try to explain what you can use aggregate projects for. - - -.. _Building_all_main_programs_from_a_single_project_tree: - -Building all main programs from a single project tree ------------------------------------------------------ - -Most often, an application is organized into modules and submodules, -which are very conveniently represented as a project tree or graph -(the root project A |withs| the projects for each modules (say B and C), -which in turn |with| projects for submodules. - -Very often, modules will build their own executables (for testing -purposes for instance), or libraries (for easier reuse in various -contexts). - -However, if you build your project through *gprbuild*, using a syntax similar to - -:: - - gprbuild -PA.gpr - -this will only rebuild the main programs of project A, not those of the -imported projects B and C. Therefore you have to spawn several -*gprbuild* commands, one per project, to build all executables. -This is a little inconvenient, but more importantly is inefficient -because *gprbuild* needs to do duplicate work to ensure that sources are -up-to-date, and cannot easily compile things in parallel when using -the -j switch. - -Also libraries are always rebuilt when building a project. - -You could therefore define an aggregate project Agg that groups A, B -and C. Then, when you build with - -:: - - gprbuild -PAgg.gpr - -this will build all mains from A, B and C. - -.. code-block:: gpr - - aggregate project Agg is - for Project_Files use ("a.gpr", "b.gpr", "c.gpr"); - end Agg; - -If B or C do not define any main program (through their Main -attribute), all their sources are built. When you do not group them -in the aggregate project, only those sources that are needed by A -will be built. - -If you add a main to a project P not already explicitly referenced in the -aggregate project, you will need to add "p.gpr" in the list of project -files for the aggregate project, or the main will not be built when -building the aggregate project. - -.. _Building_a_set_of_projects_with_a_single_command: - -Building a set of projects with a single command ------------------------------------------------- - -One other case is when you have multiple applications and libraries -that are built independently from each other (but can be built in -parallel). For instance, you have a project tree rooted at A, and -another one (which might share some subprojects) rooted at B. - -Using only *gprbuild*, you could do - -.. code-block:: sh - - gprbuild -PA.gpr - gprbuild -PB.gpr - -to build both. But again, *gprbuild* has to do some duplicate work for -those files that are shared between the two, and cannot truly build -things in parallel efficiently. - -If the two projects are really independent, share no sources other -than through a common subproject, and have no source files with a -common basename, you could create a project C that imports A and -B. But these restrictions are often too strong, and one has to build -them independently. An aggregate project does not have these -limitations and can aggregate two project trees that have common -sources. - -This scenario is particularly useful in environments like VxWorks 653 -where the applications running in the multiple partitions can be built -in parallel through a single *gprbuild* command. This also works nicely -with Annex E. - - -.. _Define_a_build_environment: - -Define a build environment --------------------------- - -The environment variables at the time you launch *gprbuild* -will influence the view these tools have of the project -(PATH to find the compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the -projects, environment variables that are referenced in project files -through the "external" built-in function, ...). Several command line switches -can be used to override those (-X or -aP), but on some systems and -with some projects, this might make the command line too long, and on -all systems often make it hard to read. - -An aggregate project can be used to set the environment for all -projects built through that aggregate. One of the nice aspects is that -you can put the aggregate project under configuration management, and -make sure all your user have a consistent environment when -building. The syntax looks like - -.. code-block:: gpr - - aggregate project Agg is - for Project_Files use ("A.gpr", "B.gpr"); - for Project_Path use ("../dir1", "../dir1/dir2"); - for External ("BUILD") use "PRODUCTION"; - - package Builder is - for Global_Compilation_Switches ("Ada") use ("-g"); - end Builder; - end Agg; - -One of the often requested features in projects is to be able to -reference external variables in |with| declarations, as in - -.. code-block:: gpr - - with external("SETUP") & "path/prj.gpr"; -- ILLEGAL - project MyProject is - ... - end MyProject; - -For various reasons, this is not allowed. But using aggregate projects provide -an elegant solution. For instance, you could use a project file like: - -.. code-block:: gpr - - aggregate project Agg is - for Project_Path use (external("SETUP") & "path"); - for Project_Files use ("myproject.gpr"); - end Agg; - - with "prj.gpr"; -- searched on Agg'Project_Path - project MyProject is - ... - end MyProject; - - -.. _Performance_improvements_in_builder: - -Performance improvements in builder ------------------------------------ - -The loading of aggregate projects is optimized in *gprbuild*, -so that all files are searched for only once on the disk -(thus reducing the number of system calls and contributing to faster -compilation times, especially on systems with sources on remote -servers). As part of the loading, *gprbuild* -computes how and where a source file should be compiled, and even if it is -found several times in the aggregated projects it will be compiled only -once. - -Since there is no ambiguity as to which switches should be used, files -can be compiled in parallel (through the usual -j switch) and this can -be done while maximizing the use of CPUs (compared to launching -multiple *gprbuild* commands in parallel). - - -.. _Syntax_of_aggregate_projects: - -Syntax of aggregate projects ----------------------------- - -An aggregate project follows the general syntax of project files. The -recommended extension is still :file:`.gpr`. However, a special -`aggregate` qualifier must be put before the keyword -`project`. - -An aggregate project cannot |with| any other project (standard or -aggregate), except an abstract project which can be used to share attribute -values. Also, aggregate projects cannot be extended or imported though a -|with| clause by any other project. Building other aggregate projects from -an aggregate project is done through the Project_Files attribute (see below). - -An aggregate project does not have any source files directly (only -through other standard projects). Therefore a number of the standard -attributes and packages are forbidden in an aggregate project. Here is the -(non exhaustive) list: - -* Languages -* Source_Files, Source_List_File and other attributes dealing with - list of sources. -* Source_Dirs, Exec_Dir and Object_Dir -* Library_Dir, Library_Name and other library-related attributes -* Main -* Roots -* Externally_Built -* Inherit_Source_Path -* Excluded_Source_Dirs -* Locally_Removed_Files -* Excluded_Source_Files -* Excluded_Source_List_File -* Interfaces - -The only package that is authorized (albeit optional) is -Builder. Other packages (in particular Compiler, Binder and Linker) -are forbidden. - -The following three attributes can be used only in an aggregate project: - -.. index:: Project_Files (GNAT Project Manager) - -**Project_Files**: - - This attribute is compulsory (or else we are not aggregating any project, - and thus not doing anything). It specifies a list of :file:`.gpr` files - that are grouped in the aggregate. The list may be empty. The project - files can be either other aggregate projects, or standard projects. When - grouping standard projects, you can have both the root of a project tree - (and you do not need to specify all its imported projects), and any project - within the tree. - - Basically, the idea is to specify all those projects that have - main programs you want to build and link, or libraries you want to - build. You can even specify projects that do not use the Main - attribute nor the `Library_*` attributes, and the result will be to - build all their source files (not just the ones needed by other - projects). - - The file can include paths (absolute or relative). Paths are relative to - the location of the aggregate project file itself (if you use a base name, - we expect to find the .gpr file in the same directory as the aggregate - project file). The environment variables `ADA_PROJECT_PATH`, - `GPR_PROJECT_PATH` and `GPR_PROJECT_PATH_FILE` are not used to find - the project files. The extension :file:`.gpr` is mandatory, since this attribute - contains file names, not project names. - - Paths can also include the `"*"` and `"**"` globbing patterns. The - latter indicates that any subdirectory (recursively) will be - searched for matching files. The latter (`"**"`) can only occur at the - last position in the directory part (ie `"a/**/*.gpr"` is supported, but - not `"**/a/*.gpr"`). Starting the pattern with `"**"` is equivalent - to starting with `"./**"`. - - For now, the pattern `"*"` is only allowed in the filename part, not - in the directory part. This is mostly for efficiency reasons to limit the - number of system calls that are needed. - - Here are a few valid examples: - - .. code-block:: gpr - - for Project_Files use ("a.gpr", "subdir/b.gpr"); - -- two specific projects relative to the directory of agg.gpr - - for Project_Files use ("/.gpr"); - -- all projects recursively - - -.. index:: Project_Path (GNAT Project Manager) - -**Project_Path**: - - This attribute can be used to specify a list of directories in - which to look for project files in |with| declarations. - - When you specify a project in Project_Files (say `x/y/a.gpr`), and - `a.gpr` imports a project `b.gpr`, only `b.gpr` is searched in - the project path. `a.gpr` must be exactly at - `/x/y/a.gpr`. - - This attribute, however, does not affect the search for the aggregated - project files specified with `Project_Files`. - - Each aggregate project has its own `Project_Path` (that is if - `agg1.gpr` includes `agg2.gpr`, they can potentially both have a - different `Project_Path`). - - This project path is defined as the concatenation, in that order, of: - - * the current directory; - - * followed by the command line -aP switches; - - * then the directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH environment - variables; - - * then the directories from the Project_Path attribute; - - * and finally the predefined directories. - - In the example above, agg2.gpr's project path is not influenced by - the attribute agg1'Project_Path, nor is agg1 influenced by - agg2'Project_Path. - - This can potentially lead to errors. Consider the following example:: - - -- - -- +---------------+ +----------------+ - -- | Agg1.gpr |-=--includes--=-->| Agg2.gpr | - -- | 'project_path| | 'project_path | - -- | | | | - -- +---------------+ +----------------+ - -- : : - -- includes includes - -- : : - -- v v - -- +-------+ +---------+ - -- | P.gpr |<---------- withs --------| Q.gpr | - -- +-------+---------\ +---------+ - -- | | - -- withs | - -- | | - -- v v - -- +-------+ +---------+ - -- | R.gpr | | R'.gpr | - -- +-------+ +---------+ - - When looking for p.gpr, both aggregates find the same physical file on - the disk. However, it might happen that with their different project - paths, both aggregate projects would in fact find a different r.gpr. - Since we have a common project (p.gpr) "with"ing two different r.gpr, - this will be reported as an error by the builder. - - Directories are relative to the location of the aggregate project file. - - Example: - - .. code-block:: gpr - - for Project_Path use ("/usr/local/gpr", "gpr/"); - -.. index:: External (GNAT Project Manager) - -**External**: - - This attribute can be used to set the value of environment - variables as retrieved through the `external` function - in projects. It does not affect the environment variables - themselves (so for instance you cannot use it to change the value - of your PATH as seen from the spawned compiler). - - This attribute affects the external values as seen in the rest of - the aggregate project, and in the aggregated projects. - - The exact value of external a variable comes from one of three - sources (each level overrides the previous levels): - - * An External attribute in aggregate project, for instance - `for External ("BUILD_MODE") use "DEBUG"`; - - * Environment variables. - These override the value given by the attribute, so that - users can override the value set in the (presumably shared - with others team members) aggregate project. - - * The -X command line switch to *gprbuild*. - This always takes precedence. - - This attribute is only taken into account in the main aggregate - project (i.e. the one specified on the command line to *gprbuild*), - and ignored in other aggregate projects. It is invalid - in standard projects. - The goal is to have a consistent value in all - projects that are built through the aggregate, which would not - be the case in the diamond case: A groups the aggregate - projects B and C, which both (either directly or indirectly) - build the project P. If B and C could set different values for - the environment variables, we would have two different views of - P, which in particular might impact the list of source files in P. - - -.. _package_Builder_in_aggregate_projects: - -package Builder in aggregate projects -------------------------------------- - -As mentioned above, only the package Builder can be specified in -an aggregate project. In this package, only the following attributes -are valid: - -.. index:: Switches (GNAT Project Manager) - -**Switches**: - - This attribute gives the list of switches to use for *gprbuild*. - Because no mains can be specified for aggregate projects, the only possible - index for attribute `Switches` is `others`. All other indexes will - be ignored. - - Example: - - .. code-block:: gpr - - for Switches (others) use ("-v", "-k", "-j8"); - - These switches are only read from the main aggregate project (the - one passed on the command line), and ignored in all other aggregate - projects or projects. - - It can only contain builder switches, not compiler switches. - -.. index:: Global_Compilation_Switches (GNAT Project Manager) - -**Global_Compilation_Switches** - - This attribute gives the list of compiler switches for the various - languages. For instance, - - .. code-block:: gpr - - for Global_Compilation_Switches ("Ada") use ("O1", "-g"); - for Global_Compilation_Switches ("C") use ("-O2"); - - This attribute is only taken into account in the aggregate project - specified on the command line, not in other aggregate projects. - - In the projects grouped by that aggregate, the attribute - Builder.Global_Compilation_Switches is also ignored. However, the - attribute Compiler.Default_Switches will be taken into account (but - that of the aggregate have higher priority). The attribute - Compiler.Switches is also taken into account and can be used to - override the switches for a specific file. As a result, it always - has priority. - - The rules are meant to avoid ambiguities when compiling. For - instance, aggregate project Agg groups the projects A and B, that - both depend on C. Here is an extra for all of these projects: - - - .. code-block:: gpr - - aggregate project Agg is - for Project_Files use ("a.gpr", "b.gpr"); - package Builder is - for Global_Compilation_Switches ("Ada") use ("-O2"); - end Builder; - end Agg; - - with "c.gpr"; - project A is - package Builder is - for Global_Compilation_Switches ("Ada") use ("-O1"); - -- ignored - end Builder; - - package Compiler is - for Default_Switches ("Ada") - use ("-O1", "-g"); - for Switches ("a_file1.adb") - use ("-O0"); - end Compiler; - end A; - - with "c.gpr"; - project B is - package Compiler is - for Default_Switches ("Ada") use ("-O0"); - end Compiler; - end B; - - project C is - package Compiler is - for Default_Switches ("Ada") - use ("-O3", - "-gnatn"); - for Switches ("c_file1.adb") - use ("-O0", "-g"); - end Compiler; - end C; - - - then the following switches are used: - - * all files from project A except a_file1.adb are compiled - with "-O2 -g", since the aggregate project has priority. - - * the file a_file1.adb is compiled with - "-O0", since the Compiler.Switches has priority - - * all files from project B are compiled with - "-O2", since the aggregate project has priority - - * all files from C are compiled with "-O2 -gnatn", except for - c_file1.adb which is compiled with "-O0 -g" - - Even though C is seen through two paths (through A and through - B), the switches used by the compiler are unambiguous. - - -.. index:: Global_Configuration_Pragmas (GNAT Project Manager) - -**Global_Configuration_Pragmas** - - This attribute can be used to specify a file containing - configuration pragmas, to be passed to the Ada compiler. Since we - ignore the package Builder in other aggregate projects and projects, - only those pragmas defined in the main aggregate project will be - taken into account. - - Projects can locally add to those by using the - `Compiler.Local_Configuration_Pragmas` attribute if they need. - - -.. index:: Global_Config_File (GNAT Project Manager) - -**Global_Config_File** - - This attribute, indexed with a language name, can be used to specify a config - when compiling sources of the language. For Ada, these files are configuration - pragmas files. - -For projects that are built through the aggregate, the package Builder -is ignored, except for the Executable attribute which specifies the -name of the executables resulting from the link of the main programs, and -for the Executable_Suffix. - - -.. _Aggregate_Library_Projects: - -Aggregate Library Projects -========================== - -Aggregate library projects make it possible to build a single library -using object files built using other standard or library -projects. This gives the flexibility to describe an application as -having multiple modules (a GUI, database access, ...) using different -project files (so possibly built with different compiler options) and -yet create a single library (static or relocatable) out of the -corresponding object files. - -.. _Building_aggregate_library_projects: - -Building aggregate library projects ------------------------------------ - -For example, we can define an aggregate project Agg that groups A, B -and C: - -.. code-block:: gpr - - aggregate library project Agg is - for Project_Files use ("a.gpr", "b.gpr", "c.gpr"); - for Library_Name use ("agg"); - for Library_Dir use ("lagg"); - end Agg; - -Then, when you build with: - -.. code-block:: sh - - gprbuild agg.gpr - -This will build all units from projects A, B and C and will create a -static library named :file:`libagg.a` in the :file:`lagg` -directory. An aggregate library project has the same set of -restriction as a standard library project. - -Note that a shared aggregate library project cannot aggregate a -static library project. In platforms where a compiler option is -required to create relocatable object files, a Builder package in the -aggregate library project may be used: - -.. code-block:: gpr - - aggregate library project Agg is - for Project_Files use ("a.gpr", "b.gpr", "c.gpr"); - for Library_Name use ("agg"); - for Library_Dir use ("lagg"); - for Library_Kind use "relocatable"; - - package Builder is - for Global_Compilation_Switches ("Ada") use ("-fPIC"); - end Builder; - end Agg; - -With the above aggregate library Builder package, the `-fPIC` -option will be passed to the compiler when building any source code -from projects :file:`a.gpr`, :file:`b.gpr` and :file:`c.gpr`. - - -.. _Syntax_of_aggregate_library_projects: - -Syntax of aggregate library projects ------------------------------------- - -An aggregate library project follows the general syntax of project -files. The recommended extension is still :file:`.gpr`. However, a special -`aggregate library` qualifier must be put before the keyword -`project`. - -An aggregate library project cannot |with| any other project -(standard or aggregate), except an abstract project which can be used -to share attribute values. - -An aggregate library project does not have any source files directly (only -through other standard projects). Therefore a number of the standard -attributes and packages are forbidden in an aggregate library -project. Here is the (non exhaustive) list: - -* Languages -* Source_Files, Source_List_File and other attributes dealing with - list of sources. -* Source_Dirs, Exec_Dir and Object_Dir -* Main -* Roots -* Externally_Built -* Inherit_Source_Path -* Excluded_Source_Dirs -* Locally_Removed_Files -* Excluded_Source_Files -* Excluded_Source_List_File -* Interfaces - -The only package that is authorized (albeit optional) is Builder. - -The Project_Files attribute (See :ref:`Aggregate_Projects`) is used to -described the aggregated projects whose object files have to be -included into the aggregate library. The environment variables -`ADA_PROJECT_PATH`, `GPR_PROJECT_PATH` and -`GPR_PROJECT_PATH_FILE` are not used to find the project files. - - -.. _Project_File_Reference: - -Project File Reference -====================== - -This section describes the syntactic structure of project files, the various -constructs that can be used. Finally, it ends with a summary of all available -attributes. - - -.. _Project_Declaration: - -Project Declaration -------------------- - -Project files have an Ada-like syntax. The minimal project file is: - -.. code-block:: gpr - - project Empty is - end Empty; - -The identifier `Empty` is the name of the project. -This project name must be present after the reserved -word `end` at the end of the project file, followed by a semi-colon. - -**Identifiers** (i.e., the user-defined names such as project or variable names) -have the same syntax as Ada identifiers: they must start with a letter, -and be followed by zero or more letters, digits or underscore characters; -it is also illegal to have two underscores next to each other. Identifiers -are always case-insensitive ("Name" is the same as "name"). - -:: - - simple_name ::= identifier - name ::= simple_name { . simple_name } - -**Strings** are used for values of attributes or as indexes for these -attributes. They are in general case sensitive, except when noted -otherwise (in particular, strings representing file names will be case -insensitive on some systems, so that "file.adb" and "File.adb" both -represent the same file). - -**Reserved words** are the same as for standard Ada 95, and cannot -be used for identifiers. In particular, the following words are currently -used in project files, but others could be added later on. In bold are the -extra reserved words in project files: -``all``, ``at``, ``case``, ``end``, ``for``, ``is``, ``limited``, -``null``, ``others``, ``package``, ``renames``, ``type``, ``use``, ``when``, -``with``, **extends**, **external**, **project**. - -**Comments** in project files have the same syntax as in Ada, two consecutive -hyphens through the end of the line. - -A project may be an **independent project**, entirely defined by a single -project file. Any source file in an independent project depends only -on the predefined library and other source files in the same project. -But a project may also depend on other projects, either by importing them -through **with clauses**, or by **extending** at most one other project. Both -types of dependency can be used in the same project. - -A path name denotes a project file. It can be absolute or relative. -An absolute path name includes a sequence of directories, in the syntax of -the host operating system, that identifies uniquely the project file in the -file system. A relative path name identifies the project file, relative -to the directory that contains the current project, or relative to a -directory listed in the environment variables ADA_PROJECT_PATH and -GPR_PROJECT_PATH. Path names are case sensitive if file names in the host -operating system are case sensitive. As a special case, the directory -separator can always be "/" even on Windows systems, so that project files -can be made portable across architectures. -The syntax of the environment variables ADA_PROJECT_PATH and -GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and -semicolons on Windows. - -A given project name can appear only once in a context clause. - -It is illegal for a project imported by a context clause to refer, directly -or indirectly, to the project in which this context clause appears (the -dependency graph cannot contain cycles), except when one of the with clauses -in the cycle is a **limited with**. - -.. code-block:: gpr - - with "other_project.gpr"; - project My_Project extends "extended.gpr" is - end My_Project; - -These dependencies form a **directed graph**, potentially cyclic when using -**limited with**. The subgraph reflecting the **extends** relations is a tree. - -A project's **immediate sources** are the source files directly defined by -that project, either implicitly by residing in the project source directories, -or explicitly through any of the source-related attributes. -More generally, a project's **sources** are the immediate sources of the -project together with the immediate sources (unless overridden) of any project -on which it depends directly or indirectly. - -A **project hierarchy** can be created, where projects are children of -other projects. The name of such a child project must be `Parent.Child`, -where `Parent` is the name of the parent project. In particular, this -makes all |with| clauses of the parent project automatically visible -in the child project. - -:: - - project ::= context_clause project_declaration - - context_clause ::= {with_clause} - with_clause ::= *with* path_name { , path_name } ; - path_name ::= string_literal - - project_declaration ::= simple_project_declaration | project_extension - simple_project_declaration ::= - project name is - {declarative_item} - end simple_name; - - -.. _Qualified_Projects: - -Qualified Projects ------------------- - -Before the reserved `project`, there may be one or two **qualifiers**, that -is identifiers or reserved words, to qualify the project. -The current list of qualifiers is: - -**abstract**: - Qualifies a project with no sources. - Such a project must either have no declaration of attributes `Source_Dirs`, - `Source_Files`, `Languages` or `Source_List_File`, or one of - `Source_Dirs`, `Source_Files`, or `Languages` must be declared - as empty. If it extends another project, the project it extends must also be a - qualified abstract project. - -**standard**: - A standard project is a non library project with sources. - This is the default (implicit) qualifier. - -**aggregate**: - A project whose sources are aggregated from other project files. - -**aggregate library**: - A library whose sources are aggregated from other project - or library project files. - -**library**: - A library project must declare both attributes - Library_Name` and `Library_Dir`. - -**configuration**: - A configuration project cannot be in a project tree. - It describes compilers and other tools to *gprbuild*. - - -.. _Declarations: - -Declarations ------------- - -Declarations introduce new entities that denote types, variables, attributes, -and packages. Some declarations can only appear immediately within a project -declaration. Others can appear within a project or within a package. - -:: - - declarative_item ::= simple_declarative_item - | typed_string_declaration - | package_declaration - - simple_declarative_item ::= variable_declaration - | typed_variable_declaration - | attribute_declaration - | case_construction - | empty_declaration - - empty_declaration ::= *null* ; - -An empty declaration is allowed anywhere a declaration is allowed. It has -no effect. - - -.. _Packages: - -Packages --------- - -A project file may contain **packages**, that group attributes (typically -all the attributes that are used by one of the GNAT tools). - -A package with a given name may only appear once in a project file. -The following packages are currently supported in project files -(See :ref:`Attributes` for the list of attributes that each can contain). - -*Binder* - This package specifies characteristics useful when invoking the binder either - directly via the *gnat* driver or when using *gprbuild*. - See :ref:`Main_Subprograms`. - -*Builder* - This package specifies the compilation options used when building an - executable or a library for a project. Most of the options should be - set in one of `Compiler`, `Binder` or `Linker` packages, - but there are some general options that should be defined in this - package. See :ref:`Main_Subprograms`, and :ref:`Executable_File_Names` in - particular. - -.. only:: PRO or GPL - - *Check* - This package specifies the options used when calling the checking tool - *gnatcheck* via the *gnat* driver. Its attribute - **Default_Switches** has the same semantics as for the package - `Builder`. The first string should always be `-rules` to specify - that all the other options belong to the `-rules` section of the - parameters to *gnatcheck*. - -*Clean* - This package specifies the options used when cleaning a project or a project - tree using the tools *gnatclean* or *gprclean*. - -*Compiler* - This package specifies the compilation options used by the compiler for - each languages. See :ref:`Tools_Options_in_Project_Files`. - -*Cross_Reference* - This package specifies the options used when calling the library tool - *gnatxref* via the *gnat* driver. Its attributes - **Default_Switches** and **Switches** have the same semantics as for the - package `Builder`. - -.. only:: PRO or GPL - - *Eliminate* - This package specifies the options used when calling the tool - *gnatelim* via the *gnat* driver. Its attributes - **Default_Switches** and **Switches** have the same semantics as for the - package `Builder`. - -*Finder* - This package specifies the options used when calling the search tool - *gnatfind* via the *gnat* driver. Its attributes - **Default_Switches** and **Switches** have the same semantics as for the - package `Builder`. - -*Gnatls* - This package specifies the options to use when invoking *gnatls* - via the *gnat* driver. - -.. only:: PRO or GPL - - *Gnatstub* - This package specifies the options used when calling the tool - *gnatstub* via the *gnat* driver. Its attributes - **Default_Switches** and **Switches** have the same semantics as for the - package `Builder`. - -*IDE* - This package specifies the options used when starting an integrated - development environment, for instance *GPS* or *Gnatbench*. - -*Install* - This package specifies the options used when installing a project - with *gprinstall*. See :ref:`Installation`. - -*Linker* - This package specifies the options used by the linker. - See :ref:`Main_Subprograms`. - -.. only:: PRO or GPL - - *Metrics* - This package specifies the options used when calling the tool - *gnatmetric* via the *gnat* driver. Its attributes - **Default_Switches** and **Switches** have the same semantics as for the - package `Builder`. - -*Naming* - This package specifies the naming conventions that apply - to the source files in a project. In particular, these conventions are - used to automatically find all source files in the source directories, - or given a file name to find out its language for proper processing. - See :ref:`Naming_Schemes`. - - .. only:: PRO or GPL - - *Pretty_Printer* - This package specifies the options used when calling the formatting tool - *gnatpp* via the *gnat* driver. Its attributes - **Default_Switches** and **Switches** have the same semantics as for the - package `Builder`. - -*Remote* - This package is used by *gprbuild* to describe how distributed - compilation should be done. - -*Stack* - This package specifies the options used when calling the tool - *gnatstack* via the *gnat* driver. Its attributes - **Default_Switches** and **Switches** have the same semantics as for the - package `Builder`. - -*Synchronize* - This package specifies the options used when calling the tool - *gnatsync* via the *gnat* driver. - -In its simplest form, a package may be empty: - -.. code-block:: gpr - - project Simple is - package Builder is - end Builder; - end Simple; - -A package may contain **attribute declarations**, -**variable declarations** and **case constructions**, as will be -described below. - -When there is ambiguity between a project name and a package name, -the name always designates the project. To avoid possible confusion, it is -always a good idea to avoid naming a project with one of the -names allowed for packages or any name that starts with `gnat`. - -A package can also be defined by a **renaming declaration**. The new package -renames a package declared in a different project file, and has the same -attributes as the package it renames. The name of the renamed package -must be the same as the name of the renaming package. The project must -contain a package declaration with this name, and the project -must appear in the context clause of the current project, or be its parent -project. It is not possible to add or override attributes to the renaming -project. If you need to do so, you should use an **extending declaration** -(see below). - -Packages that are renamed in other project files often come from project files -that have no sources: they are just used as templates. Any modification in the -template will be reflected automatically in all the project files that rename -a package from the template. This is a very common way to share settings -between projects. - -Finally, a package can also be defined by an **extending declaration**. This is -similar to a **renaming declaration**, except that it is possible to add or -override attributes. - -:: - - package_declaration ::= package_spec | package_renaming | package_extension - package_spec ::= - package simple_name is - {simple_declarative_item} - end package_identifier ; - package_renaming ::== - package simple_name renames simple_name.package_identifier ; - package_extension ::== - package simple_name extends simple_name.package_identifier is - {simple_declarative_item} - end package_identifier ; - - -.. _Expressions: - -Expressions ------------ - -An expression is any value that can be assigned to an attribute or a -variable. It is either a literal value, or a construct requiring runtime -computation by the project manager. In a project file, the computed value of -an expression is either a string or a list of strings. - -A string value is one of: - -* A literal string, for instance `"comm/my_proj.gpr"` -* The name of a variable that evaluates to a string (see :ref:`Variables`) -* The name of an attribute that evaluates to a string (see :ref:`Attributes`) -* An external reference (see :ref:`External_Values`) -* A concatenation of the above, as in `"prefix_" & Var`. - -A list of strings is one of the following: - -* A parenthesized comma-separated list of zero or more string expressions, for - instance `(File_Name, "gnat.adc", File_Name & ".orig")` or `()`. -* The name of a variable that evaluates to a list of strings -* The name of an attribute that evaluates to a list of strings -* A concatenation of a list of strings and a string (as defined above), for - instance `("A", "B") & "C"` -* A concatenation of two lists of strings - -The following is the grammar for expressions - -:: - - string_literal ::= "{string_element}" -- Same as Ada - string_expression ::= string_literal - | *variable_*name - | external_value - | attribute_reference - | ( string_expression { & string_expression } ) - string_list ::= ( string_expression { , string_expression } ) - | *string_variable*_name - | *string_*attribute_reference - term ::= string_expression | string_list - expression ::= term { & term } -- Concatenation - -Concatenation involves strings and list of strings. As soon as a list of -strings is involved, the result of the concatenation is a list of strings. The -following Ada declarations show the existing operators: - -.. code-block:: ada - - function "&" (X : String; Y : String) return String; - function "&" (X : String_List; Y : String) return String_List; - function "&" (X : String_List; Y : String_List) return String_List; - - -Here are some specific examples: - -.. code-block:: ada - - List := () & File_Name; -- One string in this list - List2 := List & (File_Name & ".orig"); -- Two strings - Big_List := List & Lists2; -- Three strings - Illegal := "gnat.adc" & List2; -- Illegal, must start with list - - -.. _External_Values: - -External Values ---------------- - -An external value is an expression whose value is obtained from the command -that invoked the processing of the current project file (typically a -*gprbuild* command). - -There are two kinds of external values, one that returns a single string, and -one that returns a string list. - -The syntax of a single string external value is:: - - external_value ::= *external* ( string_literal [, string_literal] ) - - -The first string_literal is the string to be used on the command line or -in the environment to specify the external value. The second string_literal, -if present, is the default to use if there is no specification for this -external value either on the command line or in the environment. - -Typically, the external value will either exist in the -environment variables -or be specified on the command line through the -:samp:`-X{vbl}={value}` switch. If both -are specified, then the command line value is used, so that a user can more -easily override the value. - -The function `external` always returns a string. It is an error if the -value was not found in the environment and no default was specified in the -call to `external`. - -An external reference may be part of a string expression or of a string -list expression, and can therefore appear in a variable declaration or -an attribute declaration. - -Most of the time, this construct is used to initialize typed variables, which -are then used in **case** constructions to control the value assigned to -attributes in various scenarios. Thus such variables are often called -**scenario variables**. - -The syntax for a string list external value is:: - - external_value ::= *external_as_list* ( string_literal , string_literal ) - - -The first string_literal is the string to be used on the command line or -in the environment to specify the external value. The second string_literal is -the separator between each component of the string list. - -If the external value does not exist in the environment or on the command line, -the result is an empty list. This is also the case, if the separator is an -empty string or if the external value is only one separator. - -Any separator at the beginning or at the end of the external value is -discarded. Then, if there is no separator in the external value, the result is -a string list with only one string. Otherwise, any string between the beginning -and the first separator, between two consecutive separators and between the -last separator and the end are components of the string list. - -:: - - *external_as_list* ("SWITCHES", ",") - -If the external value is "-O2,-g", -the result is ("-O2", "-g"). - -If the external value is ",-O2,-g,", -the result is also ("-O2", "-g"). - -if the external value is "-gnatv", -the result is ("-gnatv"). - -If the external value is ",,", the result is (""). - -If the external value is ",", the result is (), the empty string list. - - -.. _Typed_String_Declaration: - -Typed String Declaration ------------------------- - -A **type declaration** introduces a discrete set of string literals. -If a string variable is declared to have this type, its value -is restricted to the given set of literals. These are the only named -types in project files. A string type may only be declared at the project -level, not inside a package. - -:: - - typed_string_declaration ::= - *type* **_simple_name *is* ( string_literal {, string_literal} ); - -The string literals in the list are case sensitive and must all be different. -They may include any graphic characters allowed in Ada, including spaces. -Here is an example of a string type declaration: - -.. code-block:: ada - - type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS"); - -Variables of a string type are called **typed variables**; all other -variables are called **untyped variables**. Typed variables are -particularly useful in `case` constructions, to support conditional -attribute declarations. (See :ref:`Case_Constructions`). - -A string type may be referenced by its name if it has been declared in the same -project file, or by an expanded name whose prefix is the name of the project -in which it is declared. - - -.. _Variables: - -Variables ---------- - -**Variables** store values (strings or list of strings) and can appear -as part of an expression. The declaration of a variable creates the -variable and assigns the value of the expression to it. The name of the -variable is available immediately after the assignment symbol, if you -need to reuse its old value to compute the new value. Before the completion -of its first declaration, the value of a variable defaults to the empty -string (""). - -A **typed** variable can be used as part of a **case** expression to -compute the value, but it can only be declared once in the project file, -so that all case constructions see the same value for the variable. This -provides more consistency and makes the project easier to understand. -The syntax for its declaration is identical to the Ada syntax for an -object declaration. In effect, a typed variable acts as a constant. - -An **untyped** variable can be declared and overridden multiple times -within the same project. It is declared implicitly through an Ada -assignment. The first declaration establishes the kind of the variable -(string or list of strings) and successive declarations must respect -the initial kind. Assignments are executed in the order in which they -appear, so the new value replaces the old one and any subsequent reference -to the variable uses the new value. - -A variable may be declared at the project file level, or within a package. - -:: - - typed_variable_declaration ::= - **simple_name : **name := string_expression; - - variable_declaration ::= **simple_name := expression; - -Here are some examples of variable declarations: - -.. code-block:: gpr - - This_OS : OS := external ("OS"); -- a typed variable declaration - That_OS := "GNU/Linux"; -- an untyped variable declaration - - Name := "readme.txt"; - Save_Name := Name & ".saved"; - - Empty_List := (); - List_With_One_Element := ("-gnaty"); - List_With_Two_Elements := List_With_One_Element & "-gnatg"; - Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada"); - -A **variable reference** may take several forms: - -* The simple variable name, for a variable in the current package (if any) - or in the current project -* An expanded name, whose prefix is a context name. - -A **context** may be one of the following: - -* The name of an existing package in the current project -* The name of an imported project of the current project -* The name of an ancestor project (i.e., a project extended by the current - project, either directly or indirectly) -* An expanded name whose prefix is an imported/parent project name, and - whose selector is a package name in that project. - - -.. _Case_Constructions: - -Case Constructions ------------------- - -A **case** construction is used in a project file to effect conditional -behavior. Through this construction, you can set the value of attributes -and variables depending on the value previously assigned to a typed -variable. - -All choices in a choice list must be distinct. Unlike Ada, the choice -lists of all alternatives do not need to include all values of the type. -An `others` choice must appear last in the list of alternatives. - -The syntax of a `case` construction is based on the Ada case construction -(although the `null` declaration for empty alternatives is optional). - -The case expression must be a string variable, either typed or not, whose value -is often given by an external reference (see :ref:`External_Values`). - -Each alternative starts with the reserved word `when`, either a list of -literal strings separated by the `"|"` character or the reserved word -`others`, and the `"=>"` token. -When the case expression is a typed string variable, each literal string must -belong to the string type that is the type of the case variable. -After each `=>`, there are zero or more declarations. The only -declarations allowed in a case construction are other case constructions, -attribute declarations and variable declarations. String type declarations and -package declarations are not allowed. Variable declarations are restricted to -variables that have already been declared before the case construction. - -:: - - case_construction ::= - *case* **name *is* {case_item} *end case* ; - - case_item ::= - *when* discrete_choice_list => - {case_declaration - | attribute_declaration - | variable_declaration - | empty_declaration} - - discrete_choice_list ::= string_literal {| string_literal} | *others* - -Here is a typical example, with a typed string variable: - -.. code-block:: gpr - - project MyProj is - type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS"); - OS : OS_Type := external ("OS", "GNU/Linux"); - - package Compiler is - case OS is - when "GNU/Linux" | "Unix" => - for Switches ("Ada") - use ("-gnath"); - when "NT" => - for Switches ("Ada") - use ("-gnatP"); - when others => - null; - end case; - end Compiler; - end MyProj; - - -.. _Attributes: - -Attributes ----------- - -A project (and its packages) may have **attributes** that define -the project's properties. Some attributes have values that are strings; -others have values that are string lists. - -:: - - attribute_declaration ::= - simple_attribute_declaration | indexed_attribute_declaration - - simple_attribute_declaration ::= *for* attribute_designator *use* expression ; - - indexed_attribute_declaration ::= - *for* **simple_name ( string_literal) *use* expression ; - - attribute_designator ::= - **simple_name - | **simple_name ( string_literal ) - -There are two categories of attributes: **simple attributes** -and **indexed attributes**. -Each simple attribute has a default value: the empty string (for string -attributes) and the empty list (for string list attributes). -An attribute declaration defines a new value for an attribute, and overrides -the previous value. The syntax of a simple attribute declaration is similar to -that of an attribute definition clause in Ada. - -Some attributes are indexed. These attributes are mappings whose -domain is a set of strings. They are declared one association -at a time, by specifying a point in the domain and the corresponding image -of the attribute. -Like untyped variables and simple attributes, indexed attributes -may be declared several times. Each declaration supplies a new value for the -attribute, and replaces the previous setting. - -Here are some examples of attribute declarations: - -.. code-block:: gpr - - -- simple attributes - for Object_Dir use "objects"; - for Source_Dirs use ("units", "test/drivers"); - - -- indexed attributes - for Body ("main") use "Main.ada"; - for Switches ("main.ada") - use ("-v", "-gnatv"); - for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g"; - - -- indexed attributes copy (from package Builder in project Default) - -- The package name must always be specified, even if it is the current - -- package. - for Default_Switches use Default.Builder'Default_Switches; - -Attributes references may appear anywhere in expressions, and are used -to retrieve the value previously assigned to the attribute. If an attribute -has not been set in a given package or project, its value defaults to the -empty string or the empty list, with some exceptions. - -:: - - attribute_reference ::= - attribute_prefix ' *_*simple_name [ (string_literal) ] - attribute_prefix ::= *project* - | **simple_name - | package_identifier - | **simple_name . package_identifier - -Examples are:: - - 'Object_Dir - Naming'Dot_Replacement - Imported_Project'Source_Dirs - Imported_Project.Naming'Casing - Builder'Default_Switches ("Ada") - -The exceptions to the empty defaults are: - -* Object_Dir: default is "." -* Exec_Dir: default is 'Object_Dir, that is the value of attribute - Object_Dir in the same project, declared or defaulted. -* Source_Dirs: default is (".") - -The prefix of an attribute may be: - -* `project` for an attribute of the current project -* The name of an existing package of the current project -* The name of an imported project -* The name of a parent project that is extended by the current project -* An expanded name whose prefix is imported/parent project name, - and whose selector is a package name - -In the following sections, all predefined attributes are succinctly described, -first the project level attributes, that is those attributes that are not in a -package, then the attributes in the different packages. - -It is possible for different tools to dynamically create new packages with -attributes, or new attributes in predefined packages. These attributes are -not documented here. - -The attributes under Configuration headings are usually found only in -configuration project files. - -The characteristics of each attribute are indicated as follows: - -* **Type of value** - - The value of an attribute may be a single string, indicated by the word - "single", or a string list, indicated by the word "list". - -* **Read-only** - - When the attribute is read-only, that is when it is not allowed to declare - the attribute, this is indicated by the words "read-only". - -* **Optional index** - - If it is allowed in the value of the attribute (both single and list) to have - an optional index, this is indicated by the words "optional index". - -* **Indexed attribute** - - When it is an indexed attribute, this is indicated by the word "indexed". - -* **Case-sensitivity of the index** - - For an indexed attribute, if the index is case-insensitive, this is indicated - by the words "case-insensitive index". - -* **File name index** - - For an indexed attribute, when the index is a file name, this is indicated by - the words "file name index". The index may or may not be case-sensitive, - depending on the platform. - -* **others allowed in index** - - For an indexed attribute, if it is allowed to use **others** as the index, - this is indicated by the words "others allowed". - - When **others** is used as the index of an indexed attribute, the value of - the attribute indexed by **others** is used when no other index would apply. - - -.. _Project_Level_Attributes: - -Project Level Attributes -^^^^^^^^^^^^^^^^^^^^^^^^ - - -* **General** - - * **Name**: single, read-only - - The name of the project. - - * **Project_Dir**: single, read-only - - The path name of the project directory. - - * **Main**: list, optional index - - The list of main sources for the executables. - - * **Languages**: list - - The list of languages of the sources of the project. - - * **Roots**: list, indexed, file name index - - The index is the file name of an executable source. Indicates the list of units - from the main project that need to be bound and linked with their closures - with the executable. The index is either a file name, a language name or "*". - The roots for an executable source are those in **Roots** with an index that - is the executable source file name, if declared. Otherwise, they are those in - **Roots** with an index that is the language name of the executable source, - if present. Otherwise, they are those in **Roots ("*")**, if declared. If none - of these three possibilities are declared, then there are no roots for the - executable source. - - * **Externally_Built**: single - - Indicates if the project is externally built. - Only case-insensitive values allowed are "true" and "false", the default. - -* **Directories** - - * **Object_Dir**: single - - Indicates the object directory for the project. - - * **Exec_Dir**: single - - Indicates the exec directory for the project, that is the directory where the - executables are. - - * **Source_Dirs**: list - - The list of source directories of the project. - - * **Inherit_Source_Path**: list, indexed, case-insensitive index - - Index is a language name. Value is a list of language names. Indicates that - in the source search path of the index language the source directories of - the languages in the list should be included. - - Example: - - .. code-block:: gpr - - for Inherit_Source_Path ("C++") use ("C"); - - * **Exclude_Source_Dirs**: list - - The list of directories that are included in Source_Dirs but are not source - directories of the project. - - * **Ignore_Source_Sub_Dirs**: list - - Value is a list of simple names for subdirectories that are removed from the - list of source directories, including theur subdirectories. - -* **Source Files** - - * **Source_Files**: list - - Value is a list of source file simple names. - - * **Locally_Removed_Files**: list - - Obsolescent. Equivalent to Excluded_Source_Files. - - * **Excluded_Source_Files**: list - - Value is a list of simple file names that are not sources of the project. - Allows to remove sources that are inherited or found in the source directories - and that match the naming scheme. - - * **Source_List_File**: single - - Value is a text file name that contains a list of source file simple names, - one on each line. - - * **Excluded_Source_List_File**: single - - Value is a text file name that contains a list of file simple names that - are not sources of the project. - - * **Interfaces**: list - - Value is a list of file names that constitutes the interfaces of the project. - -* **Aggregate Projects** - - * **Project_Files**: list - - Value is the list of aggregated projects. - - * **Project_Path**: list - - Value is a list of directories that are added to the project search path when - looking for the aggregated projects. - - * **External**: single, indexed - - Index is the name of an external reference. Value is the value of the - external reference to be used when parsing the aggregated projects. - -* **Libraries** - - * **Library_Dir**: single - - Value is the name of the library directory. This attribute needs to be - declared for each library project. - - * **Library_Name**: single - - Value is the name of the library. This attribute needs to be declared or - inherited for each library project. - - * **Library_Kind**: single - - Specifies the kind of library: static library (archive) or shared library. - Case-insensitive values must be one of "static" for archives (the default) or - "dynamic" or "relocatable" for shared libraries. - - * **Library_Version**: single - - Value is the name of the library file. - - * **Library_Interface**: list - - Value is the list of unit names that constitutes the interfaces - of a Stand-Alone Library project. - - * **Library_Standalone**: single - - Specifies if a Stand-Alone Library (SAL) is encapsulated or not. - Only authorized case-insensitive values are "standard" for non encapsulated - SALs, "encapsulated" for encapsulated SALs or "no" for non SAL library project. - - * **Library_Encapsulated_Options**: list - - Value is a list of options that need to be used when linking an encapsulated - Stand-Alone Library. - - * **Library_Encapsulated_Supported**: single - - Indicates if encapsulated Stand-Alone Libraries are supported. Only - authorized case-insensitive values are "true" and "false" (the default). - - * **Library_Auto_Init**: single - - Indicates if a Stand-Alone Library is auto-initialized. Only authorized - case-insentive values are "true" and "false". - - * **Leading_Library_Options**: list - - Value is a list of options that are to be used at the beginning of - the command line when linking a shared library. - - * **Library_Options**: list - - Value is a list of options that are to be used when linking a shared library. - - * **Library_Rpath_Options**: list, indexed, case-insensitive index - - Index is a language name. Value is a list of options for an invocation of the - compiler of the language. This invocation is done for a shared library project - with sources of the language. The output of the invocation is the path name - of a shared library file. The directory name is to be put in the run path - option switch when linking the shared library for the project. - - * **Library_Src_Dir**: single - - Value is the name of the directory where copies of the sources of the - interfaces of a Stand-Alone Library are to be copied. - - * **Library_ALI_Dir**: single - - Value is the name of the directory where the ALI files of the interfaces - of a Stand-Alone Library are to be copied. When this attribute is not declared, - the directory is the library directory. - - * **Library_gcc**: single - - Obsolescent attribute. Specify the linker driver used to link a shared library. - Use instead attribute Linker'Driver. - - * **Library_Symbol_File**: single - - Value is the name of the library symbol file. - - * **Library_Symbol_Policy**: single - - Indicates the symbol policy kind. Only authorized case-insensitive values are - "autonomous", "default", "compliant", "controlled" or "direct". - - * **Library_Reference_Symbol_File**: single - - Value is the name of the reference symbol file. - -* **Configuration - General** - - * **Default_Language**: single - - Value is the case-insensitive name of the language of a project when attribute - Languages is not specified. - - * **Run_Path_Option**: list - - Value is the list of switches to be used when specifying the run path option - in an executable. - - * **Run_Path_Origin**: single - - Value is the the string that may replace the path name of the executable - directory in the run path options. - - * **Separate_Run_Path_Options**: single - - Indicates if there may be several run path options specified when linking an - executable. Only authorized case-insensitive values are "true" or "false" (the - default). - - * **Toolchain_Version**: single, indexed, case-insensitive index - - Index is a language name. Specify the version of a toolchain for a language. - - * **Toolchain_Description**: single, indexed, case-insensitive index - - Obsolescent. No longer used. - - * **Object_Generated**: single, indexed, case-insensitive index - - Index is a language name. Indicates if invoking the compiler for a language - produces an object file. Only authorized case-insensitive values are "false" - and "true" (the default). - - * **Objects_Linked**: single, indexed, case-insensitive index - - Index is a language name. Indicates if the object files created by the compiler - for a language need to be linked in the executable. Only authorized - case-insensitive values are "false" and "true" (the default). - - * **Target**: single - - Value is the name of the target platform. Taken into account only in the main - project. - - Note that when the target is specified on the command line (usually with - a switch --target=), the value of attribute reference 'Target is the one - specified on the command line. - - * **Runtime**: single, indexed, case-insensitive index - - Index is a language name. Indicates the runtime directory that is to be used - when using the compiler of the language. Taken into account only in the main - project. - - Note that when the runtime is specified for a language on the command line - (usually with a switch --RTS), the value of attribute reference 'Runtime - for this language is the one specified on the command line. - -* **Configuration - Libraries** - - * **Library_Builder**: single - - Value is the path name of the application that is to be used to build - libraries. Usually the path name of "gprlib". - - * **Library_Support**: single - - Indicates the level of support of libraries. Only authorized case-insensitive - values are "static_only", "full" or "none" (the default). - -* **Configuration - Archives** - - * **Archive_Builder**: list - - Value is the name of the application to be used to create a static library - (archive), followed by the options to be used. - - * **Archive_Builder_Append_Option**: list - - Value is the list of options to be used when invoking the archive builder - to add project files into an archive. - - * **Archive_Indexer**: list - - Value is the name of the archive indexer, followed by the required options. - - * **Archive_Suffix**: single - - Value is the extension of archives. When not declared, the extension is ".a". - - * **Library_Partial_Linker**: list - - Value is the name of the partial linker executable, followed by the required - options. - -* **Configuration - Shared Libraries** - - * **Shared_Library_Prefix**: single - - Value is the prefix in the name of shared library files. When not declared, - the prefix is "lib". - - * **Shared_Library_Suffix**: single - - Value is the the extension of the name of shared library files. When not - declared, the extension is ".so". - - * **Symbolic_Link_Supported**: single - - Indicates if symbolic links are supported on the platform. Only authorized - case-insensitive values are "true" and "false" (the default). - - * **Library_Major_Minor_Id_Supported**: single - - Indicates if major and minor ids for shared library names are supported on - the platform. Only authorized case-insensitive values are "true" and "false" - (the default). - - * **Library_Auto_Init_Supported**: single - - Indicates if auto-initialization of Stand-Alone Libraries is supported. Only - authorized case-insensitive values are "true" and "false" (the default). - - * **Shared_Library_Minimum_Switches**: list - - Value is the list of required switches when linking a shared library. - - * **Library_Version_Switches**: list - - Value is the list of switches to specify a internal name for a shared library. - - * **Library_Install_Name_Option**: single - - Value is the name of the option that needs to be used, concatenated with the - path name of the library file, when linking a shared library. - - * **Runtime_Library_Dir**: single, indexed, case-insensitive index - - Index is a language name. Value is the path name of the directory where the - runtime libraries are located. - - * **Runtime_Source_Dir**: single, indexed, case-insensitive index - - Index is a language name. Value is the path name of the directory where the - sources of runtime libraries are located. - - -.. _Package_Binder_Attributes: - -Package Binder Attributes -^^^^^^^^^^^^^^^^^^^^^^^^^ - -* **General** - - * **Default_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is the list of switches to be used when binding - code of the language, if there is no applicable attribute Switches. - - * **Switches**: list, optional index, indexed, - case-insensitive index, others allowed - - Index is either a language name or a source file name. Value is the list of - switches to be used when binding code. Index is either the source file name - of the executable to be bound or the language name of the code to be bound. - -* **Configuration - Binding** - - * **Driver**: single, indexed, case-insensitive index - - Index is a language name. Value is the name of the application to be used when - binding code of the language. - - * **Required_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is the list of the required switches to be - used when binding code of the language. - - * **Prefix**: single, indexed, case-insensitive index - - Index is a language name. Value is a prefix to be used for the binder exchange - file name for the language. Used to have different binder exchange file names - when binding different languages. - - * **Objects_Path**: single,indexed, case-insensitive index - - Index is a language name. Value is the name of the environment variable that - contains the path for the object directories. - - * **Object_Path_File**: single,indexed, case-insensitive index - - Index is a language name. Value is the name of the environment variable. The - value of the environment variable is the path name of a text file that - contains the list of object directories. - - -.. _Package_Builder_Attributes: - -Package Builder Attributes -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* **Default_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is the list of builder switches to be used when - building an executable of the language, if there is no applicable attribute - Switches. - -* **Switches**: list, optional index, indexed, case-insensitive index, - others allowed - - Index is either a language name or a source file name. Value is the list of - builder switches to be used when building an executable. Index is either the - source file name of the executable to be built or its language name. - -* **Global_Compilation_Switches**: list, optional index, indexed, - case-insensitive index - - Index is a language name. Value is the list of compilation switches to be - used when building an executable. Index is either the source file name of - the executable to be built or its language name. - -* **Executable**: single, indexed, case-insensitive index - - Index is an executable source file name. Value is the simple file name of the - executable to be built. - -* **Executable_Suffix**: single - - Value is the extension of the file names of executable. When not specified, - the extension is the default extension of executables on the platform. - -* **Global_Configuration_Pragmas**: single - - Value is the file name of a configuration pragmas file that is specified to - the Ada compiler when compiling any Ada source in the project tree. - -* **Global_Config_File**: single, indexed, case-insensitive index - - Index is a language name. Value is the file name of a configuration file that - is specified to the compiler when compiling any source of the language in the - project tree. - - -.. only:: PRO and GPL - - .. _Package_Check_Attributes: - - Package Check Attributes - ^^^^^^^^^^^^^^^^^^^^^^^^ - - * **Default_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is a list of switches to be used when invoking - `gnatcheck` for a source of the language, if there is no applicable - attribute Switches. - - * **Switches**: list, optional index, indexed, case-insensitive index, - others allowed - - Index is a source file name. Value is the list of switches to be used when - invoking `gnatcheck` for the source. - -.. _Package_Clean_Attributes: - -Package Clean Attributes -^^^^^^^^^^^^^^^^^^^^^^^^ - -* **Switches**: list - - Value is a list of switches to be used by the cleaning application. - -* **Source_Artifact_Extensions**: list, indexed, case-insensitive index - - Index is a language names. Value is the list of extensions for file names - derived from object file names that need to be cleaned in the object - directory of the project. - -* **Object_Artifact_Extensions**: list, indexed, case-insensitive index - - Index is a language names. Value is the list of extensions for file names - derived from source file names that need to be cleaned in the object - directory of the project. - -* **Artifacts_In_Object_Dir**: single - - Value is a list of file names expressed as regular expressions that are to be - deleted by gprclean in the object directory of the project. - -* **Artifacts_In_Exec_Dir**: single - - Value is list of file names expressed as regular expressions that are to be - deleted by gprclean in the exec directory of the main project. - -.. _Package_Compiler_Attributes: - -Package Compiler Attributes -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* **General** - - * **Default_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is a list of switches to be used when invoking - the compiler for the language for a source of the project, if there is no - applicable attribute Switches. - - * **Switches**: list, optional index, indexed, case-insensitive index, - others allowed - - Index is a source file name or a language name. Value is the list of switches - to be used when invoking the compiler for the source or for its language. - - * **Local_Configuration_Pragmas**: single - - Value is the file name of a configuration pragmas file that is specified to - the Ada compiler when compiling any Ada source in the project. - - * **Local_Config_File**: single, indexed, case-insensitive index - - Index is a language name. Value is the file name of a configuration file that - is specified to the compiler when compiling any source of the language in the - project. - -* **Configuration - Compiling** - - * **Driver**: single, indexed, case-insensitive index - - Index is a language name. Value is the name of the executable for the compiler - of the language. - - * **Language_Kind**: single, indexed, case-insensitive index - - Index is a language name. Indicates the kind of the language, either file based - or unit based. Only authorized case-insensitive values are "unit_based" and - "file_based" (the default). - - * **Dependency_Kind**: single, indexed, case-insensitive index - - Index is a language name. Indicates how the dependencies are handled for the - language. Only authorized case-insensitive values are "makefile", "ali_file", - "ali_closure" or "none" (the default). - - * **Required_Switches**: list, indexed, case-insensitive index - - Equivalent to attribute Leading_Required_Switches. - - * **Leading_Required_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is the list of the minimum switches to be used - at the beginning of the command line when invoking the compiler for the - language. - - * **Trailing_Required_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is the list of the minimum switches to be used - at the end of the command line when invoking the compiler for the language. - - * **PIC_Option**: list, indexed, case-insensitive index - - Index is a language name. Value is the list of switches to be used when - compiling a source of the language when the project is a shared library - project. - - * **Path_Syntax**: single, indexed, case-insensitive index - - Index is a language name. Value is the kind of path syntax to be used when - invoking the compiler for the language. Only authorized case-insensitive - values are "canonical" and "host" (the default). - - * **Source_File_Switches**: single, indexed, case-insensitive index - - Index is a language name. Value is a list of switches to be used just before - the path name of the source to compile when invoking the compiler for a source - of the language. - - * **Object_File_Suffix**: single, indexed, case-insensitive index - - Index is a language name. Value is the extension of the object files created - by the compiler of the language. When not specified, the extension is the - default one for the platform. - - * **Object_File_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is the list of switches to be used by the - compiler of the language to specify the path name of the object file. When not - specified, the switch used is "-o". - - * **Multi_Unit_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is the list of switches to be used to compile - a unit in a multi unit source of the language. The index of the unit in the - source is concatenated with the last switches in the list. - - * **Multi_Unit_Object_Separator**: single, indexed, case-insensitive index - - Index is a language name. Value is the string to be used in the object file - name before the index of the unit, when compiling a unit in a multi unit source - of the language. - -* **Configuration - Mapping Files** - - * **Mapping_File_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is the list of switches to be used to specify - a mapping file when invoking the compiler for a source of the language. - - * **Mapping_Spec_Suffix**: single, indexed, case-insensitive index - - Index is a language name. Value is the suffix to be used in a mapping file - to indicate that the source is a spec. - - * **Mapping_Body_Suffix**: single, indexed, case-insensitive index - - Index is a language name. Value is the suffix to be used in a mapping file - to indicate that the source is a body. - -* **Configuration - Config Files** - - * **Config_File_Switches**: list: single, indexed, case-insensitive index - - Index is a language name. Value is the list of switches to specify to the - compiler of the language a configuration file. - - * **Config_Body_File_Name**: single, indexed, case-insensitive index - - Index is a language name. Value is the template to be used to indicate a - configuration specific to a body of the language in a configuration - file. - - * **Config_Body_File_Name_Index**: single, indexed, case-insensitive index - - Index is a language name. Value is the template to be used to indicate a - configuration specific to the body a unit in a multi unit source of the - language in a configuration file. - - * **Config_Body_File_Name_Pattern**: single, indexed, - case-insensitive index - - Index is a language name. Value is the template to be used to indicate a - configuration for all bodies of the languages in a configuration file. - - * **Config_Spec_File_Name**: single, indexed, case-insensitive index - - Index is a language name. Value is the template to be used to indicate a - configuration specific to a spec of the language in a configuration - file. - - * **Config_Spec_File_Name_Index**: single, indexed, case-insensitive index - - Index is a language name. Value is the template to be used to indicate a - configuration specific to the spec a unit in a multi unit source of the - language in a configuration file. - - * **Config_Spec_File_Name_Pattern**: single, indexed, - case-insensitive index - - Index is a language name. Value is the template to be used to indicate a - configuration for all specs of the languages in a configuration file. - - * **Config_File_Unique**: single, indexed, case-insensitive index - - Index is a language name. Indicates if there should be only one configuration - file specified to the compiler of the language. Only authorized - case-insensitive values are "true" and "false" (the default). - -* **Configuration - Dependencies** - - * **Dependency_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is the list of switches to be used to specify - to the compiler the dependency file when the dependency kind of the language is - file based, and when Dependency_Driver is not specified for the language. - - * **Dependency_Driver**: list, indexed, case-insensitive index - - Index is a language name. Value is the name of the executable to be used to - create the dependency file for a source of the language, followed by the - required switches. - -* **Configuration - Search Paths** - - * **Include_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is the list of switches to specify to the - compiler of the language to indicate a directory to look for sources. - - * **Include_Path**: single, indexed, case-insensitive index - - Index is a language name. Value is the name of an environment variable that - contains the path of all the directories that the compiler of the language - may search for sources. - - * **Include_Path_File**: single, indexed, case-insensitive index - - Index is a language name. Value is the name of an environment variable the - value of which is the path name of a text file that contains the directories - that the compiler of the language may search for sources. - - * **Object_Path_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is the list of switches to specify to the - compiler of the language the name of a text file that contains the list of - object directories. When this attribute is not declared, the text file is - not created. - - -.. _Package_Cross_Reference_Attributes: - -Package Cross_Reference Attributes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* **Default_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is a list of switches to be used when invoking - `gnatxref` for a source of the language, if there is no applicable - attribute Switches. - -* **Switches**: list, optional index, indexed, case-insensitive index, - others allowed - - Index is a source file name. Value is the list of switches to be used when - invoking `gnatxref` for the source. - - -.. only:: PRO or GPL - - .. _Package_Eliminate_Attributes: - - Package Eliminate Attributes - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - * **Default_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is a list of switches to be used when invoking - `gnatelim` for a source of the language, if there is no applicable - attribute Switches. - - * **Switches**: list, optional index, indexed, case-insensitive index, - others allowed - - Index is a source file name. Value is the list of switches to be used when - invoking `gnatelim` for the source. - -.. _Package_Finder_Attributes: - -Package Finder Attributes -^^^^^^^^^^^^^^^^^^^^^^^^^ - -* **Default_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is a list of switches to be used when invoking - `gnatfind` for a source of the language, if there is no applicable - attribute Switches. - -* **Switches**: list, optional index, indexed, case-insensitive index, - others allowed - - Index is a source file name. Value is the list of switches to be used when - invoking `gnatfind` for the source. - - -.. _Package_gnatls_Attributes: - -Package gnatls Attributes -^^^^^^^^^^^^^^^^^^^^^^^^^ - -* **Switches**: list - - Value is a list of switches to be used when invoking `gnatls`. - - -.. only:: PRO or GPL - - Package gnatstub Attributes - ^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - * **Default_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is a list of switches to be used when invoking - `gnatstub` for a source of the language, if there is no applicable - attribute Switches. - - * **Switches**: list, optional index, indexed, case-insensitive index, - others allowed - - Index is a source file name. Value is the list of switches to be used when - invoking `gnatstub` for the source. - - -.. _Package_IDE_Attributes: - -Package IDE Attributes -^^^^^^^^^^^^^^^^^^^^^^ - -* **Default_Switches**: list, indexed - - Index is the name of an external tool that the GNAT Programming System (GPS) - is supporting. Value is a list of switches to use when invoking that tool. - -* **Remote_Host**: single - - Value is a string that designates the remote host in a cross-compilation - environment, to be used for remote compilation and debugging. This attribute - should not be specified when running on the local machine. - -* **Program_Host**: single - - Value is a string that specifies the name of IP address of the embedded target - in a cross-compilation environment, on which the program should execute. - -* **Communication_Protocol**: single - - Value is the name of the protocol to use to communicate with the target - in a cross-compilation environment, for example `"wtx"` or - `"vxworks"`. - -* **Compiler_Command**: single, indexed, case-insensitive index - - Index is a language Name. Value is a string that denotes the command to be - used to invoke the compiler. For historical reasons, the value of - `Compiler_Command ("Ada")` is expected to be a reference to *gnatmake* or - *cross-gnatmake*. - -* **Debugger_Command**: single - - Value is a string that specifies the name of the debugger to be used, such as - gdb, powerpc-wrs-vxworks-gdb or gdb-4. - -* **gnatlist**: single - - Value is a string that specifies the name of the *gnatls* utility - to be used to retrieve information about the predefined path; for example, - `"gnatls"`, `"powerpc-wrs-vxworks-gnatls"`. - -* **VCS_Kind**: single - - Value is a string used to specify the Version Control System (VCS) to be used - for this project, for example "Subversion", "ClearCase". If the - value is set to "Auto", the IDE will try to detect the actual VCS used - on the list of supported ones. - -* **VCS_File_Check**: single - - Value is a string that specifies the command used by the VCS to check - the validity of a file, either when the user explicitly asks for a check, - or as a sanity check before doing the check-in. - -* **VCS_Log_Check**: single - - Value is a string that specifies the command used by the VCS to check - the validity of a log file. - -* **Documentation_Dir**: single - - Value is the directory used to generate the documentation of source code. - - -.. _Package_Install_Attributes: - -Package Install Attributes -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* **Artifacts**: list, indexed - - An array attribute to declare a set of files not part of the sources - to be installed. The array discriminant is the directory where the - file is to be installed. If a relative directory then Prefix (see - below) is prepended. Note also that if the same file name occurs - multiple time in the attribute list, the last one will be the one - installed. - -* **Prefix**: single - - Value is the install destination directory. - -* **Sources_Subdir**: single - - Value is the sources directory or subdirectory of Prefix. - -* **Exec_Subdir**: single - - Value is the executables directory or subdirectory of Prefix. - -* **Lib_Subdir**: single - - Value is library directory or subdirectory of Prefix. - -* **Project_Subdir**: single - - Value is the project directory or subdirectory of Prefix. - -* **Active**: single - - Indicates that the project is to be installed or not. Case-insensitive value - "false" means that the project is not to be installed, all other values mean - that the project is to be installed. - -* **Mode**: single - - Value is the installation mode, it is either **dev** (default) or **usage**. - -* **Install_Name**: single - - Specify the name to use for recording the installation. The default is - the project name without the extension. - - -.. _Package_Linker_Attributes: - -Package Linker Attributes -^^^^^^^^^^^^^^^^^^^^^^^^^ - -* **General** - - * **Required_Switches**: list - - Value is a list of switches that are required when invoking the linker to link - an executable. - - * **Default_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is a list of switches for the linker when - linking an executable for a main source of the language, when there is no - applicable Switches. - - * **Leading_Switches**: list, optional index, indexed, - case-insensitive index, others allowed - - Index is a source file name or a language name. Value is the list of switches - to be used at the beginning of the command line when invoking the linker to - build an executable for the source or for its language. - - * **Switches**: list, optional index, indexed, case-insensitive index, - others allowed - - Index is a source file name or a language name. Value is the list of switches - to be used when invoking the linker to build an executable for the source or - for its language. - - * **Trailing_Switches**: list, optional index, indexed, - case-insensitive index, others allowed - - Index is a source file name or a language name. Value is the list of switches - to be used at the end of the command line when invoking the linker to - build an executable for the source or for its language. These switches may - override the Required_Switches. - - * **Linker_Options**: list - - Value is a list of switches/options that are to be added when linking an - executable from a project importing the current project directly or indirectly. - Linker_Options are not used when linking an executable from the current - project. - - * **Map_File_Option**: single - - Value is the switch to specify the map file name that the linker needs to - create. - -* **Configuration - Linking** - - * **Driver**: single - - Value is the name of the linker executable. - -* **Configuration - Response Files** - - * **Max_Command_Line_Length**: single - - Value is the maximum number of character in the command line when invoking - the linker to link an executable. - - * **Response_File_Format**: single - - Indicates the kind of response file to create when the length of the linking - command line is too large. Only authorized case-insensitive values are "none", - "gnu", "object_list", "gcc_gnu", "gcc_option_list" and "gcc_object_list". - - * **Response_File_Switches**: list - - Value is the list of switches to specify a response file to the linker. - - - -.. only PRO or GPL - - .. _Package_Metrics_Attribute: - - Package Metrics Attribute - ^^^^^^^^^^^^^^^^^^^^^^^^^ - - * **Default_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is a list of switches to be used when invoking - `gnatmetric` for a source of the language, if there is no applicable - attribute Switches. - - * **Switches**: list, optional index, indexed, case-insensitive index, - others allowed - - Index is a source file name. Value is the list of switches to be used when - invoking `gnatmetric` for the source. - - -.. _Package_Naming_Attributes: - -Package Naming Attributes -^^^^^^^^^^^^^^^^^^^^^^^^^ - -* **Specification_Suffix**: single, indexed, case-insensitive index - - Equivalent to attribute Spec_Suffix. - -* **Spec_Suffix**: single, indexed, case-insensitive index - - Index is a language name. Value is the extension of file names for specs of - the language. - -* **Implementation_Suffix**: single, indexed, case-insensitive index - - Equivalent to attribute Body_Suffix. - -* **Body_Suffix**: single, indexed, case-insensitive index - - Index is a language name. Value is the extension of file names for bodies of - the language. - -* **Separate_Suffix**: single - - Value is the extension of file names for subunits of Ada. - -* **Casing**: single - - Indicates the casing of sources of the Ada language. Only authorized - case-insensitive values are "lowercase", "uppercase" and "mixedcase". - -* **Dot_Replacement**: single - - Value is the string that replace the dot of unit names in the source file names - of the Ada language. - -* **Specification**: single, optional index, indexed, - case-insensitive index - - Equivalent to attribute Spec. - -* **Spec**: single, optional index, indexed, case-insensitive index - - Index is a unit name. Value is the file name of the spec of the unit. - -* **Implementation**: single, optional index, indexed, - case-insensitive index - - Equivalent to attribute Body. - -* **Body**: single, optional index, indexed, case-insensitive index - - Index is a unit name. Value is the file name of the body of the unit. - -* **Specification_Exceptions**: list, indexed, case-insensitive index - - Index is a language name. Value is a list of specs for the language that do not - necessarily follow the naming scheme for the language and that may or may not - be found in the source directories of the project. - -* **Implementation_Exceptions**: list, indexed, case-insensitive index - - Index is a language name. Value is a list of bodies for the language that do not - necessarily follow the naming scheme for the language and that may or may not - be found in the source directories of the project. - - -.. only:: PRO or GPL - - .. _Package_Pretty_Printer_Attributes: - - Package Pretty_Printer Attributes - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - * **Default_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is a list of switches to be used when invoking - `gnatpp` for a source of the language, if there is no applicable - attribute Switches. - - * **Switches**: list, optional index, indexed, case-insensitive index, - others allowed - - Index is a source file name. Value is the list of switches to be used when - invoking `gnatpp` for the source. - - -.. _Package_Remote_Attributes: - -Package Remote Attributes -^^^^^^^^^^^^^^^^^^^^^^^^^ - -* **Included_Patterns**: list - - If this attribute is defined it sets the patterns to - synchronized from the master to the slaves. It is exclusive - with Excluded_Patterns, that is it is an error to define - both. - -* **Included_Artifact_Patterns**: list - - If this attribute is defined it sets the patterns of compilation - artifacts to synchronized from the slaves to the build master. - This attribute replace the default hard-coded patterns. - -* **Excluded_Patterns**: list - - Set of patterns to ignore when synchronizing sources from the build - master to the slaves. A set of predefined patterns are supported - (e.g. \*.o, \*.ali, \*.exe, etc.), this attributes make it possible to - add some more patterns. - -* **Root_Dir**: single - - Value is the root directory used by the slave machines. - - -.. _Package_Stack_Attributes: - -Package Stack Attributes -^^^^^^^^^^^^^^^^^^^^^^^^ - -* **Switches**: list - - Value is the list of switches to be used when invoking `gnatstack`. - - -Package Synchronize Attributes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* **Default_Switches**: list, indexed, case-insensitive index - - Index is a language name. Value is a list of switches to be used when invoking - `gnatsync` for a source of the language, if there is no applicable - attribute Switches. - -* **Switches**: list, optional index, indexed, case-insensitive index, - others allowed - - Index is a source file name. Value is the list of switches to be used when - invoking `gnatsync` for the source. diff --git a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst index 792d698c52f..1d22d17e935 100644 --- a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst +++ b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst @@ -19,6 +19,9 @@ This chapter describes a number of utility programs: * :ref:`The_Body_Stub_Generator_gnatstub` * :ref:`The_Unit_Test_Generator_gnattest` + It also describes how several of these tools can be used in conjunction + with project files: :ref:`Using_Project_Files_with_GNAT_Tools` + .. only:: FSF * :ref:`The_File_Cleanup_Utility_gnatclean` @@ -629,7 +632,8 @@ The following switches are available for *gnatxref*: .. index:: -pFILE (gnatxref) :samp:`p{FILE}` - Specify a project file to use :ref:`GNAT_Project_Manager`. + Specify a project file to use (see the *GNAT_Project_Manager* + chapter in the *GPRbuild User's Guide*). If you need to use the :file:`.gpr` project files, you should use gnatxref through the GNAT driver (*gnat xref -Pproject*). @@ -832,7 +836,8 @@ The following switches are available: .. index:: -pFILE (gnatfind) :samp:`p{FILE}` - Specify a project file (:ref:`GNAT_Project_Manager`) to use. + Specify a project file (see the *GNAT_Project_Manager* chapter in the + *GPRbuild User's Guide*). By default, `gnatxref` and `gnatfind` will try to locate a project file in the current directory. @@ -1379,6 +1384,11 @@ Alternatively, you may run the script using the following command line: The *gnat2xml* tool is an ASIS-based utility that converts Ada source code into XML. + *gnat2xml* is a project-aware tool + (see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of + the project-related switches). The project file package that can specify + *gnat2xml* switches is named ``gnat2xml``. + .. _Switches_for_*gnat2xml*: Switches for *gnat2xml* @@ -1823,15 +1833,12 @@ Alternatively, you may run the script using the following command line: The *gnatcheck* tool is an ASIS-based utility that checks properties of Ada source files according to a given set of semantic rules. - In order to check compliance with a given rule, *gnatcheck* has to - semantically analyze the Ada sources. - Therefore, checks can only be performed on - legal Ada units. Moreover, when a unit depends semantically upon units located - outside the current directory, the source search path has to be provided when - calling *gnatcheck*, either through a specified project file or - through *gnatcheck* switches. + *gnatcheck* is a project-aware tool + (see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of + the project-related switches). The project file package that can specify + *gnatcheck* switches is named ``Check``. - For full details, refer to :title:`GNATcheck Reference Manual`. + For full details, plese refer to :title:`GNATcheck Reference Manual`. @@ -1851,6 +1858,11 @@ Alternatively, you may run the script using the following command line: metrics data as output. Various switches control which metrics are computed and output. + *gnatmetric* is a project-aware tool + (see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of + the project-related switches). The project file package that can specify + *gnatmetric* switches is named ``Metrics``. + To compute program metrics, *gnatmetric* invokes the Ada compiler and generates and uses the ASIS tree for the input source; thus the input must be legal Ada code, and the tool should have all the @@ -2095,71 +2107,71 @@ Alternatively, you may run the script using the following command line: .. index:: --no-lines (gnatmetric) - :samp:`-lines-all` + :samp:`--lines-all` Report all the line metrics - :samp:`-no-lines-all` + :samp:`--no-lines-all` Do not report any of line metrics - :samp:`-lines` + :samp:`--lines` Report the number of all lines - :samp:`-no-lines` + :samp:`--no-lines` Do not report the number of all lines - :samp:`-lines-code` + :samp:`--lines-code` Report the number of code lines - :samp:`-no-lines-code` + :samp:`--no-lines-code` Do not report the number of code lines - :samp:`-lines-comment` + :samp:`--lines-comment` Report the number of comment lines - :samp:`-no-lines-comment` + :samp:`--no-lines-comment` Do not report the number of comment lines - :samp:`-lines-eol-comment` + :samp:`--lines-eol-comment` Report the number of code lines containing end-of-line comments - :samp:`-no-lines-eol-comment` + :samp:`--no-lines-eol-comment` Do not report the number of code lines containing end-of-line comments - :samp:`-lines-ratio` + :samp:`--lines-ratio` Report the comment percentage in the program text - :samp:`-no-lines-ratio` + :samp:`--no-lines-ratio` Do not report the comment percentage in the program text - :samp:`-lines-blank` + :samp:`--lines-blank` Report the number of blank lines - :samp:`-no-lines-blank` + :samp:`--no-lines-blank` Do not report the number of blank lines - :samp:`-lines-average` + :samp:`--lines-average` Report the average number of code lines in subprogram bodies, task bodies, entry bodies and statement sequences in package bodies. The metric is computed and reported for the whole set of processed Ada sources only. - :samp:`-no-lines-average` + :samp:`--no-lines-average` Do not report the average number of code lines in subprogram bodies, task bodies, entry bodies and statement sequences in package bodies. @@ -2204,6 +2216,15 @@ Alternatively, you may run the script using the following command line: maximum nesting level in the GNAT built-in style checks (see :ref:`Style_Checking`) + * *Number of formal parameters* + Number of formal parameters of a subprogram; if a subprogram does have + parameters, then numbers of "in", "out" and "in out" parameters are also + reported. This metric is reported for subprogram specifications and for + subprogram instantiations. For subprogram bodies, expression functions + and null procedures this metric is reported if the construct acts as a + subprogram declaration but is not a completion of previous declaration. + This metric is not reported for generic and formal subprograms. + For the outermost unit in the file, *gnatmetric* additionally computes the following metrics: @@ -2263,77 +2284,84 @@ Alternatively, you may run the script using the following command line: .. index:: --no-syntax (gnatmetric) - :samp:`-syntax-all` + :samp:`--syntax-all` Report all the syntax metrics - :samp:`-no-syntax-all` + :samp:`--no-syntax-all` Do not report any of syntax metrics - :samp:`-declarations` + :samp:`--declarations` Report the total number of declarations - :samp:`-no-declarations` + :samp:`--no-declarations` Do not report the total number of declarations - :samp:`-statements` + :samp:`--statements` Report the total number of statements - :samp:`-no-statements` + :samp:`--no-statements` Do not report the total number of statements - :samp:`-public-subprograms` + :samp:`--public-subprograms` Report the number of public subprograms in a compilation unit - :samp:`-no-public-subprograms` + :samp:`--no-public-subprograms` Do not report the number of public subprograms in a compilation unit - :samp:`-all-subprograms` + :samp:`--all-subprograms` Report the number of all the subprograms in a compilation unit - :samp:`-no-all-subprograms` + :samp:`--no-all-subprograms` Do not report the number of all the subprograms in a compilation unit - :samp:`-public-types` + :samp:`--public-types` Report the number of public types in a compilation unit - :samp:`-no-public-types` + :samp:`--no-public-types` Do not report the number of public types in a compilation unit - :samp:`-all-types` + :samp:`--all-types` Report the number of all the types in a compilation unit - :samp:`-no-all-types` + :samp:`--no-all-types` Do not report the number of all the types in a compilation unit - :samp:`-unit-nesting` + :samp:`--unit-nesting` Report the maximal program unit nesting level - :samp:`-no-unit-nesting` + :samp:`--no-unit-nesting` Do not report the maximal program unit nesting level - :samp:`-construct-nesting` + :samp:`--construct-nesting` Report the maximal construct nesting level - :samp:`-no-construct-nesting` + :samp:`--no-construct-nesting` Do not report the maximal construct nesting level + :samp:`--param-number` + Report the number of subprogram parameters + + + :samp:`--no-param-number` + Do not report the number of subprogram parameters + .. _Complexity_Metrics_Control: @@ -2420,31 +2448,31 @@ Alternatively, you may run the script using the following command line: .. index:: --no-complexity (gnatmetric) - :samp:`-complexity-all` + :samp:`--complexity-all` Report all the complexity metrics - :samp:`-no-complexity-all` + :samp:`--no-complexity-all` Do not report any of complexity metrics - :samp:`-complexity-cyclomatic` + :samp:`--complexity-cyclomatic` Report the McCabe Cyclomatic Complexity - :samp:`-no-complexity-cyclomatic` + :samp:`--no-complexity-cyclomatic` Do not report the McCabe Cyclomatic Complexity - :samp:`-complexity-essential` + :samp:`--complexity-essential` Report the Essential Complexity - :samp:`-no-complexity-essential` + :samp:`--no-complexity-essential` Do not report the Essential Complexity - :samp:`-loop-nesting` + :samp:`--loop-nesting` Report maximal loop nesting level @@ -2452,14 +2480,14 @@ Alternatively, you may run the script using the following command line: Do not report maximal loop nesting level - :samp:`-complexity-average` + :samp:`--complexity-average` Report the average McCabe Cyclomatic Complexity for all the subprogram bodies, task bodies, entry bodies and statement sequences in package bodies. The metric is computed and reported for whole set of processed Ada sources only. - :samp:`-no-complexity-average` + :samp:`--no-complexity-average` Do not report the average McCabe Cyclomatic Complexity for all the subprogram bodies, task bodies, entry bodies and statement sequences in package bodies @@ -2473,11 +2501,11 @@ Alternatively, you may run the script using the following command line: .. index:: --no-static-loop (gnatmetric) - :samp:`-no-static-loop` + :samp:`--no-static-loop` Do not consider static loops when computing cyclomatic complexity - :samp:`-extra-exit-points` + :samp:`--extra-exit-points` Report the extra exit points for subprogram bodies. As an exit point, this metric counts `return` statements and raise statements in case when the raised exception is not handled in the same body. In case of a function this @@ -2485,7 +2513,7 @@ Alternatively, you may run the script using the following command line: must contain at least one `return` statement. - :samp:`-no-extra-exit-points` + :samp:`--no-extra-exit-points` Do not report the extra exit points for subprogram bodies @@ -2678,39 +2706,39 @@ Alternatively, you may run the script using the following command line: .. index:: --unit-coupling (gnatmetric) .. index:: --control-coupling (gnatmetric) - :samp:`-coupling-all` + :samp:`--coupling-all` Report all the coupling metrics - :samp:`-tagged-coupling-out` + :samp:`--tagged-coupling-out` Report tagged (class) fan-out coupling - :samp:`-tagged-coupling-in` + :samp:`--tagged-coupling-in` Report tagged (class) fan-in coupling - :samp:`-hierarchy-coupling-out` + :samp:`--hierarchy-coupling-out` Report hierarchy (category) fan-out coupling - :samp:`-hierarchy-coupling-in` + :samp:`--hierarchy-coupling-in` Report hierarchy (category) fan-in coupling - :samp:`-unit-coupling-out` + :samp:`--unit-coupling-out` Report unit fan-out coupling - :samp:`-unit-coupling-in` + :samp:`--unit-coupling-in` Report unit fan-in coupling - :samp:`-control-coupling-out` + :samp:`--control-coupling-out` Report control fan-out coupling - :samp:`-control-coupling-in` + :samp:`--control-coupling-in` Report control fan-in coupling @@ -2724,13 +2752,13 @@ Alternatively, you may run the script using the following command line: .. index:: --version (gnatmetric) - :samp:`-version` + :samp:`--version` Display Copyright and version, then exit disregarding all other options. .. index:: --help (gnatmetric) - :samp:`-help` + :samp:`--help` Display usage, then exit disregarding all other options. @@ -2768,14 +2796,14 @@ Alternatively, you may run the script using the following command line: .. index:: --RTS (gnatmetric) - :samp:`-RTS={rts-path}` + :samp:`--RTS={rts-path}` Specifies the default location of the runtime library. Same meaning as the equivalent *gnatmake* flag (see :ref:`Switches_for_gnatmake`). .. index:: --subdirs=dir (gnatmetric) - :samp:`-subdirs={dir}` + :samp:`--subdirs={dir}` Use the specified subdirectory of the project objects file (or of the project file directory if the project does not specify an object directory) for tool output files. Has no effect if no project is specified as @@ -2784,7 +2812,7 @@ Alternatively, you may run the script using the following command line: .. index:: --no_objects_dir (gnatmetric) - :samp:`-no_objects_dir` + :samp:`--no_objects_dir` Place all the result files into the current directory instead of project objects directory. This corresponds to the *gnatcheck* behavior when it is called with the project file from the @@ -2852,6 +2880,11 @@ Alternatively, you may run the script using the following command line: You can specify various style directives via switches; e.g., identifier case conventions, rules of indentation, and comment layout. + *gnatpp* is a project-aware tool + (see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of + the project-related switches). The project file package that can specify + *gnatpp* switches is named ``Pretty_Printer``. + To produce a reformatted file, *gnatpp* invokes the Ada compiler and generates and uses the ASIS tree for the input source; thus the input must be legal Ada code, and the tool should have all the @@ -3143,6 +3176,13 @@ Alternatively, you may run the script using the following command line: :samp:`--comments-only` Format just the comments. + .. index:: --no-end-id (gnatpp) + + + :samp:`--no-end-id` + Do not insert the name of a unit after `end`; leave whatever comes + after `end`, if anything, alone. + .. index:: --no-separate-is (gnatpp) @@ -3849,6 +3889,15 @@ Alternatively, you may run the script using the following command line: for library unit declarations, and empty but compilable subunit for body stubs. + *gnatstub* is a project-aware tool. + (See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of + the project-related switches but note that *gnatstub* does not support + the :samp:`-U`, :samp:`-U {main_unit}`, :samp:`--subdirs={dir}`, or + :samp:`--no_objects_dir` switches.) + The project file package that can specify + *gnatstub* switches is named ``gnatstub``. + + To create a body or a subunit, *gnatstub* invokes the Ada compiler and generates and uses the ASIS tree for the input source; thus the input must be legal Ada code, and the tool should have all the @@ -4336,9 +4385,10 @@ Alternatively, you may run the script using the following command line: .. index:: --separate-drivers (gnattest) - :samp:`--separate-drivers` - Generates a separate test driver for each test, rather than a single - executable incorporating all tests. + :samp:`--separate-drivers[={val}]` + Generates a separate test driver for each test or unit under test, rather + than a single executable incorporating all tests. `val` can be "unit" or + "test", or may be omitted, which defaults to "unit". .. index:: --stub (gnattest) @@ -4401,6 +4451,16 @@ Alternatively, you may run the script using the following command line: placed accordingly. + .. index:: --exclude-from-stubbing (gnattest) + + :samp:`--exclude-from-stubbing={filename}` + Disables stubbing of units listed in `filename`. The file should contain + corresponding spec files, one per line. + + :samp:`--exclude-from-stubbing:{unit}={filename}` + Same as above, but corresponding units will not be stubbed only when testing + specified `unit`. + .. index:: --validate-type-extensions (gnattest) :samp:`--validate-type-extensions` @@ -4531,6 +4591,15 @@ Alternatively, you may run the script using the following command line: specified by ``--skeleton-default`` option. The value of this attribute should be either ``pass`` or ``fail``. + * ``Default_Stub_Exclusion_List`` + is used to specify the file with list of units whose bodies should not + be stubbed, otherwise specified by ``--exclude-from-stubbing=filename``. + + * ``Stub_Exclusion_List ("unit")`` + is used to specify the file with list of units whose bodies should not + be stubbed when testing "unit", otherwise specified by + ``--exclude-from-stubbing:unit=filename``. + Each of those attributes can be overridden from the command line if needed. Other *gnattest* switches can also be passed via the project file as an attribute list called *Gnattest_Switches*. @@ -4877,12 +4946,12 @@ Alternatively, you may run the script using the following command line: By default, *gnattest* generates a monolithic test driver that aggregates the individual tests into a single executable. It is also possible - to generate separate executables for each test, by passing the switch - ``--separate-drivers``. This approach scales better for large testing - campaigns, especially involving target architectures with limited resources - typical for embedded development. It can also provide a major performance - benefit on multi-core systems by allowing simultaneous execution of multiple - tests. + to generate separate executables for each test or each unit under test, by + passing the switch ``--separate-drivers`` with corresponding parameter. This + approach scales better for large testing campaigns, especially involving target + architectures with limited resources typical for embedded development. It can + also provide a major performance benefit on multi-core systems by allowing + simultaneous execution of multiple tests. *gnattest* can take charge of executing the individual tests; for this, instead of passing a project file, a text file containing the list of @@ -4923,7 +4992,8 @@ Alternatively, you may run the script using the following command line: Due to the nature of stubbing process, this mode implies the switch ``--separate-drivers``, i.e. an individual test driver (with the - corresponding hierarchy of extending projects) is generated for each test. + corresponding hierarchy of extending projects) is generated for each unit under + test. .. note:: @@ -4965,5 +5035,90 @@ Alternatively, you may run the script using the following command line: * pragma *No_Secondary_Stack* is not supported; * if pragmas for interfacing with foreign languages are used, manual adjustments might be necessary to make the test harness compilable; - * use of elaboration control pragmas may result in elaboration circularities - in the generated harness. + * use of some constructs, such as elaboration-control pragmas, Type_Invariant + aspects, and complex variable initializations that use Subprogram'Access, + may result in elaboration circularities in the generated harness. + +.. only:: PRO or GPL + + .. _Using_Project_Files_with_GNAT_Tools: + + Using Project Files with GNAT Tools + =================================== + + This section describes how project files can be used in conjunction + with a number of GNAT tools. + For a comprehensive description of project files and the overall + GNAT Project Manager facility, please refer to the + *GNAT Project Manager* chapter in the + *GPRbuild and GPR Companion Tools User's Guide*. + + .. index:: Project-aware tool + + If a tool can take a project file as an option and extract the needed + information, such a tool is called a *project-aware* tool. + + .. _Switches_Related_to_Project_Files: + + Switches Related to Project Files + --------------------------------- + + The following switches are used by the project-aware GNAT tools: + + :samp:`-P{project_file}` + Indicates the name of the project file whose source files are to + be processed. The exact set of sources depends on other options + specified, see below. + + :samp:`-U` + If a project file is supplied, say for project ``proj``, + but no sources are specified for ``proj`` (either by a + project attribute or through a tool option that provides a list + of the files to be used), process all the source files + from projects imported either directly or indirectly by ``proj``. + Otherwise this option has no effect. + + :samp:`-U {main_unit}` + Similar to :samp:`-U`, but if no sources are specified then + process only those source files for units in the closure of + `main_unit`. + + :samp:`-X{name}={val}` + Indicates that the external variable ``name`` in the project has the + value ``val``. Has no effect if no project has been specified. + + :samp:`--subdirs={dir}` + Use the `dir` subdirectory of the project's object directory (or the `dir` + subdirectory of the project file directory if the project does not specify + an object directory) for tool output files. Has no effect if no project + has been specified or if :samp:`--no_objects_dir` is specified. + + :samp:`--no_objects_dir` + Place all the result files into the current directory (i.e., the directory + from which the tool invocation command is issued) instead of the project's + object directory. Has no effect if no project has been specified. + + :samp:`-eL` + Follow all symbolic links when processing project files. + + If a project file is specified and there is neither a :samp:`-U` option, + nor a :samp:`-U {main_unit}` option, nor some other explicit option to + specify the source files, then the sources to be processed are the + immediate sources of the specified project (i.e., the source files directly + defined by that project, either implicitly by residing in the project + source directories, or explicitly through any of the source-related + attributes). + + .. _Tool-specific_packages_in_project files: + + Tool-specific packages in project files + --------------------------------------- + + Each project-aware tool may have a corresponding package in a project file; + the package names are given elsewhere in this manual, in the sections that describe + the respective tools. + + A tool-specific package in a project file may define the ``Default_Switches`` + attribute indexed by "ada" (as language name). The value of this attribute + is a list of switches that will be supplied at tool invocation. + Project-specific switches cannot be specified through this attribute. diff --git a/gcc/ada/doc/gnat_ugn/platform_specific_information.rst b/gcc/ada/doc/gnat_ugn/platform_specific_information.rst index 694e37baeed..d6f36c29058 100644 --- a/gcc/ada/doc/gnat_ugn/platform_specific_information.rst +++ b/gcc/ada/doc/gnat_ugn/platform_specific_information.rst @@ -156,6 +156,31 @@ For example on x86-linux:: -- | -- +--- adalib +.. only:: html or latex + + .. image:: rtlibrary-structure.png + +.. only:: not (html or latex) + + :: + + $(target-dir) + __/ / \ \___ + _______/ / \ \_________________ + / / \ \ + / / \ \ + ADAINCLUDE ADALIB rts-native rts-sjlj + : : / \ / \ + : : / \ / \ + : : / \ / \ + : : / \ / \ + +-------------> adainclude adalib adainclude adalib + : ^ + : : + +---------------------+ + + Run-Time Library Directory Structure + (Upper-case names and dotted/dashed arrows represent soft links) If the *rts-sjlj* library is to be selected on a permanent basis, these soft links can be modified with the following commands: @@ -486,7 +511,58 @@ file will be created. This is particularly useful in networked environments where you may not have write access to some directories. +Disabling Command Line Argument Expansion +----------------------------------------- + +.. index:: Command Line Argument Expansion + +By default, an executable compiled for the **Windows** platform will do +the following postprocessing on the arguments passed on the command +line: + +* If the argument contains the characters ``*`` and/or ``?``, then + file expansion will be attempted. For example, if the current directory + contains :file:`a.txt` and :file:`b.txt`, then when calling:: + + $ my_ada_program *.txt + + The following arguments will effectively be passed to the main program + (for example when using ``Ada.Command_Line.Argument``):: + + Ada.Command_Line.Argument (1) -> "a.txt" + Ada.Command_Line.Argument (2) -> "b.txt" + +* Filename expansion can be disabled for a given argument by using single + quotes. Thus, calling:: + $ my_ada_program '*.txt' + + will result in:: + + Ada.Command_Line.Argument (1) -> "*.txt" + +Note that if the program is launched from a shell such as **Cygwin** **Bash** +then quote removal might be performed by the shell. + +In some contexts it might be useful to disable this feature (for example if +the program performs its own argument expansion). In order to do this, a C +symbol needs to be defined and set to ``0``. You can do this by +adding the following code fragment in one of your **Ada** units: + +.. code-block:: ada + + Do_Argv_Expansion : Integer := 0; + pragma Export (C, Do_Argv_Expansion, "__gnat_do_argv_expansion"); + +The results of previous examples will be respectively:: + + Ada.Command_Line.Argument (1) -> "*.txt" + +and:: + + Ada.Command_Line.Argument (1) -> "'*.txt'" + + .. _Mixed-Language_Programming_on_Windows: Mixed-Language Programming on Windows @@ -1033,7 +1109,8 @@ Building DLLs with GNAT Project files .. index:: DLLs, building There is nothing specific to Windows in the build process. -:ref:`Library_Projects`. +See the *Library Projects* section in the *GNAT Project Manager* +chapter of the *GPRbuild User's Guide*. Due to a system limitation, it is not possible under Windows to create threads when inside the `DllMain` routine which is used for auto-initialization @@ -1149,7 +1226,9 @@ Note that a relocatable DLL stripped using the `strip` binutils tool will not be relocatable anymore. To build a DLL without debug information pass `-largs -s` to `gnatdll`. This restriction does not apply to a DLL built using a Library Project. -See :ref:`Library_Projects`. +See the *Library Projects* section in the *GNAT Project Manager* +chapter of the *GPRbuild User's Guide*. + .. Limitations_When_Using_Ada_DLLs_from Ada: diff --git a/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst b/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst index 0304a536411..32d3417e0ff 100644 --- a/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst +++ b/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst @@ -872,7 +872,7 @@ File Name Krunching with `gnatkr` .. index:: ! gnatkr -This chapter discusses the method used by the compiler to shorten +This section discusses the method used by the compiler to shorten the default file names chosen for Ada units so that they do not exceed the maximum length permitted. It also describes the `gnatkr` utility that can be used to determine the result of @@ -1052,7 +1052,7 @@ Renaming Files with `gnatchop` .. index:: ! gnatchop -This chapter discusses how to handle files with multiple units by using +This section discusses how to handle files with multiple units by using the `gnatchop` utility. This utility is also useful in renaming files to meet the standard GNAT default file naming conventions. @@ -1550,8 +1550,10 @@ depend on a file that no longer exists. Such tools include *gprbuild*, *gnatmake*, and *gnatcheck*. If you are using project file, a separate mechanism is provided using -project attributes, see :ref:`Specifying_Configuration_Pragmas` for more -details. +project attributes. + +.. --Comment: + See :ref:`Specifying_Configuration_Pragmas` for more details. .. _Generating_Object_Files: @@ -1788,10 +1790,10 @@ GNAT and Libraries .. index:: Library building and using -This chapter describes how to build and use libraries with GNAT, and also shows +This section describes how to build and use libraries with GNAT, and also shows how to recompile the GNAT run-time library. You should be familiar with the -Project Manager facility (:ref:`GNAT_Project_Manager`) before reading this -chapter. +Project Manager facility (see the *GNAT_Project_Manager* chapter of the +*GPRbuild User's Guide*) before reading this chapter. .. _Introduction_to_Libraries_in_GNAT: @@ -1849,7 +1851,8 @@ Building a library The easiest way to build a library is to use the Project Manager, which supports a special type of project called a *Library Project* -(see :ref:`Library_Projects`). +(see the *Library Projects* section in the *GNAT Project Manager* +chapter of the *GPRbuild User's Guide*). A project is considered a library project, when two project-level attributes are defined in it: `Library_Name` and `Library_Dir`. In order to @@ -1961,7 +1964,8 @@ Installing a library .. index:: GPR_PROJECT_PATH If you use project files, library installation is part of the library build -process (:ref:`Installing_a_library_with_project_files`). +process (see the *Installing a Library with Project Files* section of the +*GNAT Project Manager* chapter of the *GPRbuild User's Guide*). When project files are not an option, it is also possible, but not recommended, to install the library so that the sources needed to use the library are on the @@ -2137,11 +2141,13 @@ Building a Stand-alone Library ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ GNAT's Project facility provides a simple way of building and installing -stand-alone libraries; see :ref:`Stand-alone_Library_Projects`. +stand-alone libraries; see the *Stand-alone Library Projects* section +in the *GNAT Project Manager* chapter of the *GPRbuild User's Guide*. To be a Stand-alone Library Project, in addition to the two attributes that make a project a Library Project (`Library_Name` and -`Library_Dir`; see :ref:`Library_Projects`), the attribute -`Library_Interface` must be defined. For example: +`Library_Dir`; see the *Library Projects* section in the +*GNAT Project Manager* chapter of the *GPRbuild User's Guide*), +the attribute `Library_Interface` must be defined. For example: .. code-block:: gpr diff --git a/gcc/ada/doc/gnat_ugn/tools_supporting_project_files.rst b/gcc/ada/doc/gnat_ugn/tools_supporting_project_files.rst deleted file mode 100644 index 7360acb0b8a..00000000000 --- a/gcc/ada/doc/gnat_ugn/tools_supporting_project_files.rst +++ /dev/null @@ -1,745 +0,0 @@ -.. _Tools_Supporting_Project_Files: - -Tools Supporting Project Files -============================== - -This section describes how project files can be used in conjunction with a number of -GNAT tools. - -.. _gnatmake_and_Project_Files: - -gnatmake and Project Files --------------------------- - -This section covers several topics related to *gnatmake* and -project files: defining switches for *gnatmake* -and for the tools that it invokes; specifying configuration pragmas; -the use of the `Main` attribute; building and rebuilding library project -files. - -.. _Switches_Related_to_Project_Files: - -Switches Related to Project Files -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following switches are used by GNAT tools that support project files: - - - .. index:: -P (any project-aware tool) - -:samp:`-P{project}` - Indicates the name of a project file. This project file will be parsed with - the verbosity indicated by *-vP*x**, - if any, and using the external references indicated - by *-X* switches, if any. - There may zero, one or more spaces between *-P* and `project`. - - There must be only one *-P* switch on the command line. - - Since the Project Manager parses the project file only after all the switches - on the command line are checked, the order of the switches - *-P*, - *-vP*x** - or *-X* is not significant. - - - .. index:: -X (any project-aware tool) - -:samp:`-X{name}={value}` - Indicates that external variable `name` has the value `value`. - The Project Manager will use this value for occurrences of - `external(name)` when parsing the project file. - - If `name` or `value` includes a space, then `name=value` should be - put between quotes. - - :: - - -XOS=NT - -X"user=John Doe" - - Several *-X* switches can be used simultaneously. - If several *-X* switches specify the same - `name`, only the last one is used. - - An external variable specified with a *-X* switch - takes precedence over the value of the same name in the environment. - - - .. index:: -vP (any project-aware tool) - -:samp:`-vP{x}` - Indicates the verbosity of the parsing of GNAT project files. - - *-vP0* means Default; - *-vP1* means Medium; - *-vP2* means High. - - The default is Default: no output for syntactically correct - project files. - If several *-vP*x** switches are present, - only the last one is used. - - - .. index:: -aP (any project-aware tool) - -:samp:`-aP{dir}` - Add directory `dir` at the beginning of the project search path, in order, - after the current working directory. - - - .. index:: -eL (any project-aware tool) - -:samp:`-eL` - Follow all symbolic links when processing project files. - - - .. index:: --subdirs= (gnatmake and gnatclean) - -:samp:`--subdirs={subdir}` - This switch is recognized by *gnatmake* and *gnatclean*. It - indicate that the real directories (except the source directories) are the - subdirectories `subdir` of the directories specified in the project files. - This applies in particular to object directories, library directories and - exec directories. If the subdirectories do not exist, they are created - automatically. - - -.. _Switches_and_Project_Files: - -Switches and Project Files -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -For each of the packages `Builder`, `Compiler`, `Binder`, and -`Linker`, you can specify a `Default_Switches` -attribute, a `Switches` attribute, or both; -as their names imply, these switch-related -attributes affect the switches that are used for each of these GNAT -components when -*gnatmake* is invoked. As will be explained below, these -component-specific switches precede -the switches provided on the *gnatmake* command line. - -The `Default_Switches` attribute is an attribute -indexed by language name (case insensitive) whose value is a string list. -For example: - - .. code-block:: gpr - - package Compiler is - for Default_Switches ("Ada") - use ("-gnaty", - "-v"); - end Compiler; - -The `Switches` attribute is indexed on a file name (which may or may -not be case sensitive, depending -on the operating system) whose value is a string list. For example: - - .. code-block:: gpr - - package Builder is - for Switches ("main1.adb") - use ("-O2"); - for Switches ("main2.adb") - use ("-g"); - end Builder; - -For the `Builder` package, the file names must designate source files -for main subprograms. For the `Binder` and `Linker` packages, the -file names must designate :file:`ALI` or source files for main subprograms. -In each case just the file name without an explicit extension is acceptable. - -For each tool used in a program build (*gnatmake*, the compiler, the -binder, and the linker), the corresponding package @dfn{contributes} a set of -switches for each file on which the tool is invoked, based on the -switch-related attributes defined in the package. -In particular, the switches -that each of these packages contributes for a given file `f` comprise: - -* the value of attribute `Switches (`f`)`, - if it is specified in the package for the given file, -* otherwise, the value of `Default_Switches ("Ada")`, - if it is specified in the package. - -If neither of these attributes is defined in the package, then the package does -not contribute any switches for the given file. - -When *gnatmake* is invoked on a file, the switches comprise -two sets, in the following order: those contributed for the file -by the `Builder` package; -and the switches passed on the command line. - -When *gnatmake* invokes a tool (compiler, binder, linker) on a file, -the switches passed to the tool comprise three sets, -in the following order: - -* the applicable switches contributed for the file - by the `Builder` package in the project file supplied on the command line; - -* those contributed for the file by the package (in the relevant project file -- - see below) corresponding to the tool; and - -* the applicable switches passed on the command line. - -The term *applicable switches* reflects the fact that -*gnatmake* switches may or may not be passed to individual -tools, depending on the individual switch. - -*gnatmake* may invoke the compiler on source files from different -projects. The Project Manager will use the appropriate project file to -determine the `Compiler` package for each source file being compiled. -Likewise for the `Binder` and `Linker` packages. - -As an example, consider the following package in a project file: - - - .. code-block:: gpr - - project Proj1 is - package Compiler is - for Default_Switches ("Ada") - use ("-g"); - for Switches ("a.adb") - use ("-O1"); - for Switches ("b.adb") - use ("-O2", - "-gnaty"); - end Compiler; - end Proj1; - -If *gnatmake* is invoked with this project file, and it needs to -compile, say, the files :file:`a.adb`, :file:`b.adb`, and :file:`c.adb`, then -:file:`a.adb` will be compiled with the switch *-O1*, -:file:`b.adb` with switches *-O2* and *-gnaty*, -and :file:`c.adb` with *-g*. - -The following example illustrates the ordering of the switches -contributed by different packages: - - .. code-block:: gpr - - project Proj2 is - package Builder is - for Switches ("main.adb") - use ("-g", - "-O1", - "-f"); - end Builder; - - package Compiler is - for Switches ("main.adb") - use ("-O2"); - end Compiler; - end Proj2; - -If you issue the command: - - :: - - $ gnatmake -Pproj2 -O0 main - -then the compiler will be invoked on :file:`main.adb` with the following -sequence of switches - - :: - - -g -O1 -O2 -O0 - -with the last *-O* -switch having precedence over the earlier ones; -several other switches -(such as *-c*) are added implicitly. - -The switches *-g* -and *-O1* are contributed by package -`Builder`, *-O2* is contributed -by the package `Compiler` -and *-O0* comes from the command line. - -The *-g* switch will also be passed in the invocation of -*Gnatlink.* - -A final example illustrates switch contributions from packages in different -project files: - - .. code-block:: gpr - - project Proj3 is - for Source_Files use ("pack.ads", "pack.adb"); - package Compiler is - for Default_Switches ("Ada") - use ("-gnata"); - end Compiler; - end Proj3; - - with "Proj3"; - project Proj4 is - for Source_Files use ("foo_main.adb", "bar_main.adb"); - package Builder is - for Switches ("foo_main.adb") - use ("-s", - "-g"); - end Builder; - end Proj4; - - .. code-block:: ada - - -- Ada source file: - with Pack; - procedure Foo_Main is - ... - end Foo_Main; - -If the command is - - :: - - $ gnatmake -PProj4 foo_main.adb -cargs -gnato - -then the switches passed to the compiler for :file:`foo_main.adb` are -*-g* (contributed by the package `Proj4.Builder`) and -*-gnato* (passed on the command line). -When the imported package `Pack` is compiled, the switches used -are *-g* from `Proj4.Builder`, -*-gnata* (contributed from package `Proj3.Compiler`, -and *-gnato* from the command line. - -When using *gnatmake* with project files, some switches or -arguments may be expressed as relative paths. As the working directory where -compilation occurs may change, these relative paths are converted to absolute -paths. For the switches found in a project file, the relative paths -are relative to the project file directory, for the switches on the command -line, they are relative to the directory where *gnatmake* is invoked. -The switches for which this occurs are: --I, --A, --L, --aO, --aL, --aI, as well as all arguments that are not switches (arguments to -switch --o, object files specified in package `Linker` or after --largs on the command line). The exception to this rule is the switch ---RTS= for which a relative path argument is never converted. - -.. _Specifying_Configuration_Pragmas: - -Specifying Configuration Pragmas -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -When using *gnatmake* with project files, if there exists a file -:file:`gnat.adc` that contains configuration pragmas, this file will be -ignored. - -Configuration pragmas can be defined by means of the following attributes in -project files: `Global_Configuration_Pragmas` in package `Builder` -and `Local_Configuration_Pragmas` in package `Compiler`. - -Both these attributes are single string attributes. Their values is the path -name of a file containing configuration pragmas. If a path name is relative, -then it is relative to the project directory of the project file where the -attribute is defined. - -When compiling a source, the configuration pragmas used are, in order, -those listed in the file designated by attribute -`Global_Configuration_Pragmas` in package `Builder` of the main -project file, if it is specified, and those listed in the file designated by -attribute `Local_Configuration_Pragmas` in package `Compiler` of -the project file of the source, if it exists. - -.. _Project_Files_and_Main_Subprograms: - -Project Files and Main Subprograms -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -When using a project file, you can invoke *gnatmake* -with one or several main subprograms, by specifying their source files on the -command line. - - :: - - $ gnatmake -Pprj main1.adb main2.adb main3.adb - -Each of these needs to be a source file of the same project, except -when the switch `-u` is used. - -When `-u` is not used, all the mains need to be sources of the -same project, one of the project in the tree rooted at the project specified -on the command line. The package `Builder` of this common project, the -"main project" is the one that is considered by *gnatmake*. - -When `-u` is used, the specified source files may be in projects -imported directly or indirectly by the project specified on the command line. -Note that if such a source file is not part of the project specified on the -command line, the switches found in package `Builder` of the -project specified on the command line, if any, that are transmitted -to the compiler will still be used, not those found in the project file of -the source file. - -When using a project file, you can also invoke *gnatmake* without -explicitly specifying any main, and the effect depends on whether you have -defined the `Main` attribute. This attribute has a string list value, -where each element in the list is the name of a source file (the file -extension is optional) that contains a unit that can be a main subprogram. - -If the `Main` attribute is defined in a project file as a non-empty -string list and the switch *-u* is not used on the command -line, then invoking *gnatmake* with this project file but without any -main on the command line is equivalent to invoking *gnatmake* with all -the file names in the `Main` attribute on the command line. - -Example: - - .. code-block:: gpr - - project Prj is - for Main use ("main1.adb", "main2.adb", "main3.adb"); - end Prj; - -With this project file, `"gnatmake -Pprj"` -is equivalent to -`"gnatmake -Pprj main1.adb main2.adb main3.adb"`. - -When the project attribute `Main` is not specified, or is specified -as an empty string list, or when the switch *-u* is used on the command -line, then invoking *gnatmake* with no main on the command line will -result in all immediate sources of the project file being checked, and -potentially recompiled. Depending on the presence of the switch *-u*, -sources from other project files on which the immediate sources of the main -project file depend are also checked and potentially recompiled. In other -words, the *-u* switch is applied to all of the immediate sources of the -main project file. - -When no main is specified on the command line and attribute `Main` exists -and includes several mains, or when several mains are specified on the -command line, the default switches in package `Builder` will -be used for all mains, even if there are specific switches -specified for one or several mains. - -But the switches from package `Binder` or `Linker` will be -the specific switches for each main, if they are specified. - -.. _Library_Project_Files: - -Library Project Files -^^^^^^^^^^^^^^^^^^^^^ - -When *gnatmake* is invoked with a main project file that is a library -project file, it is not allowed to specify one or more mains on the command -line. - -When a library project file is specified, switches `-b` and -`-l` have special meanings. - -* `-b` is only allowed for stand-alone libraries. It indicates - to *gnatmake* that *gnatbind* should be invoked for the - library. - -* `-l` may be used for all library projects. It indicates - to *gnatmake* that the binder generated file should be compiled - (in the case of a stand-alone library) and that the library should be built. - - -.. _The_GNAT_Driver_and_Project_Files: - -The GNAT Driver and Project Files ---------------------------------- - -A number of GNAT tools beyond *gnatmake* -can benefit from project files: - -.. only:: PRO or GPL - - * *gnatbind* - * *gnatcheck* - * *gnatclean* - * *gnatelim* - * *gnatfind* - * *gnatlink* - * *gnatls* - * *gnatmetric* - * *gnatpp* - * *gnatstub* - * *gnatxref* - -.. only:: FSF - - * *gnatbind* - * *gnatclean* - * *gnatfind* - * *gnatlink* - * *gnatls* - * *gnatxref* - -However, none of these tools can be invoked -directly with a project file switch (*-P*). -They must be invoked through the *gnat* driver. - -The *gnat* driver is a wrapper that accepts a number of commands and -calls the corresponding tool. It was designed initially for VMS platforms (to -convert VMS qualifiers to Unix-style switches), but it is now available on all -GNAT platforms. - -On non-VMS platforms, the *gnat* driver accepts the following commands -(case insensitive): - -.. only:: PRO or GPL - - * BIND to invoke *gnatbind* - * CHOP to invoke *gnatchop* - * CLEAN to invoke *gnatclean* - * COMP or COMPILE to invoke the compiler - * ELIM to invoke *gnatelim* - * FIND to invoke *gnatfind* - * KR or KRUNCH to invoke *gnatkr* - * LINK to invoke *gnatlink* - * LS or LIST to invoke *gnatls* - * MAKE to invoke *gnatmake* - * METRIC to invoke *gnatmetric* - * NAME to invoke *gnatname* - * PP or PRETTY to invoke *gnatpp* - * PREP or PREPROCESS to invoke *gnatprep* - * STUB to invoke *gnatstub* - * XREF to invoke *gnatxref* - -.. only:: FSF - - * BIND to invoke *gnatbind* - * CHOP to invoke *gnatchop* - * CLEAN to invoke *gnatclean* - * COMP or COMPILE to invoke the compiler - * FIND to invoke *gnatfind* - * KR or KRUNCH to invoke *gnatkr* - * LINK to invoke *gnatlink* - * LS or LIST to invoke *gnatls* - * MAKE to invoke *gnatmake* - * NAME to invoke *gnatname* - * PREP or PREPROCESS to invoke *gnatprep* - * XREF to invoke *gnatxref* - -Note that the command -*gnatmake -c -f -u* is used to invoke the compiler. - -On non-VMS platforms, between *gnat* and the command, two -special switches may be used: - -* *-v* to display the invocation of the tool. -* *-dn* to prevent the *gnat* driver from removing - the temporary files it has created. These temporary files are - configuration files and temporary file list files. - -The command may be followed by switches and arguments for the invoked -tool. - - :: - - $ gnat bind -C main.ali - $ gnat ls -a main - $ gnat chop foo.txt - -Switches may also be put in text files, one switch per line, and the text -files may be specified with their path name preceded by '@'. - - :: - - $ gnat bind @args.txt main.ali - -In addition, for the following commands the project file related switches -(*-P*, *-X* and *-vPx*) may be used in addition to -the switches of the invoking tool: - -.. only:: PRO or GPL - - * BIND - * COMP or COMPILE - * FIND - * ELIM - * LS or LIST - * LINK - * METRIC - * PP or PRETTY - * STUB - * XREF - -.. only:: FSF - - * BIND - * COMP or COMPILE - * FIND - * LS or LIST - * LINK - * XREF - -.. only:: PRO or GPL - - When GNAT PP or GNAT PRETTY is used with a project file, but with no source - specified on the command line, it invokes *gnatpp* with all - the immediate sources of the specified project file. - - When GNAT METRIC is used with a project file, but with no source - specified on the command line, it invokes *gnatmetric* - with all the immediate sources of the specified project file and with - *-d* with the parameter pointing to the object directory - of the project. - - In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with - a project file, no source is specified on the command line and - switch -U is specified on the command line, then - the underlying tool (gnatpp or - gnatmetric) is invoked for all sources of all projects, - not only for the immediate sources of the main project. - (-U stands for Universal or Union of the project files of the project tree) - -For each of the following commands, there is optionally a corresponding -package in the main project. - -.. only:: PRO or GPL - - * package `Binder` for command BIND (invoking `gnatbind`) - * package `Check` for command CHECK (invoking `gnatcheck`) - * package `Compiler` for command COMP or COMPILE (invoking the compiler) - * package `Cross_Reference` for command XREF (invoking `gnatxref`) - * package `Eliminate` for command ELIM (invoking `gnatelim`) - * package `Finder` for command FIND (invoking `gnatfind`) - * package `Gnatls` for command LS or LIST (invoking `gnatls`) - * package `Gnatstub` for command STUB (invoking `gnatstub`) - * package `Linker` for command LINK (invoking `gnatlink`) - * package `Metrics` for command METRIC (invoking `gnatmetric`) - * package `Pretty_Printer` for command PP or PRETTY (invoking `gnatpp`) - -.. only:: FSF - - * package `Binder` for command BIND (invoking `gnatbind`) - * package `Compiler` for command COMP or COMPILE (invoking the compiler) - * package `Cross_Reference` for command XREF (invoking `gnatxref`) - * package `Finder` for command FIND (invoking `gnatfind`) - * package `Gnatls` for command LS or LIST (invoking `gnatls`) - * package `Linker` for command LINK (invoking `gnatlink`) - -Package `Gnatls` has a unique attribute `Switches`, -a simple variable with a string list value. It contains switches -for the invocation of `gnatls`. - - .. code-block:: gpr - - project Proj1 is - package gnatls is - for Switches - use ("-a", - "-v"); - end gnatls; - end Proj1; - -All other packages have two attribute `Switches` and -`Default_Switches`. - -`Switches` is an indexed attribute, indexed by the -source file name, that has a string list value: the switches to be -used when the tool corresponding to the package is invoked for the specific -source file. - -`Default_Switches` is an attribute, -indexed by the programming language that has a string list value. -`Default_Switches ("Ada")` contains the -switches for the invocation of the tool corresponding -to the package, except if a specific `Switches` attribute -is specified for the source file. - - .. code-block:: gpr - - project Proj is - - for Source_Dirs use (""); - - package gnatls is - for Switches use - ("-a", - "-v"); - end gnatls; - - package Compiler is - for Default_Switches ("Ada") - use ("-gnatv", - "-gnatwa"); - end Binder; - - package Binder is - for Default_Switches ("Ada") - use ("-C", - "-e"); - end Binder; - - package Linker is - for Default_Switches ("Ada") - use ("-C"); - for Switches ("main.adb") - use ("-C", - "-v", - "-v"); - end Linker; - - package Finder is - for Default_Switches ("Ada") - use ("-a", - "-f"); - end Finder; - - package Cross_Reference is - for Default_Switches ("Ada") - use ("-a", - "-f", - "-d", - "-u"); - end Cross_Reference; - end Proj; - -With the above project file, commands such as - - :: - - $ gnat comp -Pproj main - $ gnat ls -Pproj main - $ gnat xref -Pproj main - $ gnat bind -Pproj main.ali - $ gnat link -Pproj main.ali - -will set up the environment properly and invoke the tool with the switches -found in the package corresponding to the tool: -`Default_Switches ("Ada")` for all tools, -except `Switches ("main.adb")` -for `gnatlink`. - -.. only:: PRO or GPL - - It is also possible to invoke some of the tools, - (`gnatcheck`, - `gnatmetric`, - and `gnatpp`) - on a set of project units thanks to the combination of the switches - *-P*, *-U* and possibly the main unit when one is interested - in its closure. For instance, - - :: - - $ gnat metric -Pproj - - will compute the metrics for all the immediate units of project `proj`. - - :: - - $ gnat metric -Pproj -U - - will compute the metrics for all the units of the closure of projects - rooted at `proj`. - - :: - - $ gnat metric -Pproj -U main_unit - - will compute the metrics for the closure of units rooted at - `main_unit`. This last possibility relies implicitly - on *gnatbind*'s option *-R*. But if the argument files for the - tool invoked by the *gnat* driver are explicitly specified - either directly or through the tool *-files* option, then the tool - is called only for these explicitly specified files. -- 2.30.2