[Ada] Documentation cleanups

gcc/ada/

	* doc/gnat_ugn/about_this_guide.rst: Remove old section and
	update for Ada 202x.
	* doc/gnat_ugn/getting_started_with_gnat.rst: Add a system
	requirements section. Remove obsolete section and minimal
	rewording on the getting started section.
	* gnat_ugn.texi: Regenerate.

2 files changed, 41 insertions, 168 deletions

diff --git a/gcc/ada/doc/gnat_ugn/about_this_guide.rst b/gcc/ada/doc/gnat_ugn/about_this_guide.rst
index 1ab2f4c..3347626 100644
--- a/gcc/ada/doc/gnat_ugn/about_this_guide.rst
+++ b/gcc/ada/doc/gnat_ugn/about_this_guide.rst
@@ -14,13 +14,13 @@ toolset for the full Ada programming language.
 It documents the features of the compiler and tools, and explains
 how to use them to build Ada applications.
 
-GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be
+GNAT implements Ada 95, Ada 2005, Ada 2012, and Ada 202x, and it may also be
 invoked in Ada 83 compatibility mode.
 By default, GNAT assumes Ada 2012, but you can override with a
 compiler switch (:ref:`Compiling_Different_Versions_of_Ada`)
 to explicitly specify the language version.
 Throughout this manual, references to 'Ada' without a year suffix
-apply to all Ada 95/2005/2012 versions of the language.
+apply to all Ada versions of the language, starting with Ada 95.
 
 What This Guide Contains
 ========================
@@ -71,8 +71,6 @@ What You Should Know before Reading This Guide
 This guide assumes a basic familiarity with the Ada 95 language, as
 described in the International Standard ANSI/ISO/IEC-8652:1995, January
 1995.
-It does not require knowledge of the features introduced by Ada 2005
-or Ada 2012.
 Reference manuals for Ada 95, Ada 2005, and Ada 2012 are included in
 the GNAT documentation package.
 
@@ -104,81 +102,6 @@ following documents:
   environment Emacs.
 
 
-A Note to Readers of Previous Versions of the Manual
-====================================================
-
-In early 2015 the GNAT manuals were transitioned to the
-reStructuredText (rst) / Sphinx documentation generator technology.
-During that process the :title:`GNAT User's Guide` was reorganized
-so that related topics would be described together in the same chapter
-or appendix.  Here's a summary of the major changes realized in
-the new document structure.
-
-* :ref:`The_GNAT_Compilation_Model` has been extended so that it now covers
-  the following material:
-
-  - The ``gnatname``, ``gnatkr``, and ``gnatchop`` tools
-  - :ref:`Configuration_Pragmas`
-  - :ref:`GNAT_and_Libraries`
-  - :ref:`Conditional_Compilation` including :ref:`Preprocessing_with_gnatprep`
-    and :ref:`Integrated_Preprocessing`
-  - :ref:`Generating_Ada_Bindings_for_C_and_C++_headers`
-  - :ref:`Using_GNAT_Files_with_External_Tools`
-
-* :ref:`Building_Executable_Programs_With_GNAT` is a new chapter consolidating
-  the following content:
-
-  - :ref:`The_GNAT_Make_Program_gnatmake`
-  - :ref:`Compiling_with_GCC`
-  - :ref:`Binding_with_gnatbind`
-  - :ref:`Linking_with_gnatlink`
-  - :ref:`Using_the_GNU_make_Utility`
-
-* :ref:`GNAT_Utility_Programs` is a new chapter consolidating the information about several
-  GNAT tools:
-
-  .. only:: PRO or GPL
-
-    - :ref:`The_File_Cleanup_Utility_gnatclean`
-    - :ref:`The_GNAT_Library_Browser_gnatls`
-    - :ref:`The_Cross-Referencing_Tools_gnatxref_and_gnatfind`
-    - :ref:`The_Ada_to_HTML_Converter_gnathtml`
-    - :ref:`The_Ada-to-XML_Converter_gnat2xml`
-    - :ref:`The_Coding_Standard_Verifier_gnatcheck`
-    - :ref:`The_GNAT_Metrics_Tool_gnatmetric`
-    - :ref:`The_GNAT_Pretty_Printer_gnatpp`
-    - :ref:`The_Body_Stub_Generator_gnatstub`
-    - :ref:`The_Unit_Test_Generator_gnattest`
-
-  .. only:: FSF
-
-    - :ref:`The_File_Cleanup_Utility_gnatclean`
-    - :ref:`The_GNAT_Library_Browser_gnatls`
-    - :ref:`The_Cross-Referencing_Tools_gnatxref_and_gnatfind`
-    - :ref:`The_Ada_to_HTML_Converter_gnathtml`
-
-* :ref:`GNAT_and_Program_Execution` is a new chapter consolidating the following:
-
-  - :ref:`Running_and_Debugging_Ada_Programs`
-  - :ref:`Profiling`
-  - :ref:`Improving_Performance`
-  - :ref:`Overflow Check Handling in GNAT <Overflow_Check_Handling_in_GNAT>`
-  - :ref:`Performing Dimensionality Analysis in GNAT <Performing_Dimensionality_Analysis_in_GNAT>`
-  - :ref:`Stack_Related_Facilities`
-  - :ref:`Memory_Management_Issues`
-
-* :ref:`Platform_Specific_Information` is a new appendix consolidating the following:
-
-  - :ref:`Run_Time_Libraries`
-  - :ref:`Microsoft_Windows_Topics`
-  - :ref:`Mac_OS_Topics`
-
-* The *Compatibility and Porting Guide* appendix has been moved to the
-  :title:`GNAT Reference Manual`. It now includes a section
-  *Writing Portable Fixed-Point Declarations* which was previously
-  a separate chapter in the :title:`GNAT User's Guide`.
-
-
 Conventions
 ===========
 .. index:: Conventions, typographical
diff --git a/gcc/ada/doc/gnat_ugn/getting_started_with_gnat.rst b/gcc/ada/doc/gnat_ugn/getting_started_with_gnat.rst
index 34dc355..9814cb6 100644
--- a/gcc/ada/doc/gnat_ugn/getting_started_with_gnat.rst
+++ b/gcc/ada/doc/gnat_ugn/getting_started_with_gnat.rst
@@ -9,14 +9,43 @@ Getting Started with GNAT
 This chapter describes how to use GNAT's command line interface to build
 executable Ada programs.
 On most platforms a visually oriented Integrated Development Environment
-is also available, the GNAT Programming Studio (GNAT Studio).
+is also available: GNAT Studio.
 GNAT Studio offers a graphical "look and feel", support for development in
 other programming languages, comprehensive browsing features, and
 many other capabilities.
-For information on GNAT Studio please refer to
-:title:`Using the GNAT Programming Studio`.
+For information on GNAT Studio please refer to the
+:title:`GNAT Studio documentation`.
 
 
+.. _System_Requirements:
+
+System Requirements
+===================
+
+Even though any machine can run the GNAT toolset and GNAT Studio IDE, in order
+to get the best experience, we recommend using a machine with as many cores
+as possible since all individual compilations can run in parallel.
+A comfortable setup for a compiler server is a machine with 24 physical cores
+or more, with at least 48 GB of memory (2 GB per core).
+
+For a desktop machine, a minimum of 4 cores is recommended (8 preferred),
+with at least 2GB per core (so 8 to 16GB).
+
+In addition, for running and navigating sources in GNAT Studio smoothly, we
+recommend at least 1.5 GB plus 3 GB of RAM per 1 million source line of code.
+In other words, we recommend at least 3 GB for for 500K lines of code and
+7.5 GB for 2 million lines of code.
+
+Note that using local and fast drives will also make a difference in terms of
+build and link time. Network drives such as NFS, SMB, or worse, configuration
+management filesystems (such as ClearCase dynamic views) should be avoided as
+much as possible and will produce very degraded performance (typically 2 to 3
+times slower than on local fast drives). If such slow drives cannot be avoided
+for accessing the source code, then you should at least configure your project
+file so that the result of the compilation is stored on a drive local to the
+machine performing the run. This can be achieved by setting the ``Object_Dir``
+project file attribute.
+
 .. _Running_GNAT:
 
 Running GNAT
@@ -96,24 +125,12 @@ file corresponding to your Ada program. It also generates
 an 'Ada Library Information' file :file:`hello.ali`,
 which contains additional information used to check
 that an Ada program is consistent.
-To build an executable file,
-use ``gnatbind`` to bind the program
-and ``gnatlink`` to link it. The
-argument to both ``gnatbind`` and ``gnatlink`` is the name of the
-:file:`ALI` file, but the default extension of :file:`.ali` can
-be omitted. This means that in the most common case, the argument
-is simply the name of the main program:
-
-.. code-block:: sh
-
-  $ gnatbind hello
-  $ gnatlink hello
 
-A simpler method of carrying out these steps is to use ``gnatmake``,
-a master program that invokes all the required
-compilation, binding and linking tools in the correct order. In particular,
-``gnatmake`` automatically recompiles any sources that have been
-modified since they were last compiled, or sources that depend
+To build an executable file, use either ``gnatmake`` or gprbuild with
+the name of the main file: these tools are builders that will take care of
+all the necessary build steps in the correct order.
+In particular, these builders automatically recompile any sources that have
+been modified since they were last compiled, or sources that depend
 on such modified sources, so that 'version skew' is avoided.
 
 .. index:: Version skew (avoided by ``gnatmake``)
@@ -190,17 +207,6 @@ following three separate files:
 *gmain.adb*
   body of main program
 
-To build an executable version of
-this program, we could use four separate steps to compile, bind, and link
-the program, as follows:
-
-.. code-block:: sh
-
-  $ gcc -c gmain.adb
-  $ gcc -c greetings.adb
-  $ gnatbind gmain
-  $ gnatlink gmain
-
 Note that there is no required order of compilation when using GNAT.
 In particular it is perfectly fine to compile the main program first.
 Also, it is not necessary to compile package specs in the case where
@@ -212,66 +218,10 @@ generation, then use the :switch:`-gnatc` switch:
 
   $ gcc -c greetings.ads -gnatc
 
-Although the compilation can be done in separate steps as in the
-above example, in practice it is almost always more convenient
-to use the ``gnatmake`` tool. All you need to know in this case
-is the name of the main program's source file. The effect of the above four
-commands can be achieved with a single one:
+Although the compilation can be done in separate steps, in practice it is
+almost always more convenient to use the ``gnatmake`` or ``gprbuild`` tools:
 
 .. code-block:: sh
 
   $ gnatmake gmain.adb
 
-In the next section we discuss the advantages of using ``gnatmake`` in
-more detail.
-
-.. _Using_the_gnatmake_Utility:
-
-Using the ``gnatmake`` Utility
-==============================
-
-If you work on a program by compiling single components at a time using
-``gcc``, you typically keep track of the units you modify. In order to
-build a consistent system, you compile not only these units, but also any
-units that depend on the units you have modified.
-For example, in the preceding case,
-if you edit :file:`gmain.adb`, you only need to recompile that file. But if
-you edit :file:`greetings.ads`, you must recompile both
-:file:`greetings.adb` and :file:`gmain.adb`, because both files contain
-units that depend on :file:`greetings.ads`.
-
-``gnatbind`` will warn you if you forget one of these compilation
-steps, so that it is impossible to generate an inconsistent program as a
-result of forgetting to do a compilation. Nevertheless it is tedious and
-error-prone to keep track of dependencies among units.
-One approach to handle the dependency-bookkeeping is to use a
-makefile. However, makefiles present maintenance problems of their own:
-if the dependencies change as you change the program, you must make
-sure that the makefile is kept up-to-date manually, which is also an
-error-prone process.
-
-The ``gnatmake`` utility takes care of these details automatically.
-Invoke it using either one of the following forms:
-
-.. code-block:: sh
-
-  $ gnatmake gmain.adb
-  $ gnatmake gmain
-
-The argument is the name of the file containing the main program;
-you may omit the extension. ``gnatmake``
-examines the environment, automatically recompiles any files that need
-recompiling, and binds and links the resulting set of object files,
-generating the executable file, :file:`gmain`.
-In a large program, it
-can be extremely helpful to use ``gnatmake``, because working out by hand
-what needs to be recompiled can be difficult.
-
-Note that ``gnatmake`` takes into account all the Ada rules that
-establish dependencies among units. These include dependencies that result
-from inlining subprogram bodies, and from
-generic instantiation. Unlike some other
-Ada make tools, ``gnatmake`` does not rely on the dependencies that were
-found by the compiler on a previous compilation, which may possibly
-be wrong when sources change. ``gnatmake`` determines the exact set of
-dependencies from scratch each time it is run.