Merge branch 'slides/217-update_gnat_project_facility' into 'master'

Resolve "Update GNAT Project Facility training for GNAT 24.2"

See merge request feng/training/material!297

Author: frank-at-adacore

courses/gnat_project_facility/010_overview.rst

@@ -59,19 +59,19 @@ Origins and Purposes of Projects
 
 + Tools (metrics, documentation generator, etc)
 
-  + AdaCore Tools benefit from having knowledge of application structure
+  + AdaCore tools benefit from having knowledge of application structure
 
 ---------------------------------
 Subsystems of Subsystems of ...
 ---------------------------------
 
-+ Projects support incremental, modular project definition
++ Projects support incremental/modular project definition
 
   + Projects can import other projects containing needed files
   + Child projects can extend parent projects
 
     + Inheriting all attributes of parent
-    + Can optionally override source files and other attributes
+    + Allows override of source files and other attributes
 
 + Allows structuring of large development efforts into hierarchical subsystems
 
@@ -112,7 +112,7 @@ Configurable Properties
   + Ada / C / C++ are preconfigured
 
 + Source file naming conventions
-+ et cetera
++ And many more
 
 --------------------------
 The Minimal Project File
@@ -129,7 +129,8 @@ Specifying Main Subprogram(s)
 
 + Optional
 
-  + If not specified in file, must be specified on command-line
+  + Some projects do not build an executable
+  + If necessary and not specified in file, must be specified on command-line
 
 + Can have more than one file named
 + A project-level setting

courses/gnat_project_facility/020_building_with_gprbuild.rst

@@ -88,7 +88,7 @@ GPRbuild Command Line
 Common Options Passed To Tools
 --------------------------------
 
-* :command:`-cargs options`
+:command:`-cargs options`
 
   * Options passed to all compilers
   * Example:
@@ -98,7 +98,7 @@ Common Options Passed To Tools
       -cargs -g
 
 
-* :command:`-cargs:<language> options`
+:command:`-cargs:<language> options`
 
   * Options passed to compiler for specific language
   * Examples:
@@ -109,11 +109,11 @@ Common Options Passed To Tools
       -cargs:C -E
 
 
-* :command:`-bargs options`
+:command:`-bargs options`
 
   * Options passed to all binder drivers
 
-* :command:`-bargs:<language> options`
+:command:`-bargs:<language> options`
 
   * Options passed to binder driver for specific language
   * Examples:
@@ -124,7 +124,7 @@ Common Options Passed To Tools
       -bargs:C++ c_compiler_name=ccppc
 
 
-* :command:`-largs options`
+:command:`-largs options`
 
   * Options passed to linker for generating executable
 

courses/gnat_project_facility/030_project_properties.rst

@@ -173,9 +173,9 @@ Source Files
 Object Directory
 ------------------
 
-+ Specifies location for compiler-generated files
++ Specifies location for files generated by compiler (or tools)
 
-  + Such as :filename:`.ali` files and object files
+  + Such as :filename:`.ali` files and :filename:`.o` files
   + For the project's immediate sources
 
      .. code:: Ada
@@ -187,10 +187,6 @@ Object Directory
 
 + Only one object directory per project
 
-+ If :ada:`Child` extends project :ada:`Parent` and then building :ada:`Child`
-
-    + For any source that exists only in :ada:`Parent` but has not been compiled, it's object files will appear in the :ada:`Child` object directory
-
 ----------------------
 Executable Directory
 ----------------------
@@ -221,34 +217,35 @@ Packages Correspond to Tools
 
   + Not by users
 
-.. columns::
-
-  .. column::
-
-    * Analyzer
-    * Binder
-    * Builder
-    * Check
-    * Clean
-    * Compiler
-    * Cross_Reference
-    * Documentation
-    * Eliminate
-    * Finder
-    * Gnatls
-
-  .. column::
-
-    * Gnatstub
-    * IDE
-    * Install
-    * Linker
-    * Metrics
-    * Naming
-    * Pretty_Printer
-    * Remote
-    * Stack
-    * Synchronize
+.. list-table::
+
+    * - Analyzer
+      - Binder
+      - Builder
+
+    * - Check
+      - Clean
+      - Compiler
+
+    * - Cross_Reference
+      - Documentation
+      - Eliminate
+
+    * - Finder
+      - Gnatls
+      - Gnatstub
+
+    * - IDE
+      - Install
+      - Linker
+
+    * - Metrics
+      - Naming
+      - Pretty_Printer
+
+    * - Remote
+      - Stack
+      - Synchronize
 
 -----------------------
 Setting Tool Switches
@@ -294,8 +291,7 @@ Rationale
 
   + Third-party libraries
   + Legacy code used different compiler
-
-    + Changing filenames would make tracking changes harder
+  + Changing filenames would make tracking changes harder
 
 ----------------------------
 Source File Naming Schemes
@@ -305,13 +301,12 @@ Source File Naming Schemes
 
   + Other than GNAT default convention
 
-+ May be applied to all source files in a project
-
-  + Specified in a package named :ada:`Naming`
++ Specified in a package named :ada:`Naming`
 
-+ May be applied to specific files in a project
+  + May be applied to all source files in a project
+  + May be applied to specific files in a project
 
-  + Individual attribute specifications
+    + Individual attribute specifications
 
 -------------------------------------
 Foreign Default File Naming Example
@@ -377,11 +372,11 @@ Individual (Arbitrary) File Naming
 
 + Has distinct attributes for specs and bodies
 
-:ada:`for Spec ("<unit name>") use "<filename>"`
+  + Syntax: *for Spec ("<Ada unit name>") use "<filename>";*
 
-   :ada:`for Spec ("MyPack.MyChild") use "MMS1AF32.A";`
+  :ada:`for Spec ("MyPack.MyChild") use "MMS1AF32.A";`
 
-   :ada:`for Body ("MyPack.MyChild") use "MMS1AF32.B";`
+  :ada:`for Body ("MyPack.MyChild") use "MMS1AF32.B";`
 
 ======================================
 Variables for Conditional Processing
@@ -442,13 +437,13 @@ External and Conditional References
 
 + Command line switch
 
-:command:`gprbuild -P... -Xname=value ...`
+  + Syntax: *gprbuild -P... -Xname=value ...*
 
-  .. container:: latex_environment footnotesize
+.. container:: latex_environment footnotesize
 
-     :command:`gprbuild -P common/build.gpr -Xtarget=test  common/main.adb`
+   :command:`gprbuild -P common/build.gpr -Xtarget=test  common/main.adb`
 
-+ **Note:** Command line values override environment variables
+.. note:: Command line values override environment variables
 
 ----------------------------------------
 External/Conditional Reference Example

courses/gnat_project_facility/040_structuring_your_application.rst

@@ -120,7 +120,7 @@ Project Import Notation
      end MyApp;
 
 -----------------------
-GPRBuild search paths
+GPRbuild search paths
 -----------------------
 
 GPR with **relative** paths are searched
@@ -135,9 +135,8 @@ GPR with **relative** paths are searched
     * List of directories, separated by PATH-like (``:``, ``;``) separator
 
         + ``GPR_PROJECT_PATH``
-        + ``ADA_PROJECT_PATH`` (deprecated)
 
-- From the current toolchain's install dir
+- From the current toolchain's installation directory
 
     * Can be target-specific
     * Can be runtime-specific
@@ -223,13 +222,13 @@ Referencing Imported Content
 
    + Project P uses all the compiler switches in project Foo and adds ``-gnatwa``
 
-   + *Note: in GPR files, "&" can be used to concatenate string lists and string*
+.. note:: in GPR files, "&" can be used to concatenate string lists and strings
 
 ----------
 Renaming
 ----------
 
-+ Packages can rename (imported) packages
++ Packages can rename imported packages
 + Effect is as if the package is declared locally
 
   + Much like the Ada language
@@ -257,29 +256,29 @@ Project Source Code Dependencies
       with Hmi.Controls;
       package body Nav.Engine is
          Global_Speed : Speed_T := 0.0;
-         procedure Increase_Speed (Change : Speed_Delta_T) is
-            Max_Change : Speed_T := Global_Speed * 0.10;
+         procedure Increase
+            (Change : Speed_Delta_T) is
          begin
-            Global_Speed :=
-              Global_Speed + Speed_T'max (Speed_T (Change),
-                                          Max_Change);
-            Hmi.Controls.Display_Speed (Global_Speed);
-         end Increase_Speed;
+            Global_Speed := Global_Speed + Change;
+            Hmi.Controls.Display (Global_Speed);
+         end Increase;
       end Nav.Engine;
 
   + In the :ada:`HMI` project
 
     .. code:: Ada
 
       package body Hmi.Controls is
-         procedure Display_Speed (Speed : Nav.Engine.Speed_T) is
+         procedure Display
+            (Speed : Nav.Engine.Speed_T) is
          begin
-            Display_Speed_On_Console (Speed);
-         end Display_Speed;
-         procedure Change_Speed (Speed_Change : Nav.Engine.Speed_Delta_T) is
+            Display_On_Console (Speed);
+         end Display;
+         procedure Change
+            (Speed_Change : Nav.Engine.Speed_Delta_T) is
          begin
-            Nav.Engine.Increase_Speed (Speed_Change);
-         end Change_Speed;
+            Nav.Engine.Increase (Speed_Change);
+         end Change;
       end Hmi.Controls;
 
 ----------------------
@@ -394,6 +393,26 @@ Extending Projects
 
 + Hierarchies permitted
 
+-------------------
+Project Extension
+-------------------
+
+.. code:: Ada
+
+   project Child extends "parent.gpr" is 
+
++ New project :ada:`Child` inherits everything from :ada:`Parent`
+
+  + Except whatever new source/properties are specified in :ada:`Child`
+
++ When compiling project :ada:`Child`
+
+  + Source files in :ada:`Child` get compiled into its object directory
+  + For source files in :ada:`Parent` that are not overridden in :ada:`Child`
+
+    + If the source file is compiled into the :ada:`Parent` object directory, that file is considered compiled
+    + If the source file is not compiled into the :ada:`Parent` object directory, that file will be compiled into the :ada:`Child` object directory
+
 ------------------------------
 Limits on Extending Projects
 ------------------------------

courses/gnat_project_facility/labs/020_building_with_gprbuild.lab.rst

@@ -1,5 +1,5 @@
 --------------
-Start GPRBuild
+Start GPRbuild
 --------------
 
 * Open a command shell