diff --git a/courses/gnat_project_facility/010_overview.rst b/courses/gnat_project_facility/010_overview.rst index 6bc97c83e..8b3ff3118 100644 --- a/courses/gnat_project_facility/010_overview.rst +++ b/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 diff --git a/courses/gnat_project_facility/020_building_with_gprbuild.rst b/courses/gnat_project_facility/020_building_with_gprbuild.rst index b14a83a9a..b926b2b32 100644 --- a/courses/gnat_project_facility/020_building_with_gprbuild.rst +++ b/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: options` +:command:`-cargs: 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: options` +:command:`-bargs: 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 diff --git a/courses/gnat_project_facility/030_project_properties.rst b/courses/gnat_project_facility/030_project_properties.rst index 631db768f..bbbf59dec 100644 --- a/courses/gnat_project_facility/030_project_properties.rst +++ b/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 ("") use ""` + + Syntax: *for Spec ("") use "";* - :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 diff --git a/courses/gnat_project_facility/040_structuring_your_application.rst b/courses/gnat_project_facility/040_structuring_your_application.rst index 72323b8a4..b6f51dcef 100644 --- a/courses/gnat_project_facility/040_structuring_your_application.rst +++ b/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,14 +256,12 @@ 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 @@ -272,14 +269,16 @@ Project Source Code Dependencies .. 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 ------------------------------ diff --git a/courses/gnat_project_facility/labs/020_building_with_gprbuild.lab.rst b/courses/gnat_project_facility/labs/020_building_with_gprbuild.lab.rst index 5f11c0020..eabaea32e 100644 --- a/courses/gnat_project_facility/labs/020_building_with_gprbuild.lab.rst +++ b/courses/gnat_project_facility/labs/020_building_with_gprbuild.lab.rst @@ -1,5 +1,5 @@ -------------- -Start GPRBuild +Start GPRbuild -------------- * Open a command shell