Reducing Size of Ada Executables with gnatelim
* About gnatelim::
* Running gnatelim::
+* Processing Precompiled Libraries::
* Correcting the List of Eliminate Pragmas::
* Making Your Executables Smaller::
* Summary of the gnatelim Usage Cycle::
@menu
* About gnatelim::
* Running gnatelim::
+* Processing Precompiled Libraries::
* Correcting the List of Eliminate Pragmas::
* Making Your Executables Smaller::
* Summary of the gnatelim Usage Cycle::
@xref{Pragma Eliminate,,, gnat_rm, GNAT Reference Manual}, for more
information about this pragma.
-@code{gnatelim} needs as its input data the name of the main subprogram
-and a bind file for a main subprogram.
+@code{gnatelim} needs as its input data the name of the main subprogram.
-To create a bind file for @code{gnatelim}, run @code{gnatbind} for
-the main subprogram. @code{gnatelim} can work with both Ada and C
-bind files; when both are present, it uses the Ada bind file.
-The following commands will build the program and create the bind file:
+If a set of source files is specified as @code{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 @code{gnatelim} can be
+called without specifying sources to analyse, in this case it computes
+the source closure of the main unit from the @file{ALI} files.
+
+The following command will create the set of @file{ALI} files needed for
+@code{gnatelim}:
@smallexample
$ gnatmake ^-c Main_Prog^/ACTIONS=COMPILE MAIN_PROG^
-$ gnatbind main_prog
@end smallexample
-Note that @code{gnatelim} needs neither object nor ALI files.
+Note that @code{gnatelim} does not need object files.
@node Running gnatelim
@subsection Running @code{gnatelim}
@code{gnatelim} has the following command-line interface:
@smallexample
-$ gnatelim [@var{options}] name
+$ gnatelim [@var{switches}] ^-main^?MAIN^=@var{main_unit_name} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]}
@end smallexample
@noindent
-@code{name} should be a name of a source file that contains the main subprogram
-of a program (partition).
+@var{main_unit_name} should be a name of a source file that contains the main
+subprogram of a program (partition).
+
+Each @var{filename} is the name (including the extension) of a source
+file to process. ``Wildcards'' are allowed, and
+the file name may contain path information.
+
+@samp{-cargs @var{gcc_switches}} is a list of switches for
+@command{gcc}. They will be passed on to all compiler invocations made by
+@command{gnatelim} to generate the ASIS trees. Here you can provide
+@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
+use the @option{-gnatec} switch to set the configuration file etc.
@code{gnatelim} has the following switches:
@table @option
@c !sort!
+@item ^-files^/FILES^=@var{filename}
+@cindex @option{^-files^/FILES^} (@code{gnatelim})
+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
+@command{gnatelim}. You also can combine this switch with
+an explicit list of files.
+
+@item ^-log^/LOG^
+@cindex @option{^-log^/LOG^} (@command{gnatelim})
+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.
+
+@item ^-log^/LOGFILE^=@var{filename}
+@cindex @option{^-log^/LOGFILE^} (@command{gnatelim})
+Duplicate all the output sent to @file{stderr} into a specified log file.
+
+@cindex @option{^-o^/OUTPUT^} (@command{gnatelim})
+@item ^-o^/OUTPUT^=@var{report_file}
+Put @command{gnatelim} output into a specified file. If this file already exists,
+it is overridden. If this switch is not used, @command{gnatelim} outputs its results
+into @file{stderr}
+
@item ^-q^/QUIET^
@cindex @option{^-q^/QUIET^} (@command{gnatelim})
Quiet mode: by default @code{gnatelim} outputs to the standard error
stream the number of program units left to be processed. This option turns
this trace off.
+@cindex @option{^-t^/TIME^} (@command{gnatelim})
+@item ^-t^/TIME^
+Print out execution time.
+
@item ^-v^/VERBOSE^
@cindex @option{^-v^/VERBOSE^} (@command{gnatelim})
Verbose mode: @code{gnatelim} version information is printed as Ada
program units left @code{gnatelim} will output the name of the current unit
being processed.
-@item ^-a^/ALL^
-@cindex @option{^-a^/ALL^} (@command{gnatelim})
-Also look for subprograms from the GNAT run time that can be eliminated. Note
-that when @file{gnat.adc} is produced using this switch, the entire program
-must be recompiled with switch @option{^-a^/ALL_FILES^} to @command{gnatmake}.
-
-@item ^-I^/INCLUDE_DIRS=^@var{dir}
-@cindex @option{^-I^/INCLUDE_DIRS^} (@command{gnatelim})
-When looking for source files also look in directory @var{dir}. Specifying
-@option{^-I-^/INCLUDE_DIRS=-^} instructs @code{gnatelim} not to look for
-sources in the current directory.
-
-@item ^-b^/BIND_FILE=^@var{bind_file}
-@cindex @option{^-b^/BIND_FILE^} (@command{gnatelim})
-Specifies @var{bind_file} as the bind file to process. If not set, the name
-of the bind file is computed from the full expanded Ada name
-of a main subprogram.
-
-@item ^-C^/CONFIG_FILE=^@var{config_file}
-@cindex @option{^-C^/CONFIG_FILE^} (@command{gnatelim})
-Specifies a file @var{config_file} that contains configuration pragmas. The
-file must be specified with full path.
-
-@item ^--GCC^/COMPILER^=@var{compiler_name}
-@cindex @option{^-GCC^/COMPILER^} (@command{gnatelim})
-Instructs @code{gnatelim} to use specific @command{gcc} compiler instead of one
-available on the path.
-
-@item ^--GNATMAKE^/GNATMAKE^=@var{gnatmake_name}
-@cindex @option{^--GNATMAKE^/GNATMAKE^} (@command{gnatelim})
-Instructs @code{gnatelim} to use specific @command{gnatmake} instead of one
-available on the path.
+@item ^-wq^/WARNINGS=QUIET^
+@cindex @option{^-wq^/WARNINGS=QUIET^} (@command{gnatelim})
+Quet 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.
@end table
-@noindent
-@code{gnatelim} sends its output to the standard output stream, and all the
-tracing and debug information is sent to the standard error stream.
-In order to produce a proper GNAT configuration file
-@file{gnat.adc}, redirection must be used:
+@node Processing Precompiled Libraries
+@subsection Processing Precompiled Libraries
-@smallexample
-@ifset vms
-$ PIPE GNAT ELIM MAIN_PROG.ADB > GNAT.ADC
-@end ifset
-@ifclear vms
-$ gnatelim main_prog.adb > gnat.adc
-@end ifclear
-@end smallexample
-
-@ifclear vms
@noindent
-or
-
-@smallexample
-$ gnatelim main_prog.adb >> gnat.adc
-@end smallexample
-
-@noindent
-in order to append the @code{gnatelim} output to the existing contents of
-@file{gnat.adc}.
-@end ifclear
+If some program uses a precompiled Ada library, it can be processed by
+@code{gnatelim} in a usual way. @code{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 @option{^-wq^/WARNINGS=QUIET^} may be used to suppress
+warnings about missing source files and non-analyzed subprogram bodies
+that can be generated when processing precompiled Ada libraries.
@node Correcting the List of Eliminate Pragmas
@subsection Correcting the List of Eliminate Pragmas
compiler will generate an error message of the form:
@smallexample
-file.adb:106:07: cannot call eliminated subprogram "My_Prog"
+main.adb:4:08: cannot reference subprogram "P" eliminated at elim.out:5
@end smallexample
@noindent
You will need to manually remove the wrong @code{Eliminate} pragmas from
-the @file{gnat.adc} file. You should recompile your program
-from scratch after that, because you need a consistent @file{gnat.adc} file
-during the entire compilation.
+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.
@node Making Your Executables Smaller
@subsection Making Your Executables Smaller
@noindent
In order to get a smaller executable for your program you now have to
-recompile the program completely with the new @file{gnat.adc} file
-created by @code{gnatelim} in your current directory:
+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:
@smallexample
$ gnatmake ^-f main_prog^/FORCE_COMPILE MAIN_PROG^
Be aware that the set of @code{Eliminate} pragmas is specific to each
program. It is not recommended to merge sets of @code{Eliminate}
-pragmas created for different programs in one @file{gnat.adc} file.
+pragmas created for different programs in one configuration file.
@node Summary of the gnatelim Usage Cycle
-@subsection Summary of the gnatelim Usage Cycle
+@subsection Summary of the @code{gnatelim} Usage Cycle
@noindent
Here is a quick summary of the steps to be taken in order to reduce
@enumerate
@item
-Produce a bind file
+Create a complete set of @file{ALI} files (if the program has not been
+built already)
@smallexample
$ gnatmake ^-c main_prog^/ACTIONS=COMPILE MAIN_PROG^
-$ gnatbind main_prog
@end smallexample
@item
-Generate a list of @code{Eliminate} pragmas
+Generate a list of @code{Eliminate} pragmas in default configuration file
+@file{gnat.adc} in the current directory
@smallexample
@ifset vms
$ PIPE GNAT ELIM MAIN_PROG > GNAT.ADC
The additional @command{gnatpp} switches are defined in this subsection.
@table @option
-@item ^-files @var{filename}^/FILES=@var{output_file}^
+@item ^-files @var{filename}^/FILES=@var{filename}^
@cindex @option{^-files^/FILES^} (@code{gnatpp})
Take the argument source files from the specified file. This file should be an
ordinary text file containing file names separated by spaces or
@end table
-@noindent
-Note that if any of the options @option{^-s1^/COMPILER_STYLE^},
-@option{^-s2^/BY_RULES^} or
-@option{^-s3^/BY_FILES_BY_RULES^} is specified,
-then the @command{gnatcheck} report file will only contain sections
-explicitly denoted by these options.
-
@node gnatcheck Rule Options
@section @command{gnatcheck} Rule Options
--
-- Duplicate all the output sent to Stderr into a log file.
- S_Check_Sections : aliased constant S := "/SECTIONS=" &
- "DEFAULT " &
- "-s123 " &
- "COMPILER_STYLE " &
- "-s1 " &
- "BY_RULES " &
- "-s2 " &
- "BY_FILES_BY_RULES " &
- "-s3";
- -- /SECTIONS[=section-option, section-option, ...]
- --
- -- Specify what sections should be included into the report file.
- -- By default, all three section (diagnoses in the format corresponding
- -- to compiler error and warning messages, diagnoses grouped by rules and
- -- then - by files, diagnoses grouped by files and then - by rules) are
- -- included in the report file.
- --
- -- section-option may be one of the following:
- --
- -- COMPILER_STYLE Include diagnostics in compile-style format
- -- (diagnoses are grouped by files, for each file
- -- they are ordered according to the references
- -- into the source)
- -- BY_RULES Include diagnostics grouped first by rules and
- -- then by files
- -- BY_FILES_BY_RULES Include diagnostics grouped first by files and
- -- then by rules
- --
- -- If one of these options is specified, then the report file contains
- -- only sections set by these options
-
S_Check_Short : aliased constant S := "/SHORT " &
"-s";
-- /NOSHORT (D)
--
-- Generate a short form of the report file.
+ S_Check_Include : aliased constant S := "/INCLUDE_FILE=@" &
+ "--include-file=@";
+
+ -- /INCLUDE_FILE=filename
+ --
+ -- Add the content of the specified text file to the generated report
+ -- file.
+
S_Check_Subdirs : aliased constant S := "/SUBDIRS=<" &
"--subdirs=>";
-- /SUBDIRS=dir
-- Specify the name of the output file.
Check_Switches : aliased constant Switches :=
- (S_Check_Add 'Access,
- S_Check_All 'Access,
- S_Diagnosis 'Access,
- S_Check_Ext 'Access,
- S_Check_Files 'Access,
- S_Check_Follow 'Access,
- S_Check_Help 'Access,
- S_Check_Locs 'Access,
- S_Check_Mess 'Access,
- S_Check_Project 'Access,
- S_Check_Quiet 'Access,
- S_Check_Time 'Access,
- S_Check_Log 'Access,
- S_Check_Sections 'Access,
- S_Check_Short 'Access,
- S_Check_Subdirs 'Access,
- S_Check_Verb 'Access,
- S_Check_Out 'Access);
+ (S_Check_Add 'Access,
+ S_Check_All 'Access,
+ S_Diagnosis 'Access,
+ S_Check_Ext 'Access,
+ S_Check_Files 'Access,
+ S_Check_Follow 'Access,
+ S_Check_Help 'Access,
+ S_Check_Locs 'Access,
+ S_Check_Mess 'Access,
+ S_Check_Project'Access,
+ S_Check_Quiet 'Access,
+ S_Check_Time 'Access,
+ S_Check_Log 'Access,
+ S_Check_Short 'Access,
+ S_Check_Include'Access,
+ S_Check_Subdirs'Access,
+ S_Check_Verb 'Access,
+ S_Check_Out 'Access);
----------------------------
-- Switches for GNAT CHOP --
-- gnatelim. The source directories to be searched will be communicated
-- to gnatelim through logical name ADA_PRJ_INCLUDE_FILE.
- S_Elim_Quiet : aliased constant S := "/QUIET " &
+ S_Elim_Quiet : aliased constant S := "/QUIET " &
"-q";
-- /NOQUIET (D)
-- /QUIET
-- the number of program units left to be processed. This option turns
-- this trace off.
+ S_Elim_Files : aliased constant S := "/FILES=@" &
+ "-files=@";
+
+ -- /FILES=filename
+ --
+ -- Take as arguments the files that are listed in the specified
+ -- text file.
+
+ S_Elim_Log : aliased constant S := "/LOG " &
+ "-l";
+ -- /NOLOG (D)
+ -- /LOG
+ --
+ -- Duplicate all the output sent to Stderr into a default log file.
+
+ S_Elim_Logfile : aliased constant S := "/LOGFILE=@ " &
+ "-l@";
+
+ -- /LOGFILE=logfilename
+ --
+ -- Duplicate all the output sent to Stderr into a specified log file.
+
+ S_Elim_Main : aliased constant S := "/MAIN=@ " &
+ "-main=@";
+
+ -- /MAIN=filename
+ --
+ -- Specify the main subprogram of the partition to analyse.
+
+ S_Elim_Out : aliased constant S := "/OUTPUT=@" &
+ "-o@";
+ -- /OUTPUT=filename
+ --
+ -- Specify the name of the output file.
+
+ S_Elim_Time : aliased constant S := "/TIME " &
+ "-t";
+ -- /NOTIME (D)
+ -- /TIME
+ --
+ -- Print out execution time
+
S_Elim_Search : aliased constant S := "/SEARCH=*" &
"-I*";
-- /SEARCH=(directory, ...)
-- program units left, GNAT ELIM will output the name of the current unit
-- being processed.
+ S_Elim_Warn : aliased constant S := "/WARNINGS=" &
+ "NORMAL " &
+ "-wn " &
+ "QUIET " &
+ "-ws";
+
+ -- /WARNINGS[=(keyword[,...])]
+ --
+ -- The following keywords are supported:
+ --
+ -- NORMAL (D) Print warning all the messages.
+ -- QUIET Some warning messages are suppressed
+
Elim_Switches : aliased constant Switches :=
(S_Elim_Add 'Access,
S_Elim_All 'Access,
S_Elim_Config 'Access,
S_Elim_Current 'Access,
S_Elim_Ext 'Access,
+ S_Elim_Files 'Access,
S_Elim_Follow 'Access,
S_Elim_GNATMAKE'Access,
+ S_Elim_Log 'Access,
+ S_Elim_Logfile 'Access,
+ S_Elim_Main 'Access,
S_Elim_Mess 'Access,
+ S_Elim_Out 'Access,
S_Elim_Project 'Access,
S_Elim_Quiet 'Access,
S_Elim_Search 'Access,
S_Elim_Subdirs 'Access,
- S_Elim_Verb 'Access);
+ S_Elim_Time 'Access,
+ S_Elim_Verb 'Access,
+ S_Elim_Warn 'Access);
----------------------------
-- Switches for GNAT FIND --
projects / platform / upstream / gcc.git / commitdiff