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:
``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)
git://gcc.gnu.org / gcc.git / commitdiff