Skip to content

R
riscv-gcc-1
Commit 27af94e7 by Arnaud Charlet Committed by Pierre-Marie de Rodat
Options

[Ada] Remove documentation of gnatelim 

2019-08-14  Arnaud Charlet  <charlet@adacore.com>

gcc/ada/

	* doc/gnat_ugn/gnat_and_program_execution.rst: Remove
	documentation of gnatelim.

From-SVN: r274462
parent 3a02b469
Showing with 7 additions and 267 deletions
gcc/ada/ChangeLog
2019-08-14 Arnaud Charlet <charlet@adacore.com>
* doc/gnat_ugn/gnat_and_program_execution.rst: Remove
documentation of gnatelim.
2019-08-14 Bob Duff <duff@adacore.com> 2019-08-14 Bob Duff <duff@adacore.com>
* sem_prag.adb (Validate_Compile_Time_Warning_Error): Attach the * sem_prag.adb (Validate_Compile_Time_Warning_Error): Attach the
......
gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst
...@@ -1406,18 +1406,8 @@ This section presents several topics related to program performance. ...@@ -1406,18 +1406,8 @@ This section presents several topics related to program performance.
It first describes some of the tradeoffs that need to be considered It first describes some of the tradeoffs that need to be considered
and some of the techniques for making your program run faster. 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:
...@@ -2596,261 +2586,6 @@ It can be observed that the procedure ``Unused`` and the object ...@@ -2596,261 +2586,6 @@ It can be observed that the procedure ``Unused`` and the object
``Unused_Data`` are removed by the linker when using the ``Unused_Data`` are removed by the linker when using the
appropriate options. 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:: Overflow checks
.. index:: Checks (overflow) .. index:: Checks (overflow)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment