CbC/CbC_gcc: gcc/ada/doc/gnat_ugn/gnat_and_program

comparison gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst @ 131:84e7813d76e9

gcc-8.2

author	mir3636
date	Thu, 25 Oct 2018 07:37:49 +0900
parents	04ced10e8804
children	1830386684a0

comparison

equal deleted inserted replaced

-:04ced10e8804
+:84e7813d76e9
 **************************
 This chapter covers several topics:
 * `Running and Debugging Ada Programs`_
-* `Code Coverage and Profiling`_
+* `Profiling`_
 * `Improving Performance`_
 * `Overflow Check Handling in GNAT`_
 * `Performing Dimensionality Analysis in GNAT`_
 * `Stack Related Facilities`_
 * `Memory Management Issues`_
 documentation
 <http://docs.adacore.com/gdb-docs/html/gdb.html#Pretty_002dPrinter-Commands>`_
 for more information.
-.. index:: Code Coverage
 .. index:: Profiling
-.. _Code_Coverage_and_Profiling:
+.. _Profiling:
-Code Coverage and Profiling
+Profiling
-===========================
+=========
-This section describes how to use the ``gcov`` coverage testing tool and
+This section describes how to use the the ``gprof`` profiler tool on Ada
-the ``gprof`` profiler tool on Ada programs.
+programs.
-.. index:: !  gcov
-.. _Code_Coverage_of_Ada_Programs_with_gcov:
-Code Coverage of Ada Programs with gcov
----------------------------------------
-``gcov`` is a test coverage program: it analyzes the execution of a given
-program on selected tests, to help you determine the portions of the program
-that are still untested.
-``gcov`` is part of the GCC suite, and is described in detail in the GCC
-User's Guide. You can refer to this documentation for a more complete
-description.
-This chapter provides a quick startup guide, and
-details some GNAT-specific features.
-.. _Quick_startup_guide:
-Quick startup guide
-^^^^^^^^^^^^^^^^^^^
-In order to perform coverage analysis of a program using ``gcov``, several
-steps are needed:
-#. Instrument the code during the compilation process,
-#. Execute the instrumented program, and
-#. Invoke the ``gcov`` tool to generate the coverage results.
-.. index:: -fprofile-arcs (gcc)
-.. index:: -ftest-coverage (gcc
-.. index:: -fprofile-arcs (gnatbind)
-The code instrumentation needed by gcov is created at the object level.
-The source code is not modified in any way, because the instrumentation code is
-inserted by gcc during the compilation process. To compile your code with code
-coverage activated, you need to recompile your whole project using the
-switches
-:switch:`-fprofile-arcs` and :switch:`-ftest-coverage`, and link it using
-:switch:`-fprofile-arcs`.
-::
-$ gnatmake -P my_project.gpr -f -cargs -fprofile-arcs -ftest-coverage \\
--largs -fprofile-arcs
-This compilation process will create :file:`.gcno` files together with
-the usual object files.
-Once the program is compiled with coverage instrumentation, you can
-run it as many times as needed -- on portions of a test suite for
-example. The first execution will produce :file:`.gcda` files at the
-same location as the :file:`.gcno` files.  Subsequent executions
-will update those files, so that a cumulative result of the covered
-portions of the program is generated.
-Finally, you need to call the ``gcov`` tool. The different options of
-``gcov`` are described in the GCC User's Guide, section *Invoking gcov*.
-This will create annotated source files with a :file:`.gcov` extension:
-:file:`my_main.adb` file will be analyzed in :file:`my_main.adb.gcov`.
-.. _GNAT_specifics:
-GNAT specifics
-^^^^^^^^^^^^^^
-Because of Ada semantics, portions of the source code may be shared among
-several object files. This is the case for example when generics are
-involved, when inlining is active  or when declarations generate  initialisation
-calls. In order to take
-into account this shared code, you need to call ``gcov`` on all
-source files of the tested program at once.
-The list of source files might exceed the system's maximum command line
-length. In order to bypass this limitation, a new mechanism has been
-implemented in ``gcov``: you can now list all your project's files into a
-text file, and provide this file to gcov as a parameter,  preceded by a ``@``
-(e.g. :samp:`gcov @mysrclist.txt`).
-Note that on AIX compiling a static library with :switch:`-fprofile-arcs` is
-not supported as there can be unresolved symbols during the final link.
 .. index:: !  gprof
 .. index:: Profiling
 .. _Profiling_an_Ada_Program_with_gprof:
 ``gprof`` is the standard GNU profiling tool; it has been enhanced to
 better handle Ada programs and multitasking.
 It is currently supported on the following platforms
 * linux x86/x86_64
-* solaris sparc/sparc64/x86
 * windows x86
 In order to profile a program using ``gprof``, several steps are needed:
 #. Instrument the code, which requires a full recompilation of the project with the
 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
+the :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:
 If a set of source files is specified as ``gnatelim`` arguments, it
 treats these files as a complete set of sources making up a program to
 analyse, and analyses only these sources.
-After a full successful build of the main subprogram ``gnatelim`` can be
+If ``gnatelim`` is called with a project file and :samp:`-U` option is
-called without  specifying sources to analyse, in this case it computes
+used, then in process all the files from the argument project but
-the source closure of the main unit from the :file:`ALI` files.
+not just the closure of the main subprogram.
+In all the other cases (that are typical cases of ``gnatelim`` usage, when
+the only ``gnatelim`` parameter is the name of the source file containing
+the main subprogram) gnatelim needs the full closure of the main subprogram.
+When called with a project file, gnatelim computes this closure itself.
+Otherwise it assumes that it can reuse the results of the previous
+build of the main subprogram.
 If the set of sources to be processed by ``gnatelim`` contains sources with
 preprocessing directives
 then the needed options should be provided to run preprocessor as a part of
 the ``gnatelim`` call, and the generated set of pragmas ``Eliminate``
 will correspond to preprocessed sources.
-The following command will create the set of :file:`ALI` files needed for
-``gnatelim``:
-::
-$ gnatmake -c Main_Prog
-Note that ``gnatelim`` does not need object files.
 .. _Running_gnatelim:
 Running ``gnatelim``
 :samp:`--RTS={rts-path}`
 Specifies the default location of the runtime library. Same meaning as the
 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
+.. index:: -U (gnatelim)
+:samp:`-U`
+Process all the sources from the argument project. If no project file
+is specified, this option has no effect. If this option is used with the
+project file, ``gnatelim`` does not require the preliminary build of the
+argument main subprogram.
 .. index:: -files (gnatelim)
 :samp:`-files={filename}`
 Take the argument source files from the specified file. This file should be an
 ordinary text file containing file names separated by spaces or
 :samp:`-j{n}`
 Use ``n`` processes to carry out the tree creations (internal representations
 of the argument sources). On a multiprocessor machine this speeds up processing
 of big sets of argument sources. If ``n`` is 0, then the maximum number of
 parallel tree creations is the number of core processors on the platform.
+This possibility is disabled if ``gnatelim`` has to compute the closure
+of the main unit.
 .. index:: -q (gnatelim)
 :samp:`-q`
 You will need to manually remove the wrong ``Eliminate`` pragmas from
 the configuration file indicated in the error message. You should recompile
 your program from scratch after that, because you need a consistent
 configuration file(s) during the entire compilation.
+If ``gnatelim`` is called with a project file and with ``-U`` option
-.. _Making_Your_Executables_Smaller:
+the generated set of pragmas may contain pragmas for subprograms that
+does not belong to the closure of the argument main subprogram. These
-Making Your Executables Smaller
+pragmas has no effect when the set of pragmas is used to reduce the size
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+of executable.
-In order to get a smaller executable for your program you now have to
-recompile the program completely with the configuration file containing
-pragmas Eliminate generated by gnatelim. If these pragmas are placed in
-:file:`gnat.adc` file located in your current directory, just do:
-::
-$ gnatmake -f main_prog
-(Use the :switch:`-f` option for ``gnatmake`` to
-recompile everything
-with the set of pragmas ``Eliminate`` that you have obtained with
-``gnatelim``).
-Be aware that the set of ``Eliminate`` pragmas is specific to each
-program. It is not recommended to merge sets of ``Eliminate``
-pragmas created for different programs in one configuration file.
-.. _Summary_of_the_gnatelim_Usage_Cycle:
-Summary of the ``gnatelim`` Usage Cycle
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Here is a quick summary of the steps to be taken in order to reduce
-the size of your executables with ``gnatelim``. You may use
-other GNAT options to control the optimization level,
-to produce the debugging information, to set search path, etc.
-* Create a complete set of :file:`ALI` files (if the program has not been
-built already)
-::
-$ gnatmake -c main_prog
-* Generate a list of ``Eliminate`` pragmas in default configuration file
-:file:`gnat.adc` in the current directory
-::
-$ gnatelim main_prog >[>] gnat.adc
-* Recompile the application
-::
-$ gnatmake -f main_prog
 .. index:: Overflow checks
 .. index:: Checks (overflow)
 .. index:: System.Dim.Mks package (GNAT library)
 .. index:: MKS_Type type
 The simplest way to impose dimensionality checking on a computation is to make
-use of the package ``System.Dim.Mks``,
+use of one of the instantiations of the package ``System.Dim.Generic_Mks``, which
-which is part of the GNAT library. This
+are part of the GNAT library. This generic package defines a floating-point
-package defines a floating-point type ``MKS_Type``,
+type ``MKS_Type``, for which a sequence of dimension names are specified,
-for which a sequence of
+together with their conventional abbreviations.  The following should be read
-dimension names are specified, together with their conventional abbreviations.
+together with the full specification of the package, in file
-The following should be read together with the full specification of the
+:file:`s-digemk.ads`.
-package, in file :file:`s-dimmks.ads`.
+.. index:: s-digemk.ads file
-.. index:: s-dimmks.ads file
+.. code-block:: ada
-.. code-block:: ada
+type Mks_Type is new Float_Type
-type Mks_Type is new Long_Long_Float
 with
 Dimension_System => (
 (Unit_Name => Meter,    Unit_Symbol => 'm',   Dim_Symbol => 'L'),
 (Unit_Name => Kilogram, Unit_Symbol => "kg",  Dim_Symbol => 'M'),
 (Unit_Name => Second,   Unit_Symbol => 's',   Dim_Symbol => 'T'),
 g   : constant Mass   := 1.0E-03;
 min : constant Time   := 60.0;
 day : constant Time   := 60.0 * 24.0 * min;
 ...
-Using this package, you can then define a derived unit by
+There are three instantiations of ``System.Dim.Generic_Mks`` defined in the
-providing the aspect that
+GNAT library:
-specifies its dimensions within the MKS system, as well as the string to
-be used for output of a value of that unit:
+* ``System.Dim.Float_Mks`` based on ``Float`` defined in :file:`s-diflmk.ads`.
+* ``System.Dim.Long_Mks`` based on ``Long_Float`` defined in :file:`s-dilomk.ads`.
+* ``System.Dim.Mks`` based on ``Long_Long_Float`` defined in :file:`s-dimmks.ads`.
+Using one of these packages, you can then define a derived unit by providing
+the aspect that specifies its dimensions within the MKS system, as well as the
+string to be used for output of a value of that unit:
 .. code-block:: ada
 subtype Acceleration is Mks_Type
 with Dimension => ("m/sec^2",
 Units compiled with this option will generate extra instructions to check
 that any use of the stack (for procedure calls or for declaring local
 variables in declare blocks) does not exceed the available stack space.
 If the space is exceeded, then a ``Storage_Error`` exception is raised.
-For declared tasks, the stack size is controlled by the size
+For declared tasks, the default stack size is defined by the GNAT runtime,
-given in an applicable ``Storage_Size`` pragma or by the value specified
+whose size may be modified at bind time through the ``-d`` bind switch
-at bind time with ``-d`` (:ref:`Switches_for_gnatbind`) or is set to
+(:ref:`Switches_for_gnatbind`). Task specific stack sizes may be set using the
-the default size as defined in the GNAT runtime otherwise.
+``Storage_Size`` pragma.
-.. index:: GNAT_STACK_LIMIT
+For the environment task, the stack size is determined by the operating system.
+Consequently, to modify the size of the environment task please refer to your
-For the environment task, the stack size depends on
+operating system documentation.
-system defaults and is unknown to the compiler. Stack checking
-may still work correctly if a fixed
-size stack is allocated, but this cannot be guaranteed.
-To ensure that a clean exception is signalled for stack
-overflow, set the environment variable
-:envvar:`GNAT_STACK_LIMIT` to indicate the maximum
-stack area that can be used, as in:
-::
-$ SET GNAT_STACK_LIMIT 1600
-The limit is given in kilobytes, so the above declaration would
-set the stack limit of the environment task to 1.6 megabytes.
-Note that the only purpose of this usage is to limit the amount
-of stack used by the environment task. If it is necessary to
-increase the amount of stack for the environment task, then this
-is an operating systems issue, and must be addressed with the
-appropriate operating systems commands.
 .. _Static_Stack_Usage_Analysis:
 Static Stack Usage Analysis
 * *Stack Usage* is the measure done by the stack analyzer.
 In order to prevent overflow, the stack
 is not entirely analyzed, and it's not possible to know exactly how
 much has actually been used.
-The environment task stack, e.g., the stack that contains the main unit, is
+By default the environment task stack, the stack that contains the main unit,
-only processed when the environment variable GNAT_STACK_LIMIT is set.
+is not processed. To enable processing of the environment task stack, the
+environment variable GNAT_STACK_LIMIT needs to be set to the maximum size of
+the environment task stack. This amount is given in kilobytes. For example:
+::
+$ set GNAT_STACK_LIMIT 1600
+would specify to the analyzer that the environment task stack has a limit
+of 1.6 megabytes. Any stack usage beyond this will be ignored by the analysis.
 The package ``GNAT.Task_Stack_Usage`` provides facilities to get
-stack usage reports at run-time. See its body for the details.
+stack-usage reports at run time. See its body for the details.
 .. _Memory_Management_Issues:

Mercurial > hg > CbC > CbC_gcc

comparison gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst @ 131:84e7813d76e9