From 27af94e7b9a4702ea93348f917fd2ad82adb6853 Mon Sep 17 00:00:00 2001 From: Arnaud Charlet Date: Wed, 14 Aug 2019 09:52:01 +0000 Subject: [PATCH] [Ada] Remove documentation of gnatelim 2019-08-14 Arnaud Charlet gcc/ada/ * doc/gnat_ugn/gnat_and_program_execution.rst: Remove documentation of gnatelim. From-SVN: r274462 --- gcc/ada/ChangeLog | 5 + .../gnat_ugn/gnat_and_program_execution.rst | 269 +----------------- 2 files changed, 7 insertions(+), 267 deletions(-) diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog index 773b70523fd..b7bacdcd0ad 100644 --- a/gcc/ada/ChangeLog +++ b/gcc/ada/ChangeLog @@ -1,3 +1,8 @@ +2019-08-14 Arnaud Charlet + + * doc/gnat_ugn/gnat_and_program_execution.rst: Remove + documentation of gnatelim. + 2019-08-14 Bob Duff * sem_prag.adb (Validate_Compile_Time_Warning_Error): Attach the diff --git a/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst b/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst index de348e9e0b7..d2675c7c151 100644 --- a/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst +++ b/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst @@ -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 and some of the techniques for making your program run faster. -.. only:: PRO or GPL - - 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. - +It then documents the unused subprogram/data elimination feature, +which can reduce the size of program executables. .. _Performance_Considerations: @@ -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 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) -- 2.30.2