gnat_ugn.texi, [...]: Update gnatelim doc.

2010-06-14  Sergey Rybin  <rybin@adacore.com>

	* gnat_ugn.texi, vms_data.ads: Update gnatelim doc.

From-SVN: r160739

3 files changed, 176 insertions, 138 deletions

diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog
index 53a2c3b..5d4d98a 100644
--- a/gcc/ada/ChangeLog
+++ b/gcc/ada/ChangeLog
@@ -1,3 +1,7 @@
+2010-06-14  Sergey Rybin  <rybin@adacore.com>
+
+	* gnat_ugn.texi, vms_data.ads: Update gnatelim doc.
+
 2010-06-14  Thomas Quinot  <quinot@adacore.com>
 
 	* lib-util.adb: Minor code reorganization.
diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
index b1831da..1580d66 100644
--- a/gcc/ada/gnat_ugn.texi
+++ b/gcc/ada/gnat_ugn.texi
@@ -347,6 +347,7 @@ Performance Considerations
 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::
@@ -10694,6 +10695,7 @@ program.
 @menu
 * About gnatelim::
 * Running gnatelim::
+* Processing Precompiled Libraries::
 * Correcting the List of Eliminate Pragmas::
 * Making Your Executables Smaller::
 * Summary of the gnatelim Usage Cycle::
@@ -10717,20 +10719,24 @@ because the compiler will not generate the code for 'eliminated' subprograms.
 @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}
@@ -10739,23 +10745,60 @@ Note that @code{gnatelim} needs neither object nor ALI files.
 @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
@@ -10763,67 +10806,24 @@ comments to the standard output stream. Also, in addition to the number of
 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
@@ -10834,22 +10834,23 @@ subprograms that are actually called in the program. In this case, the
 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^
@@ -10863,10 +10864,10 @@ with the set of pragmas @code{Eliminate} that you have obtained with
 
 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
@@ -10876,15 +10877,16 @@ to produce the debugging information, to set search path, etc.
 
 @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
@@ -16675,7 +16677,7 @@ with @option{^-pipe^/STANDARD_OUTPUT^} option.
 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
@@ -20898,13 +20900,6 @@ Set name of report file file to @var{report_file} .
 
 @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
 
diff --git a/gcc/ada/vms_data.ads b/gcc/ada/vms_data.ads
index 6f4ae0f..d25f7a3 100644
--- a/gcc/ada/vms_data.ads
+++ b/gcc/ada/vms_data.ads
@@ -834,37 +834,6 @@ package VMS_Data is
    --
    --   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)
@@ -872,6 +841,14 @@ package VMS_Data is
    --
    --   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
@@ -896,24 +873,24 @@ package VMS_Data is
    --   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 --
@@ -3624,7 +3601,7 @@ package VMS_Data is
    --   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
@@ -3633,6 +3610,48 @@ package VMS_Data is
    --   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, ...)
@@ -3657,6 +3676,19 @@ package VMS_Data is
    --   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,
@@ -3665,14 +3697,21 @@ package VMS_Data is
                       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 --