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

comparison gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst @ 145:1830386684a0

gcc-9.2.0

author	anatofuz
date	Thu, 13 Feb 2020 11:34:05 +0900
parents	84e7813d76e9
children

comparison

equal deleted inserted replaced

-:84e7813d76e9
+:1830386684a0
 Running GDB
 -----------
 This section describes how to initiate the debugger.
-The debugger can be launched from a ``GPS`` menu or
+The debugger can be launched from a ``GNAT Studio`` menu or
 directly from the command line. The description below covers the latter use.
-All the commands shown can be used in the ``GPS`` debug console window,
+All the commands shown can be used in the ``GNAT Studio`` debug console window,
 but there are usually more GUI-based ways to achieve the same effect.
 The command to run ``GDB`` is
 ::
 .. _Profiling:
 Profiling
 =========
-This section describes how to use the the ``gprof`` profiler tool on Ada
+This section describes how to use the ``gprof`` profiler tool on Ada programs.
-programs.
 .. index:: !  gprof
 .. index:: Profiling
 .. _Profiling_an_Ada_Program_with_gprof:
 This section presents several topics related to program performance.
 It first describes some of the tradeoffs that need to be considered
 and some of the techniques for making your program run faster.
-.. only:: PRO or GPL
+It then documents the unused subprogram/data elimination feature,
+which can reduce the size of program executables.
-It then documents the unused subprogram/data elimination feature
-and the ``gnatelim`` tool,
-which can reduce the size of program executables.
-.. only:: FSF
-It then documents the unused subprogram/data elimination feature,
-which can reduce the size of program executables.
 .. _Performance_Considerations:
 Performance Considerations
 --------------------------
 It can be observed that the procedure ``Unused`` and the object
 ``Unused_Data`` are removed by the linker when using the
 appropriate options.
-.. only:: PRO or GPL
-.. _Reducing_Size_of_Ada_Executables_with_gnatelim:
-Reducing Size of Ada Executables with ``gnatelim``
---------------------------------------------------
-.. index:: gnatelim
-This section describes ``gnatelim``, a tool which detects unused
-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 {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``
-^^^^^^^^^^^^^^^^^^
-When a program shares a set of Ada
-packages with other programs, it may happen that this program uses
-only a fraction of the subprograms defined in these packages. The code
-created for these unused subprograms increases the size of the executable.
-``gnatelim`` tracks unused subprograms in an Ada program and
-outputs a list of GNAT-specific pragmas ``Eliminate`` marking all the
-subprograms that are declared but never called. By placing the list of
-``Eliminate`` pragmas in the GNAT configuration file :file:`gnat.adc` and
-recompiling your program, you may decrease the size of its executable,
-because the compiler will not generate the code for 'eliminated' subprograms.
-See ``Pragma_Eliminate`` in the :title:`GNAT_Reference_Manual` for more
-information about this pragma.
-``gnatelim`` needs as its input data the name of the main subprogram.
-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.
-If ``gnatelim`` is called with a project file and :samp:`-U` option is
-used, then in process all the files from the argument project but
-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.
-.. _Running_gnatelim:
-Running ``gnatelim``
-^^^^^^^^^^^^^^^^^^^^
-``gnatelim`` has the following command-line interface:
-::
-$ gnatelim [switches] -main=`main_unit_name {filename} [-cargs gcc_switches]
-``main_unit_name`` should be a name of a source file that contains the main
-subprogram of a program (partition).
-Each ``filename`` is the name (including the extension) of a source
-file to process. 'Wildcards' are allowed, and
-the file name may contain path information.
-``gcc_switches`` is a list of switches for
-``gcc``. They will be passed on to all compiler invocations made by
-``gnatelim`` to generate the ASIS trees. Here you can provide
-:switch:`-I` switches to form the source search path,
-use the :switch:`-gnatec` switch to set the configuration file,
-use the :switch:`-gnat05` switch if sources should be compiled in
-Ada 2005 mode etc.
-``gnatelim`` has the following switches:
-.. index:: --version (gnatelim)
-:samp:`--version`
-Display Copyright and version, then exit disregarding all other options.
-.. index:: --help (gnatelim)
-:samp:`--help`
-Display usage, then exit disregarding all other options.
-.. index:: -P (gnatelim)
-:samp:`-P {file}`
-Indicates the name of the project file that describes the set of sources
-to be processed.
-.. index:: -X (gnatelim)
-:samp:`-X{name}={value}`
-Indicates that external variable ``name`` in the argument project
-has the value ``value``. Has no effect if no project is specified as
-tool argument.
-.. index:: --RTS (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
-line breaks. You can use this switch more than once in the same call to
-``gnatelim``. You also can combine this switch with
-an explicit list of files.
-.. index:: -log (gnatelim)
-:samp:`-log`
-Duplicate all the output sent to :file:`stderr` into a log file. The log file
-is named :file:`gnatelim.log` and is located in the current directory.
-.. index:: --no-elim-dispatch (gnatelim)
-:samp:`--no-elim-dispatch`
-Do not generate pragmas for dispatching operations.
-.. index:: --ignore (gnatelim)
-:samp:`--ignore={filename}`
-Do not generate pragmas for subprograms declared in the sources
-listed in a specified file
-.. index:: -o (gnatelim)
-:samp:`-o={report_file}`
-Put ``gnatelim`` output into a specified file. If this file already exists,
-it is overridden. If this switch is not used, ``gnatelim`` outputs its results
-into :file:`stderr`
-.. index:: -j (gnatelim)
-: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`
-Quiet mode: by default ``gnatelim`` outputs to the standard error
-stream the number of program units left to be processed. This option turns
-this trace off.
-.. index:: -t (gnatelim)
-:samp:`-t`
-Print out execution time.
-.. index:: -v (gnatelim)
-:samp:`-v`
-Verbose mode: ``gnatelim`` version information is printed as Ada
-comments to the standard output stream. Also, in addition to the number of
-program units left ``gnatelim`` will output the name of the current unit
-being processed.
-.. index:: -wq (gnatelim)
-:samp:`-wq`
-Quiet warning mode - some warnings are suppressed. In particular warnings that
-indicate that the analysed set of sources is incomplete to make up a
-partition and that some subprogram bodies are missing are not generated.
-.. _Processing_Precompiled_Libraries:
-Processing Precompiled Libraries
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-If some program uses a precompiled Ada library, it can be processed by
-``gnatelim`` in a usual way. ``gnatelim`` will newer generate an
-Eliminate pragma for a subprogram if the body of this subprogram has not
-been analysed, this is a typical case for subprograms from precompiled
-libraries. Switch :switch:`-wq` may be used to suppress
-warnings about missing source files and non-analyzed subprogram bodies
-that can be generated when processing precompiled Ada libraries.
-.. _Correcting_the_List_of_Eliminate_Pragmas:
-Correcting the List of Eliminate Pragmas
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-In some rare cases ``gnatelim`` may try to eliminate
-subprograms that are actually called in the program. In this case, the
-compiler will generate an error message of the form:
-::
-main.adb:4:08: cannot reference subprogram "P" eliminated at elim.out:5
-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
-the generated set of pragmas may contain pragmas for subprograms that
-does not belong to the closure of the argument main subprogram. These
-pragmas has no effect when the set of pragmas is used to reduce the size
-of executable.
 .. index:: Overflow checks
 .. index:: Checks (overflow)
 .. _Overflow_Check_Handling_in_GNAT:
 automatically include an appropriate arbitrary precision
 integer arithmetic package. The compiler will make calls
 to this package, though only in cases where it cannot be
 sure that ``Long_Long_Integer`` is sufficient to guard against
 intermediate overflows. This package does not use dynamic
-alllocation, but it does use the secondary stack, so an
+allocation, but it does use the secondary stack, so an
 appropriate secondary stack package must be present (this
 is always true for standard full Ada, but may require
 specific steps for restricted run times such as ZFP).
 Although ``ELIMINATED`` mode causes expressions to use arbitrary
 ::
 $ gnatbind -u0 file
-With this option, at each task termination, its stack usage is  output on
+With this option, at each task termination, its stack usage is output on
 :file:`stderr`.
+Note that this switch is not compatible with tools like
+Valgrind and DrMemory; they will report errors.
 It is not always convenient to output the stack usage when the program
 is still running. Hence, it is possible to delay this output until program
 termination. for a given number of tasks specified as the argument of the
 ``-u`` option. For instance:
 The ``gnatmem`` command has the form
 ::
-$ gnatmem [ switches ] user_program
+$ gnatmem [ switches ] [ DEPTH ] user_program
 The program must have been linked with the instrumented version of the
 allocation and deallocation routines. This is done by linking with the
 :file:`libgmem.a` library. For correct symbolic backtrace information,
 the user program should be compiled with debugging options
 :samp:`-q`
 Quiet. Gives the minimum output needed to identify the origin of the
 memory leaks. Omits statistical information.
-.. index:: N switch (gnatmem)
+.. index:: DEPTH switch (gnatmem)
-:samp:`{N}`
+:samp:`{DEPTH}`
-``N`` is an integer literal (usually between 1 and 10) which controls the
+``DEPTH`` is an integer literal (usually between 1 and 10) which controls
-depth of the backtraces defining allocation root. The default value for
+the depth of the backtraces defining allocation root. The default value for
-N is 1. The deeper the backtrace, the more precise the localization of
+DEPTH is 1. The deeper the backtrace, the more precise the localization of
 the root. Note that the total number of roots can depend on this
-parameter. This parameter must be specified *before* the name of the
+parameter, in other words there may be more roots when the requested
-executable to be analyzed, to avoid ambiguity.
+backtrace depth is higher. This parameter must be specified *before* the
+name of the executable to be analyzed, to avoid ambiguity.
 .. index:: -b (gnatmem)
 :samp:`-b {N}`

Mercurial > hg > CbC > CbC_gcc

comparison gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst @ 145:1830386684a0