* [PATCH] gprofng: updated man pages and user guide
@ 2023-11-28 19:58 vladimir.mezentsev
0 siblings, 0 replies; only message in thread
From: vladimir.mezentsev @ 2023-11-28 19:58 UTC (permalink / raw)
To: binutils; +Cc: Vladimir Mezentsev
From: Vladimir Mezentsev <vladimir.mezentsev@oracle.com>
This is a major update of all the man pages. Bugs 30679 and 30895 are
addressed. In addition to fixes for typos, the texts have been expanded
and clarified, and line lengths no longer extend beyond column 79. In
case of gp-display-html, the new option syntax is documented. The user
guide has a new section on the gprofng GUI.
gprofng/ChangeLog
2023-11-28 Ruud van der Pas <ruud.vanderpas@oracle.com>
PR 30679
PR 30895
* doc/gp-archive.texi: Expand the description of the options.
* doc/gp-collect-app.texi: Fix various typos and textual improvements.
* doc/gp-display-html.texi: Cover the new GNU long option syntax.
* doc/gp-display-src.texi: Fix various typos and textual improvements.
* doc/gp-display-text.texi: Fix typos fixed and textual improvements.
* doc/gp-macros.texi: Fix a bug in the vspace macro and add new macro.
* doc/gprofng.texi: Cover the GPROFNG_SYSCONFDIR environment variable.
* doc/gprofng_ug.texi: Fix various typos and textual improvements.
* doc/version.texi: Adapt the date and version number.
---
gprofng/doc/gp-archive.texi | 260 +++++++++++++++++++++++++------
gprofng/doc/gp-collect-app.texi | 115 ++++++++------
gprofng/doc/gp-display-html.texi | 154 ++++++++++++------
gprofng/doc/gp-display-src.texi | 65 ++++----
gprofng/doc/gp-display-text.texi | 71 ++++++---
gprofng/doc/gp-macros.texi | 6 +
gprofng/doc/gprofng.texi | 112 ++++++++++---
gprofng/doc/gprofng_ug.texi | 114 +++++++++-----
gprofng/doc/version.texi | 6 +-
9 files changed, 635 insertions(+), 268 deletions(-)
diff --git a/gprofng/doc/gp-archive.texi b/gprofng/doc/gp-archive.texi
index 722a9546081..d57380e0a25 100644
--- a/gprofng/doc/gp-archive.texi
+++ b/gprofng/doc/gp-archive.texi
@@ -1,11 +1,11 @@
@c ----------------------------------------------------------------------------
-@c This is the Texinfo source file for the gp-collect-app man page.
+@c This is the Texinfo source file for the gp-archive man page.
@c
@c Author: Ruud van der Pas
@c ----------------------------------------------------------------------------
@ifset man
\input texinfo @c -*-texinfo-*-
-@setfilename gprofng archive
+@setfilename gp-archive
@settitle Archive gprofng experiment data
@include gp-macros.texi
@end ifset
@@ -54,7 +54,8 @@
@ManPageStart{NAME}
@c man begin NAME
-gprofng archive - Archive gprofng experiment data
+gp-archive - Archive the associated application binaries and sources for a
+gprofng experiment
@c man end
@ManPageEnd{}
@@ -81,9 +82,12 @@ gprofng archive - Archive gprofng experiment data
Archive the associated application binaries and source files in a gprofng
experiment to make it self contained and portable.
-By default, the binaries are archived, but the application source files
-are not archived. Use this tool to change this and afterwards archive
-additional components.
+By default, the binaries are archived as part of the data collection, but the
+application source files are not archived. Use this tool to change this and
+afterwards archive additional components.
+
+This tool has to be executed on the same system where the profiling data was
+recorded.
@c man end
@ManPageEnd{}
@@ -111,34 +115,39 @@ Print the version number and exit.
Print usage information and exit.
-@c -- @item --verbose @{on|off@}
-@c -- @ifclear man
-@c -- @IndexSubentry{Options, @code{--verbose}}
-@c -- @end ifclear
-
-@c -- Enable (on) or disable (off) verbose mode; the default is @samp{off}.
-
-@item -a @{off|on|ldobjects|src|usedldobjects|usedsrc@}
+@item -a @{off | on | ldobjects | src | usedldobjects | used[src]@}
@ifclear man
@IndexSubentry{Options, @code{-a}}
@end ifclear
Specify archiving of binaries and other files. In addition to disable this
-feature (off), or enable archiving off all loadobjects and sources (on),
-the other op tions support a more refined selection.
+feature (@samp{off}), or enable archiving of all loadobjects and sources
+(@samp{on}), the other choices support a more refined selection.
-All of these options enable archiving, but the keyword controls what exactly
-is selected: all load objects (ldobjects), all source files (src), the
-loadobjects asscoiated with a program counter (usedldobjects), or the source
-files associated with a program counter (usedsrc).
-The default is @samp{-a ldobjects}.
+All of these choices enable archiving, but the keyword controls what exactly
+is selected: all load objects (@samp{ldobjects}), all source files
+(@samp{src}), the loadobjects associated with a program counter
+(@samp{usedldobjects}), or the source files associated with a program counter
+(@samp{used[src]}). The default is @samp{-a ldobjects}.
-@item -n
+@item -d @var{path}
@ifclear man
-@IndexSubentry{Options, @code{-n}}
+@IndexSubentry{Options, @code{-d}}
@end ifclear
-Archive the named experiment only, not any of its descendants.
+The @var{path} is the absolute path to a common archive, which is a
+directory that contains archived files. If the directory does not
+exist, then it will be created. Files are saved in the common archive
+directory, and a symbolic link is created in the experiment archive.
+
+@item -F
+@ifclear man
+@IndexSubentry{Options, @code{-F}}
+@end ifclear
+
+Force writing, or rewriting of .archive files. All archived files will be
+removed and recreated, except if the @samp{-n} or @samp{-m} option is used,
+or if the experiment is a subexperiment.
@item -m @var{regex}
@ifclear man
@@ -148,32 +157,67 @@ Archive the named experiment only, not any of its descendants.
Archive only those source, object, and debug info files whose full path name
matches the given POSIX compliant @var{regex} regular expression.
+@item -n
+@ifclear man
+@IndexSubentry{Options, @code{-n}}
+@end ifclear
+
+Archive the named experiment only, not any of its descendants.
+
@item -q
@ifclear man
@IndexSubentry{Options, @code{-q}}
@end ifclear
-Do not write any warnings to stderr. Warnings are incorporated into the
-.archive file in the experiment directory. They are shown in the output
-of @command{gprofng display text}.
+Do not write any warnings to @file{stderr}. Warnings are incorporated into
+the .archive file in the experiment directory. They are shown in the output
+of the @command{gprofng display text} command.
-@item -F
+@item -r @var{path}
@ifclear man
-@IndexSubentry{Options, @code{-F}}
+@IndexSubentry{Options, @code{-r}}
@end ifclear
-Force writing or rewriting of the archive. This is ignored with the
-@samp{-n} or @samp{-m} option, or if this is a subexperiment.
+This option specifies the location of a common archive. The value is the
+relative path to a common archive, which is a directory that contains
+archived files.
+If the directory does not exist, then it will be created. Files are saved
+in the common archive directory, and a symbolic link is created in the
+experiment archive.
-@item -d @var{path}
+@item -s @var{selection}
@ifclear man
-@IndexSubentry{Options, @code{-d}}
+@IndexSubentry{Options, @code{-s}}
@end ifclear
-The @var{path} is the absolute path path to a common archive, which is a
-directory that contains archived files. If the directory does not
-exist, then it will be created. Files are saved in the common archive
-directory, and a symbolic link is created in the experiment archive.
+Specify archiving of source files. The allowed values for @var{selection} are:
+
+@table @gcctabopt
+
+@item no
+
+Do not archive any source files.
+
+@item all
+
+Archive all source and object files that can be found.
+
+@item used[src]
+
+Archive source and object files for functions against which data was
+recorded in the experiment, and that can be found.
+@end table
+
+By default, application source files are not archived into the experiment.
+If the @samp{-s all}, or @samp{-s used} option is used, sources and object
+files are archived.
+These options also ensure that source files are available in the experiment,
+even if the original source files have been modified, or are inaccessible
+afterwards.
+
+In case archive files cannot be found, use the @samp{addpath}, or
+@samp{pathmap} command, or both, in an @file{.er.rc} file to specify the
+location of the missing file(s).
@end table
@@ -187,17 +231,130 @@ directory, and a symbolic link is created in the experiment archive.
@ManPageStart{NOTES}
@c man begin NOTES
-Default archiving does not occur in case the application profiled terminates
-prematurely, or if archiving is disabled when collecting the performance data.
-In such cases, this tool can be used to afterwards archive the information,
-but it has to be run on the same system where the profiling data was recorded.
+@itemize @minus
+
+@c ----------------------------------------------------------------------------
+@item
+Archiving of application binaries -
+By default, binaries are archived automatically when an experiment is
+created. However, archiving does not occur in one or more of the
+following circumstances:
+
+@itemize @bullet
+
+@item
+If the profiled application is terminated before it exits normally.
+
+@item
+If a running process is profiled.
+
+@item
+If archiving is explicitly disabled when profiling. For example by using
+the @samp{-a off} option on @command{gprofng collect app}.
+
+@end itemize
+
+In these cases, @command{gprofng archive} must be run manually and on the same
+machine where the profiling data was recorded.
+
+Archiving of experiment data during the data collection process can be quite
+expensive. Especially if the experiment has many descendant processes.
+@ifclear man
+@IndexSubentry{Options, @code{-a}}
+@end ifclear
+In such cases, a more efficient strategy is to use the @samp{-a off} option
+when collecting the data. Once the collection has completed, the data can be
+@ifclear man
+@IndexSubentry{Options, @code{-s}}
+@end ifclear
+archived using the @samp{-s all} option. This saves all executables and
+source files in the experiment.
+
+If during the archiving there is an error message that an executable, or
+@ifclear man
+@IndexSubentry{Commands, @code{addpath}}
+@end ifclear
+source file cannot be found, the @samp{addpath} command to add the path
+to the missing file(s) can be included in the @file{.er.rc} file.
+After this command has been added, archive the experiment again. The
+archiving archiving can be repeated as many times as necessary to archive all
+files.
+
+Archiving should be done on the same system as was used to collect the
+experiment. If some files cannot be accessed from this system (e.g. sources
+or object files), then additional archiving can be done using another system
+that can access them. For example, the system where the application was built.
Some Java applications store shared objects in jar files. By default, such
shared objects are not automatically archived. To archive shared objects
-contained in jar files, the addpath directive in an .er.rc file. The addpath
-directive should give the path to the jar file, including the jar file itself.
-The .er.rc file should be saved in the user home directory or parent of the
-experiment directory.
+contained in jar files, make sure to include the @samp{addpath} command in
+an @file{.er.rc} file.
+The @samp{addpath} command should give the path to the jar file, including
+the jar file itself. The @file{.er.rc} file should be saved in the user home
+directory, or experiment parent directory.
+
+@item
+Archiving of application sources -
+By default, application source files are not archived in the experiment.
+Execute the @command{gprofng archive} command with the @samp{-s all}, or
+@samp{-s used} option on each experiment to store source files in the
+experiment.
+
+@item
+Automatic archiving of application sources -
+Environment variable @samp{GPROFNG_ARCHIVE} may be set to automatically
+archive sources when the experiment has completed. This environment
+variable can contain @samp{-s} and @samp{-m} arguments, as pairs of
+argument and options, separated by one or more blanks.
+@ifclear man
+@IndexSubentry{Environment variables, @code{GPROFNG_ARCHIVE}}
+@IndexSubentry{Options, @code{-a}}
+@IndexSubentry{Options, @code{-m}}
+@IndexSubentry{Options, @code{-s}}
+@end ifclear
+
+If more than one @samp{-s} argument appears on the command line, the
+last one prevails. If @samp{-s} is both passed on the command line, and
+set by the environment variable, the option from the environment variable
+prevails.
+
+Note that in case automatic source archiving during data collection has
+been enabled using either the @samp{GPROFNG_ARCHIVE} variable, or the
+@samp{-a src}, or @samp{-a usedsrc} option, it is recommended to confirm that
+source files have been correctly resolved by executing the
+@command{gprofng archive -s all}, or @command{gprofng archive -s used}
+command.
+
+@item
+The @samp{-d} and @samp{-r} options are mutually exclusive.
+@ifclear man
+@IndexSubentry{Options, @code{-d}}
+@IndexSubentry{Options, @code{-r}}
+@end ifclear
+
+@item
+When using the @samp{-d} or @samp{-r} option, environment variable
+@ifclear man
+@IndexSubentry{Options, @code{-d}}
+@IndexSubentry{Options, @code{-r}}
+@IndexSubentry{Environment variables, @code{GPROFNG_ARCHIVE_COMMON_DIR}}
+@end ifclear
+@samp{GPROFNG_ARCHIVE_COMMON_DIR} can be used to specify the location of
+the common archive. This can be very convenient when using a script to
+profile applications.
+
+@item
+If more than one @samp{-s} option is given on the command line, or
+specified in the environment variable, the specified option for all must
+be the same. If not, @command{gprofng archive} exits with an error.
+
+@item
+This tool does not work on experiments recorded with earlier versions of
+the tools. If invoked on such experiments, a warning is printed. Use the
+version of @command{gprofng archive} from the same release with which the
+experiment was recorded.
+
+@end itemize
@c man end
@ManPageEnd{}
@@ -206,10 +363,19 @@ experiment directory.
@c SEEALSO section
@c ----------------------------------------------------------------------------
-@ManPageStart{SEEALSO}
+@ManPageStart{SEE ALSO}
@c man begin SEEALSO
-gprofng(1), gp-collect-app(1), gp-display-html(1), gp-display-src(1), gp-display-text(1)
+gprofng(1),
+gp-collect-app(1),
+gp-display-gui(1),
+gp-display-html(1),
+gp-display-src(1),
+gp-display-text(1)
+
+@iftex
+@vspace{1}
+@end iftex
The user guide for gprofng is maintained as a Texinfo manual. If the info
and gprofng programs are correctly installed, the command
diff --git a/gprofng/doc/gp-collect-app.texi b/gprofng/doc/gp-collect-app.texi
index 7e81f8505e7..203827c38ea 100644
--- a/gprofng/doc/gp-collect-app.texi
+++ b/gprofng/doc/gp-collect-app.texi
@@ -5,7 +5,7 @@
@c ----------------------------------------------------------------------------
@ifset man
\input texinfo @c -*-texinfo-*-
-@setfilename gprofng collect app
+@setfilename gp-collect-app
@settitle Collect performance data for the target application
@include gp-macros.texi
@end ifset
@@ -54,7 +54,7 @@
@ManPageStart{NAME}
@c man begin NAME
-gprofng collect app - Collect performance data for the target program
+gp-collect-app - Collect performance data for the target program
@c man end
@ManPageEnd{}
@@ -66,7 +66,8 @@ gprofng collect app - Collect performance data for the target program
@ManPageStart{SYNOPSIS}
@c man begin SYNOPSIS
-@command{gprofng collect app} [@var{option(s)}] @var{target} [@var{option(s)}]
+@command{gprofng collect app} [@var{option(s)}] @var{target}
+[@var{target-option(s)}]
@c man end
@ManPageEnd{}
@@ -79,7 +80,8 @@ gprofng collect app - Collect performance data for the target program
@c man begin DESCRIPTION
Collect performance data on the target program. In addition to Program Counter
-(PC) sampling, hardware event counters and various tracing options are supported.
+(PC) sampling, hardware event counters and various tracing options are
+supported.
For example, this command collects performance data for an executable called
@samp{a.out} and stores the data collected in an experiment directory with
@@ -115,28 +117,29 @@ Print the version number and exit.
Print usage information and exit.
-@c -- @item --verbose @{on|off@}
-@c -- @ifclear man
-@c -- @IndexSubentry{Options, @code{--verbose}}
-@c -- @end ifclear
+@item -v, --verbose
+@ifclear man
+@IndexSubentry{Options, @code{-v}}
+@IndexSubentry{Options, @code{--verbose}}
+@end ifclear
-@c -- Enable (on) or disable (off) verbose mode; the default is @samp{off}.
+By default, verbose mode is disabled. This option enables it.
-@item -p @{off|on|lo|hi|@var{<value>}@}
+@item -p @{off | on | lo[w] | hi[gh] | @var{<value>}@}
@ifclear man
@IndexSubentry{Options, @code{-p}}
@end ifclear
-Disable (off) or enable (on) clock-profiling using a default sampling
-granularity, or enable clock-profiling implicitly by setting the sampling
-granularity (lo, hi, or a specific value in ms). By default, clock profiling
-is enabled (@samp{-p on}).
+Disable (@samp{off}) or enable (@samp{on}) clock profiling using a default
+sampling granularity, or enable clock profiling implicitly by setting the
+sampling granularity (@samp{lo[w]}, @samp{hi[gh]}, or a specific value in
+ms). By default, clock profiling is enabled (@samp{-p on}).
-@item -h @var{@{<ctr_def>...,<ctr_n_def>@}}
+@item -h @var{<ctr_def>[,<ctr_def>]}
@ifclear man
@IndexSubentry{Options, @code{-h}}
@end ifclear
-Enable hardware event counter profiling and select the counter(s).
+Enable hardware event counter profiling and select one or more counter(s).
To see the supported counters on this system, use the @samp{-h} option
without other arguments.
@@ -147,6 +150,7 @@ without other arguments.
Specify the name for the experiment directory. The name has to end with
@samp{.er} and may contain an absolute path (e.g. @file{/tmp/experiment.er}).
+An existing experiment with the same name will not be overwritten.
@item -O @var{<exp_name>}
@ifclear man
@@ -164,41 +168,46 @@ overwrites an existing experiment directory with the same name.
Add up to 10 comment strings to the experiment. These comments appear in the
notes section of the header and can be retrieved with the
@command{gprofng display text} command using the @samp{-header} option.
+@ifclear man
+@IndexSubentry{Options, @code{-header}}
+@IndexSubentry{Commands, @code{-header}}
+@end ifclear
-@item -j @{on|off|@var{<path>}@}
+@item -j @{on | off | @var{<path>}@}
@ifclear man
@IndexSubentry{Options, @code{-j}}
@end ifclear
-Controls Java profiling when the target is a JVM machine. The allowed values of
-this option are: enable (on), disable (off) Java profiling when the target
-program is a JVM, or set @samp{<path>} to a non-default JVM.
-The default is @samp{-j on}
+Controls Java profiling when the target is a JVM machine. The allowed values
+for this option are:
@table @gcctabopt
@item on
Record profiling data for the JVM machine, and recognize methods compiled by
-the Java HotSpot virtual machine. Also record Java call stacks. The default
-is @samp{-j on}.
+the Java HotSpot virtual machine. Also record Java call stacks.
@item off
-Does not record Java profiling data. Profiling data for native call stacks is
+Do not record Java profiling data. Profiling data for native call stacks is
still recorded.
@item @var{<path>}
-Records profiling data for the JVM, and use the JVM as installed in @var{<path>}.
+Records profiling data for the JVM, and use the JVM as installed in
+@var{<path>}.
@end table
-@item -J @var{<jvm-options>}
+The default is @samp{-j on}.
+
+@item -J @var{<jvm-option(s)>}
@ifclear man
@IndexSubentry{Options, @code{-J}}
@end ifclear
-Specifies additional options to be passed to the JVM used. The
-@var{jvm-options} list must be enclosed in quotation marks if it contains more
-than one option. The items in the list need to be separated by spaces or tab.
+Specifies one or more additional options to be passed to the JVM used. The
+@var{jvm-option(s)} list must be enclosed in quotation marks if it contains
+more than one option. The items in the list need to be separated by spaces
+or tabs.
Each item is passed as a separate option to the JVM. Note that this option
implies @samp{-j on}.
@@ -211,11 +220,12 @@ Collects data for the specified duration. The duration can be a single number,
optionally followed by either @samp{m} to specify minutes, or @samp{s} to
specify seconds, which is the default.
-The duration can also two numbers separated by minus (-) sign. If a single
-number is given, data is collected from the start of the run until the given
-time. If two numbers are given, data is collected from the first time to the
-second. If the second time is zero, data is collected until the end of the
-run. If two non-zero numbers are given, the first must be less than the second.
+The duration can also consists of two numbers separated by a minus (@minus{})
+sign. If a single number is given, data is collected from the start of the run
+until the given time.
+If two numbers are given, data is collected from the first time to the second.
+In case the second time is zero, data is collected until the end of the run.
+If two non-zero numbers are given, the first must be less than the second.
@item -n
@ifclear man
@@ -243,8 +253,8 @@ enclose the @var{regex} in single quotes. The default is @samp{-F on}.
@end ifclear
Specify archiving of binaries and other files. In addition to disable this
-feature (off), or enable archiving off all loadobjects and sources (on),
-the other op tions support a more refined selection.
+feature (@samp{off}), or enable archiving off all loadobjects and sources
+(@samp{on}), the other options support a more refined selection.
All of these options enable archiving, but the keyword controls what exactly
is selected: all load objects (ldobjects), all source files (src), the
@@ -257,9 +267,9 @@ The default is @samp{-a ldobjects}.
@IndexSubentry{Options, @code{-S}}
@end ifclear
-Disable (off), or enable (on) periodic sampling of process-wide resource
-utilization. By default, sampling occurs every second. Use the @var{<seconds>}
-option to change this. The default is @samp{-S on}.
+Disable (off), or enable (on) periodic sampling of process-wide
+resource utilization. By default, sampling occurs every second. Use the
+@var{<seconds>} option to change this. The default is @samp{-S on}.
@item -y @var{<signal>}[,r]
@ifclear man
@@ -267,11 +277,11 @@ option to change this. The default is @samp{-S on}.
@end ifclear
Controls recording of data with the signal named @var{<signal>}, referred to
-as the pause-resume signal. Whenever the given signal is delivered to the
+as the pause-resume signal. Whenever the given signal is delivered to the
process, switch between paused (no data is recorded) and resumed (data is
recorded) states.
-By default, data collection begins in the paused state. If the optional
+By default, data collection begins in the paused state. If the optional
@samp{r} is given, data collection begins in the resumed state and data
collection begins immediately.
@@ -283,8 +293,9 @@ not used by the target can be used.
@IndexSubentry{Options, @code{-l}}
@end ifclear
-Specify a signal that will trigger a sample of process-wide resource utilization.
-When the named @var{<signal>} is delivered to the process, a sample is recorded.
+Specify a signal that will trigger a sample of process-wide resource
+utilization. When the named @var{<signal>} is delivered to the process,
+a sample is recorded.
The signal can be specified using the full name, without the initial
letters @code{SIG}, or the signal number. Note that the @command{kill}
@@ -299,9 +310,10 @@ different.
@end ifclear
Enable synchronization wait tracing, where @var{<option>} is used to define the
-specifics of the tracing (on, off, @var{<threshold>}, or all). The API is
+specifics of the tracing (on, off, @var{<threshold>}, or all). The API is
selected through the setting for @var{<API>}: @samp{n} selects native/Pthreads,
-@samp{j} selects Java, and @samp{nj} selects both. The default is @samp{-s off}.
+@samp{j} selects Java, and @samp{nj} selects both. The default is
+@samp{-s off}.
@item -H @{off|on@}
@ifclear man
@@ -340,10 +352,19 @@ gprofng can provide more details, but this is not a requirement.
@c SEEALSO section
@c ----------------------------------------------------------------------------
-@ManPageStart{SEEALSO}
+@ManPageStart{SEE ALSO}
@c man begin SEEALSO
-gprofng(1), gp-archive(1), gp-display-html(1), gp-display-src(1), gp-display-text(1)
+gprofng(1),
+gp-archive(1),
+gp-display-gui(1),
+gp-display-html(1),
+gp-display-src(1),
+gp-display-text(1)
+
+@iftex
+@vspace{1}
+@end iftex
The user guide for gprofng is maintained as a Texinfo manual. If the
@command{info} and @command{gprofng} programs are correctly installed, the
diff --git a/gprofng/doc/gp-display-html.texi b/gprofng/doc/gp-display-html.texi
index de09c340974..7ec4c0c77d6 100644
--- a/gprofng/doc/gp-display-html.texi
+++ b/gprofng/doc/gp-display-html.texi
@@ -1,11 +1,11 @@
@c ----------------------------------------------------------------------------
-@c This is the Texinfo source file for the gp-collect-app man page.
+@c This is the Texinfo source file for the gp-display-html man page.
@c
@c Author: Ruud van der Pas
@c ----------------------------------------------------------------------------
@ifset man
\input texinfo @c -*-texinfo-*-
-@setfilename gprofng display html
+@setfilename gp-display-html
@settitle Generate an HTML based directory structure to browse the profiles
@include gp-macros.texi
@end ifset
@@ -54,7 +54,8 @@
@ManPageStart{NAME}
@c man begin NAME
-gprofng display html - Generate an HTML based directory structure to browse the profiles
+gp-display-html - Generate an HTML based directory structure to browse the
+profiles
@c man end
@ManPageEnd{}
@@ -107,85 +108,87 @@ Print the version number and exit.
Print usage information and exit.
-@item --verbose @{on|off@}
+@item --verbose
@ifclear man
@IndexSubentry{Options, @code{--verbose}}
@end ifclear
-Enable (@samp{on}) or disable (@samp{off)} verbose mode.
-The default is @samp{off}.
+Enable verbose mode to show diagnostic messages about the processing of the
+data. By default verbose mode is disabled.
-@item --debug @{on|s|m|l|xl|off@}
-@item -d @{on|s|m|l|xl|off@}
+@item -d [@var{db-vol-size}], --debug[=@var{db-vol-size}]
@ifclear man
@IndexSubentry{Options, @code{-d}}
@IndexSubentry{Options, @code{--debug}}
@end ifclear
-Control the printing of run time information to assist with troubleshooting,
-or further development of this tool. The keyword is case insensitive.
-A setting of @samp{on} gives a modest amount of information. The keywords
-@samp{s}, @samp{m}, @samp{l}, and @samp{xl} give an increasing amount of
-information, while @samp{off} disables the printing of debug information.
-This is also the default.
+Control the printing of run time debug information to assist with the
+troubleshooting, or further development of this tool.
-Note that currently @samp{on}, @samp{s}, @samp{m}, and @samp{l} are
-equivalent. This is expected to change in future updates.
+The @var{db-vol-size} parameter controls the output volume and is one from
+the list @samp{s}, @samp{S}, @samp{m}, @samp{M}, @samp{l}, @samp{L}, @samp{xl},
+or @samp{XL}. If @var{db-vol-size} is not set, a modest amount of information
+is printed. This is equivalent to select @samp{s}, or @samp{S}. The volume
+of data goes up as the size increases. Note that currently @samp{l/L} is
+equivalent to @samp{xl/XL}, but this is expected to change in future updates.
+By default debug mode is disabled.
-@item ---highlight-percentage @var{value}
-@item -hp @var{value}
+@item --highlight-percentage=@var{value}
@ifclear man
@IndexSubentry{Options, @code{--highlight-percentage}}
-@IndexSubentry{Options, @code{-hp}}
@end ifclear
Set a percentage value in the interval [0,100] to select and color code source
lines, as well as instructions, that are within this percentage of the maximum
-metric value(s). The default is 90 (%).
+metric value(s). The default is 90 (%). A value of zero disables this
+feature.
-A value of zero @samp{(-hp 0)} disables this feature.
-
-@item --output @var{dirname}
-@item -o @var{dirname}
+@item -o @var{dirname}, --output=@var{dirname}
@ifclear man
-@IndexSubentry{Options, @code{--output}}
@IndexSubentry{Options, @code{-o}}
+@IndexSubentry{Options, @code{--output}}
@end ifclear
-Use @var{dirname} as the directory name to store the HTML files in.
-The default name is @samp{display.<n>.html} with @var{<n>} the first
-positive integer number not in use. An existing directory with the
-same name is not overwritten.
+Use @var{dirname} as the directory name to store the results in. In
+absence of this option, the default name is @samp{display.<n>.html}.
+This directory is created in the current directory.
+The number @var{<n>} is the first positive integer number not in use in
+this naming scheme. An existing directory with the same name is not
+overwritten.
+In case the directory exists already, an error message is printed and
+the tool terminates.
-@item --overwrite @var{dirname}
-@item -O @var{dirname}
+@item -O @var{dirname}, --overwrite=@var{dirname}
@ifclear man
-@IndexSubentry{Options, @code{--overwrite}}
@IndexSubentry{Options, @code{-O}}
+@IndexSubentry{Options, @code{--overwrite}}
@end ifclear
-Use @var{dirname} as the directory name to store the HTML files in.
+Use @var{dirname} as the directory name to store the results in. In
+absence of this option, the default name is @samp{display.<n>.html}.
+This directory is created in the current directory.
+The number @var{<n>} is the first positive integer number not in use in
+this naming scheme. An existing directory with the same name is silently
+overwritten.
-@item --quiet @{on|off@}
-@item -q @{on|off@}
+@item -q, --quiet
@ifclear man
-@IndexSubentry{Options, @code{--quiet}}
@IndexSubentry{Options, @code{-q}}
+@IndexSubentry{Options, @code{--quiet}}
@end ifclear
-Control the display of all warning, debug and verbose messages.
-If set to @samp{on}, the settings for verbose, warnings and debug are ignored.
-By default the quiet mode is disabled (@samp{-q off}).
+Disable the display of all warning, debug, verbose and any other messages.
+If enabled, the settings for verbose and debug are accepted, but ignored.
+With this option, there is no screen output, other than errors. By default
+quiet mode is disabled.
-@item --warnings @{on|off@}
-@item -w @{on|off@}
+@item --nowarnings
@ifclear man
-@IndexSubentry{Options, @code{--warnings}}
-@IndexSubentry{Options, @code{-w}}
+@IndexSubentry{Options, @code{--nowarnings}}
@end ifclear
-Enable (@samp{on}), or disable (@samp{off}) run time warning messages from
-the tool. By default these are enabled.
+Disable the printing of warning messages on stdout. By default warning
+messages are printed.
@end table
@@ -199,11 +202,51 @@ the tool. By default these are enabled.
@ManPageStart{NOTES}
@c man begin NOTES
-When setting a directory name for the HTML files to be stored in, make sure that
-umask is set to the correct access permissions.
+@itemize @minus
+
+@item
+The options and values are case sensitive.
+
+@item
+In this release, the option syntax has changed to be more compliant with other
+tools and commands.
-Regardless of the setting for the warning messages, any warnings are accessible
-through the main @file{index.html} page.
+The options that used to have an @samp{on} or @samp{off} value only, now act
+as a switch. The option negates the default setting. For example, by
+default, verbose mode is disabled. It is enabled by using the
+@samp{--verbose} option.
+
+The long options, those starting with @code{--}, that require a value, expect
+the @code{=} sign between the option and the value.
+
+While the previous syntax and choices are accepted still, we strongly
+recommend to change the usage of the options according to the new syntax
+and values. At some point, these legacy settings may no longer be accepted.
+
+To assist with the transition, a warning message is shown if the legacy
+syntax, or value, or both, are used.
+
+@item
+The @samp{-hp} option is still accepted, but it will be deprecated in a
+future release. Use the @samp{--highlight-percentage} option instead.
+
+@item
+When setting a directory name for the HTML files to be stored in, make sure
+that umask is set to the correct access permissions.
+
+@item
+Regardless of the setting for the warning messages, if there are warnings, they
+are accessible through the main @file{index.html} page.
+
+@item
+The tool tries to accumulate as many warnings and errors as possible, before
+taking action. In this way, it is easier to address multiple issues at
+once. As a result of this approach, it may be that the messages do not show
+immediately. In particular, warnings are shown towards the end of the
+execution, but one or more errors will terminate execution before the
+processing begins.
+
+@end itemize
@c man end
@ManPageEnd{}
@@ -212,10 +255,19 @@ through the main @file{index.html} page.
@c SEEALSO section
@c ----------------------------------------------------------------------------
-@ManPageStart{SEEALSO}
+@ManPageStart{SEE ALSO}
@c man begin SEEALSO
-gprofng(1), gp-archive(1), gp-collect-app(1), gp-display-src(1), gp-display-text(1)
+gprofng(1),
+gp-archive(1),
+gp-collect-app(1),
+gp-display-gui(1),
+gp-display-src(1),
+gp-display-text(1)
+
+@iftex
+@vspace{1}
+@end iftex
The user guide for gprofng is maintained as a Texinfo manual. If the
@command{info} and @command{gprofng} programs are correctly installed, the
diff --git a/gprofng/doc/gp-display-src.texi b/gprofng/doc/gp-display-src.texi
index 6b32a9905a5..6ebe66d974a 100644
--- a/gprofng/doc/gp-display-src.texi
+++ b/gprofng/doc/gp-display-src.texi
@@ -1,12 +1,12 @@
@c ----------------------------------------------------------------------------
-@c This is the Texinfo source file for the gp-collect-app man page.
+@c This is the Texinfo source file for the gp-display-src man page.
@c
@c Author: Ruud van der Pas
@c ----------------------------------------------------------------------------
@ifset man
\input texinfo @c -*-texinfo-*-
-@setfilename gprofng display src
-@settitle Display the source code, optionally interleaved with the disassembly of the target object
+@setfilename gp-display-src
+@settitle Display source code and optionally disassembly of the target object
@include gp-macros.texi
@end ifset
@@ -54,7 +54,8 @@
@ManPageStart{NAME}
@c man begin NAME
-gprofng display src - Display the source code, optionally interleaved with the disassembly of the target object
+gp-display-src - Display the source code, optionally interleaved with the
+disassembly of the target object
@c man end
@ManPageEnd{}
@@ -66,7 +67,7 @@ gprofng display src - Display the source code, optionally interleaved with the d
@ManPageStart{SYNOPSIS}
@c man begin SYNOPSIS
-@command{gprofng display src} [@var{option(s)}] @var{target_file}
+@command{gprofng display src} [@var{option(s)}] @var{target-file}
@c man end
@ManPageEnd{}
@@ -78,12 +79,12 @@ gprofng display src - Display the source code, optionally interleaved with the d
@ManPageStart{DESCRIPTION}
@c man begin DESCRIPTION
-Display the source code listing, or source code interleaved with disassembly code,
-as extracted from the target file (an executable, shared object, object file, or a
-Java .class file).
+Display the source code listing, or source code interleaved with disassembly
+code, as extracted from the target file (an executable, shared object, object
+file, or a Java .class file).
-For example, this command displays the source code and disassembly listing for a
-function called @samp{mxv_core} that is part of object file @samp{mxv.o}:
+For example, this command displays the source code and disassembly listing for
+a function called @samp{mxv_core} that is part of object file @samp{mxv.o}:
@smallexample
$ gprofng display src -disasm mxv_core mxv.o
@@ -96,10 +97,10 @@ use the following command:
$ gprofng display src -disasm all -1 mxv.o
@end smallexample
-The @var{target_file} is the name of an executable, a shared object, an object
+The @var{target-file} is the name of an executable, a shared object, an object
file (.o), or a Java .class file.
-If no options are given, the source code listing of the @var{target_file}
+If no options are given, the source code listing of the @var{target-file}
is shown. This is equivalent to @samp{-source all -1}. If this information
is not available, a message to this extent is printed.
@@ -129,13 +130,6 @@ Print the version number and exit.
Print usage information and exit.
-@c -- @item --verbose @{on|off@}
-@c -- @ifclear man
-@c -- @IndexSubentry{Options, @code{--verbose}}
-@c -- @end ifclear
-
-@c -- Enable (on) or disable (off) verbose mode; the default is @samp{off}.
-
@item -functions
@ifclear man
@IndexSubentry{Options, @code{-functions}}
@@ -148,29 +142,29 @@ List all the functions from the given object.
@IndexSubentry{Options, @code{-source}}
@IndexSubentry{Commands, @code{source}}
@end ifclear
-Show the source code for @var{item} in @var{target_file}. The @var{tag}
+Show the source code for @var{item} in @var{target-file}. The @var{tag}
is used to differentiate in case there are multiple occurences with the same
name.
-See the @samp{NOTES} section for the definition of @var{item} and @var{tag}.
+See the @samp{NOTES} section for the definition of @var{item} and @var{tag}.
@item -disasm @var{item} @var{tag}
@ifclear man
@IndexSubentry{Options, @code{-disasm}}
@IndexSubentry{Commands, @code{disasm}}
@end ifclear
-Include the disassembly in the source listing. The default listing does not
-include the disassembly. If the source code is not available, show a listing
+Include the disassembly in the source listing. The default listing does not
+include the disassembly. If the source code is not available, show a listing
of the disassembly only.
-See the @samp{NOTES} section for the definition of @var{item} and @var{tag}.
+See the @samp{NOTES} section for the definition of @var{item} and @var{tag}.
@item -outfile @var{filename}
@ifclear man
@IndexSubentry{Options, @code{-outfile}}
@IndexSubentry{Commands, @code{outfile}}
@end ifclear
-Write results to file @var{filename}. A dash (-) writes to stdout. This is also
-the default. Note that this option only affects those options included to the
-right of this option.
+Write results to file @var{filename}. A dash (@minus{}) writes to stdout.
+This is also the default. Note that this option only affects those options
+included to the right of the option.
@end table
@@ -188,7 +182,7 @@ Use @var{item} to specify the name of a function, or of a source or object
file that was used to build the executable, or shared object.
The @var{tag} is an index used to determine which item is being referred
-to when multiple functions have the same name. It is required, but will
+to when multiple functions have the same name. It is required, but will
be ignored if not necessary to resolve the function.
The @var{item} may also be specified in the form @samp{function`file`}, in
@@ -197,7 +191,7 @@ context of the named file will be used.
The special @var{item} and @var{tag} combination @samp{all -1}, is used to
indicate generating the source, or disassembly, for all functions in the
-@var{target_file}.
+@var{target-file}.
@c man end
@ManPageEnd{}
@@ -206,10 +200,19 @@ indicate generating the source, or disassembly, for all functions in the
@c SEEALSO section
@c ----------------------------------------------------------------------------
-@ManPageStart{SEEALSO}
+@ManPageStart{SEE ALSO}
@c man begin SEEALSO
-gprofng(1), gp-archive(1), gp-collect-app(1), gp-display-html(1), gp-display-text(1)
+gprofng(1),
+gp-archive(1),
+gp-collect-app(1),
+gp-display-gui(1),
+gp-display-html(1),
+gp-display-text(1)
+
+@iftex
+@vspace{1}
+@end iftex
The user guide for gprofng is maintained as a Texinfo manual. If the info
and gprofng programs are correctly installed, the command
diff --git a/gprofng/doc/gp-display-text.texi b/gprofng/doc/gp-display-text.texi
index 993f9f0f35c..5790c135102 100644
--- a/gprofng/doc/gp-display-text.texi
+++ b/gprofng/doc/gp-display-text.texi
@@ -1,11 +1,11 @@
@c ----------------------------------------------------------------------------
-@c This is the Texinfo source file for the gp-collect-app man page.
+@c This is the Texinfo source file for the gp-display-text man page.
@c
@c Author: Ruud van der Pas
@c ----------------------------------------------------------------------------
@ifset man
\input texinfo @c -*-texinfo-*-
-@setfilename gprofng display text
+@setfilename gp-display-text
@settitle Display the performance data in plain text format
@include gp-macros.texi
@end ifset
@@ -54,7 +54,7 @@
@ManPageStart{NAME}
@c man begin NAME
-gprofng display text - Display the performance data in plain text format
+gp-display-text - Display the performance data in plain text format
@c man end
@ManPageEnd{}
@@ -84,8 +84,8 @@ Print a plain text version of the various displays supported by gprofng.
The input consists of one or more experiment directories. Through commands,
the user controls the output.
-There is a rich set of commands to control the display of the data. The
-@samp{NOTES} section lists the most common ones. The gprofng user guide
+There is a rich set of commands to control the display of the data. The
+@samp{NOTES} section lists the most common ones. The gprofng user guide
lists all the commands supported.
Commands specified on the command line need to be prepended with the dash ('-')
@@ -107,8 +107,9 @@ Note that the commands are processed and interpreted from left to right,
@emph{so the order matters}.
If this tool is invoked without options, commands, or a script file, it
-starts in interpreter mode. The user can then issue the commands interactively.
-The session is terminated with the @command{exit} command in the interpreter.
+starts in interpreter mode. The user can then issue the commands
+interactively. The session is terminated with the @command{exit} command in
+the interpreter.
@c man end
@ManPageEnd{}
@@ -136,13 +137,6 @@ Print the version number and exit.
Print usage information and exit.
-@c -- @item --verbose @{on|off@}
-@c -- @ifclear man
-@c -- @IndexSubentry{Options, @code{--verbose}}
-@c -- @end ifclear
-
-@c -- Enable (on) or disable (off) verbose mode; the default is @samp{off}.
-
@item -script @var{script-file}
@ifclear man
@IndexSubentry{Options, @code{-script}}
@@ -164,12 +158,12 @@ with commands specified at the command line.
@ManPageStart{NOTES}
@c man begin NOTES
-Many commands are supported. Below, the more common ones are listed in
+Many commands are supported. Below, the more common ones are listed in
mostly alphabetical order, because sometimes it is more logical to
swap the order of two entries.
@ifset man
-There are many more commands. These are documented in the user guide.
+There are many more commands. These are documented in the user guide.
@end ifset
@table @code
@@ -198,7 +192,7 @@ metrics at each level.
@IndexSubentry{Options, @code{-compare}}
@IndexSubentry{Commands, @code{compare}}
@end ifclear
-By default, the results for multiple experiments are aggregated. This
+By default, the results for multiple experiments are aggregated. This
command changes this to enable the comparison of experiments for certain
views (e.g. the function view). The first experiment specified is defined
to be the reference. The following options are supported:
@@ -227,7 +221,7 @@ experiments are shown as a ratio relative to the reference (current/reference).
@IndexSubentry{Options, @code{-disasm}}
@IndexSubentry{Commands, @code{disasm}}
@end ifclear
-List the source code and instructions for the function specified. The
+List the source code and instructions for the function specified. The
instructions are annotated with the metrics used.
@item fsingle @var{function-name} [@samp{n}]
@@ -251,7 +245,7 @@ Write a summary panel for each function in the function list.
@IndexSubentry{Commands, @code{functions}}
@end ifclear
Display a list of all functions executed. For each function the used metrics
-(e.g. the CPU time) ar shown.
+(e.g. the CPU time) are shown.
@item header
@ifclear man
@@ -274,7 +268,7 @@ Limit the output to @var{n} lines.
@IndexSubentry{Commands, @code{lines}}
@end ifclear
Write a list of source lines and their metrics, ordered by the current
-sort metric.
+sort metric.
@item metric_list
@ifclear man
@@ -296,6 +290,20 @@ The @var{metric-spec} can either be the keyword @samp{default}
to restore the default metrics selection, or a colon separated list
with metrics.
+@ifclear man
+@IndexSubentry{Hardware event counters, @code{hwc} metric}
+@end ifclear
+A special metric is @code{hwc}. It automatically expands to the active
+set of hardware event counters used in the experiment(s).
+
+@ifclear man
+@IndexSubentry{Hardware event counters, @code{IPC} metric}
+@IndexSubentry{Hardware event counters, @code{CPI} metric}
+@end ifclear
+If both instructions and clock cycles have been measured, the @code{CPI}
+and @code{IPC} metrics can be used to see the Clockcycles Per Instruction
+and Instructions Per Clockcyle values, respectively.
+
The gprofng user guide has more details how to define metrics.
@item name @{short | long | mangled@}[:@{soname | nosoname@}]
@@ -311,9 +319,13 @@ the output by adding the @emph{soname} keyword. It can also be ommitted
Whether there is an actual difference between these types of names depends
on the language.
-Note that there should be no (white)space to the left and right of the
+Note that there should be no (white)space to the left and right of the
colon (@samp{:}).
+This option should not be confused with the keyword @samp{name} in a
+metric definition, which is used to specify that the names of functions
+should be shown in the function overview.
+
@item overview
@ifclear man
@IndexSubentry{Options, @code{-overview}}
@@ -328,14 +340,14 @@ specified on the command line.
@IndexSubentry{Commands, @code{pcs}}
@end ifclear
Write a list of program counters (PCs) and their metrics, ordered by
-the current sort metric.
+the current sort metric.
@item sort @var{metric-spec}
@ifclear man
@IndexSubentry{Options, @code{-sort}}
@IndexSubentry{Commands, @code{sort}}
@end ifclear
-Sort the function list on the @var{metric-spec} given.
+Sort the function list on the @var{metric-spec} given.
@IndexSubentry{Sort, Reverse order}
The data can be sorted in reverse order by prepending the metric definition
@@ -397,10 +409,19 @@ for C, C++, and Fortran.
@c SEEALSO section
@c ----------------------------------------------------------------------------
-@ManPageStart{SEEALSO}
+@ManPageStart{SEE ALSO}
@c man begin SEEALSO
-gprofng(1), gp-archive(1), gp-collect-app(1), gp-display-html(1), gp-display-src(1)
+gprofng(1),
+gp-archive(1),
+gp-collect-app(1),
+gp-display-gui(1),
+gp-display-html(1),
+gp-display-src(1)
+
+@iftex
+@vspace{1}
+@end iftex
The user guide for gprofng is maintained as a Texinfo manual. If the
@command{info} and @command{gprofng} programs are correctly installed, the
diff --git a/gprofng/doc/gp-macros.texi b/gprofng/doc/gp-macros.texi
index f4bd4236245..3c207edb88f 100644
--- a/gprofng/doc/gp-macros.texi
+++ b/gprofng/doc/gp-macros.texi
@@ -23,6 +23,10 @@
@command{gprofng archive}
@end macro
+@macro GUI{}
+@command{gprofng display gui}
+@end macro
+
@macro Driver{}
@command{gprofng}
@end macro
@@ -41,7 +45,9 @@ gprofng
@end macro
@macro vspace {lines}
+@iftex
@sp \lines\
+@end iftex
@end macro
@c -- For some reason ending this macro with @noindent does not work out well.
diff --git a/gprofng/doc/gprofng.texi b/gprofng/doc/gprofng.texi
index d038a47f595..387104e0cea 100644
--- a/gprofng/doc/gprofng.texi
+++ b/gprofng/doc/gprofng.texi
@@ -74,7 +74,8 @@ gprofng - The driver for the gprofng application profiling tool
@ManPageStart{SYNOPSIS}
@c man begin SYNOPSIS
-@command{gprofng} [@var{option(s)}] @var{action} [@var{qualifier}] [@var{option(s)}] @var{target} [@var{options}]
+@command{gprofng} [@var{option(s)}] @var{action} [@var{qualifier}]
+[@var{option(s)}] @var{target} [@var{options}]
@c man end
@ManPageEnd{}
@@ -86,17 +87,17 @@ gprofng - The driver for the gprofng application profiling tool
@ManPageStart{DESCRIPTION}
@c man begin DESCRIPTION
-This is the driver for the gprofng tools suite to gather and analyze performance
-data.
+This is the driver for the gprofng tools suite to gather and analyze
+performance data.
-The driver executes the @var{action} specified. An example of an action is
-@samp{collect} to collect performance data. Depending on the action, a
+The driver executes the @var{action} specified. An example of an action is
+@samp{collect} to collect performance data. Depending on the action, a
@var{qualifier} may be needed to further define the command.
The last item is the @var{target} that the command applies to.
There are three places where options are supported. The driver supports
options. These can be found below. The @var{action}, possibly in combination
-with the @var{qualifier} also supports options. A description of these can be
+with the @var{qualifier} also supports options. A description of these can be
found in the man page for the command. Any options needed to execute the
target command should follow the target name.
@@ -108,12 +109,12 @@ the following command may be used:
$ gprofng collect app -o mydata.er a.out -t 2
@end smallexample
-In this example, the action is @samp{collect}, the qualifier is @samp{app}, the single
-argument to the command is @code{-o mydata.er} and the target is @command{a.out}.
-The target command is invoked with the @samp{-t 2} option.
+In this example, the action is @samp{collect}, the qualifier is @samp{app},
+the single argument to the command is @code{-o mydata.er} and the target is
+@command{a.out}. The target command is invoked with the @samp{-t 2} option.
-If gprofng is executed without any additional option, action, or target, a usage
-overview is printed.
+If gprofng is executed without any additional option, action, or target, a
+usage overview is printed.
@c man end
@ManPageEnd{}
@@ -144,9 +145,9 @@ Print usage information and exit.
@c man end
@ManPageEnd{}
-@c -----------------------------------------------------------------------------
+@c ----------------------------------------------------------------------------
@c ENVIRONMENT SECTION
-@c -----------------------------------------------------------------------------
+@c ----------------------------------------------------------------------------
@ManPageStart{ENVIRONMENT}
@c man begin ENVIRONMENT
@@ -156,45 +157,94 @@ The following environment variables are supported:
@table @samp
@item @env{GPROFNG_MAX_CALL_STACK_DEPTH}
+
+@ifclear man
@cindex Environment variables
+@end ifclear
+
Set the depth of the call stack (default is 256).
@item @env{GPROFNG_USE_JAVA_OPTIONS}
+
+@ifclear man
@cindex Environment variables
+@end ifclear
+
May be set when profiling a C/C++ application that uses dlopen() to execute
Java code.
@c -- deferred @item @env{GPROFNG_SSH_REMOTE_DISPLAY}
-@c -- deferred Use this variable to define the ssh command executed by the remote display tool.
+@c -- deferred Use this variable to define the ssh command executed by the
+@c -- remote display tool.
@c -- deferred @item @env{GPROFNG_SKIP_VALIDATION}
-@c -- deferred Set this variable to disable checking hardware, system, and Java versions.
+@c -- deferred Set this variable to disable checking hardware, system, and
+@c -- Java versions.
@item @env{GPROFNG_ALLOW_CORE_DUMP}
+
+@ifclear man
@cindex Environment variables
+@end ifclear
+
Set this variable to allow a core file to be generated; otherwise an error
-report is created on /tmp.
+report is created on @samp{/tmp}.
@item @env{GPROFNG_ARCHIVE}
+
+@ifclear man
@cindex Environment variables
-Use this variable to define the settings for automatic archiving upon experiment
-recording completion.
+@end ifclear
+
+Use this variable to define the settings for automatic archiving upon
+experiment recording completion.
@item @env{GPROFNG_ARCHIVE_COMMON_DIR}
+
+@ifclear man
@cindex Environment variables
+@end ifclear
+
Set this variable to the location of the common archive.
@item @env{GPROFNG_JAVA_MAX_CALL_STACK_DEPTH}
+
+@ifclear man
@cindex Environment variables
+@end ifclear
+
Set the depth of the Java call stack; the default is 256; set to 0 to disable
capturing of call stacks.
@item @env{GPROFNG_JAVA_NATIVE_MAX_CALL_STACK_DEPTH}
+
+@ifclear man
@cindex Environment variables
+@end ifclear
+
Set the depth of the Java native call stack; the default is 256; set to 0 to
disable capturing of call stacks (JNI and assembly call stacks are not
captured).
+@item @env{GPROFNG_SYSCONFDIR}
+
+@ifclear man
+@cindex Environment variables
+@end ifclear
+
+Set the path to the @file{gprofng.rc} configuration file. By default, this
+file is placed in the @file{etc} subdirectory of the binutils installation
+directory. In case an RPM has been used for the installation, this file is
+in directory @file{/etc}.
+
+When building and installing from the source, the user can set the path
+to this configuration file to a non-default location. If this is the case,
+the user may set the @code{GPROFNG_SYSCONFDIR} environment variable to point
+to this location.
+
+Otherwise, the @command{gp-display-text}, @command{gp-display-src}, and
+@command{gp-archive} tools cannot find this file.
+
@end table
@c man end
@@ -208,10 +258,14 @@ captured).
@c man begin NOTES
The gprofng driver supports the following commands.
+
+@iftex
@vspace{1}
+@end iftex
-@c The man pages for the commands below can be viewed using the command name with "gprofng" replaced by "gp" and the spaces replaced by a dash ("-"). For example the man page
-@c name for "gprofng collect app" is "gp-collect-app".
+@c The man pages for the commands below can be viewed using the command name
+@c with "gprofng" replaced by "gp" and the spaces replaced by a dash ("-").
+@c For example the man page name for "gprofng collect app" is "gp-collect-app".
@i{Collect performance data:}
@@ -232,6 +286,10 @@ Display the performance data in ASCII format.
@item gprofng display html
Generate an HTML file from one or more experiments.
+@item gprofng display gui
+Start the GUI. Note that this tool is not available by default and needs to
+be installed seperately.
+
@end table
@i{Miscellaneous commands:}
@@ -257,13 +315,21 @@ use the driver.
@c SEEALSO section
@c ----------------------------------------------------------------------------
-@ManPageStart{SEEALSO}
+@ManPageStart{SEE ALSO}
@c man begin SEEALSO
-gp-archive(1), gp-collect-app(1), gp-display-html(1), gp-display-src(1),
+gp-archive(1),
+gp-collect-app(1),
+gp-display-gui(1),
+gp-display-html(1),
+gp-display-src(1),
gp-display-text(1)
-Each gprofng command also supports the @option{--help} option. This lists the
+@iftex
+@vspace{1}
+@end iftex
+
+Each gprofng command also supports the @option{--help} option. This lists the
options and a short description for each option.
For example this displays the options supported on the
diff --git a/gprofng/doc/gprofng_ug.texi b/gprofng/doc/gprofng_ug.texi
index 1fe95c701e9..9759ffe0332 100644
--- a/gprofng/doc/gprofng_ug.texi
+++ b/gprofng/doc/gprofng_ug.texi
@@ -93,16 +93,16 @@ section entitled ``GNU Free Documentation License.''
@c * Archive Experiment Data:: Archive an experiment.
@menu
-* Introduction:: About this manual.
-* Overview:: A brief overview of @ProductName{}.
-* A Mini Tutorial:: A short tutorial covering the key features.
-* The gprofng Tools:: An overview of the tools supported.
-* Performance Data Collection:: Record the performance information.
-* View the Performance Information:: Different ways to view the data.
-* Terminology:: Concepts and terminology explained.
-* Other Document Formats:: Create this document in other formats.
-* The gprofng Man Pages:: The gprofng man pages.
-* Index:: The index.
+* Introduction:: About this manual.
+* Overview:: A brief overview of @ProductName{}.
+* A Mini Tutorial:: A short tutorial covering the key features.
+* The gprofng Tools:: An overview of the tools supported.
+* Performance Data Collection:: Record the performance information.
+* View the Performance Information:: Different ways to view the data.
+* Terminology:: Concepts and terminology explained.
+* Other Document Formats:: Create this document in other formats.
+* The gprofng Man Pages:: The gprofng man pages.
+* Index:: The index.
@detailmenu
@@ -131,6 +131,14 @@ The gprofng Tools
* Filters:: Filters.
* Supported Environment Variables:: The supported environment variables.
+Performance Data Collection
+
+* The @command{gprofng collect app} Tool:: Collect application performance data.
+
+View the Performance Information
+
+* The @command{gprofng display text} Tool:: View the performance data in plain text.
+
Terminology
* The Program Counter:: What is a Program Counter?
@@ -139,17 +147,17 @@ Terminology
* The Viewmode:: Select the way call stacks are presented.
* The Selection List:: How to define a selection.
* Load Objects and Functions:: The components in an application.
-* The Concept of a CPU in @ProductName{}:: The definition of a CPU.
+* The Concept of a CPU in gprofng:: The definition of a CPU.
* Hardware Event Counters Explained:: What are event counters?
* apath:: Our generic definition of a path.
The gprofng Man Pages
-* gprofng collect app:: The man page for gprofng collect app.
-* gprofng display text:: The man page for gprofng display text.
-* gprofng display src:: The man page for gprofng display src.
-* gprofng display html:: The man page for gprofng display html.
-* gprofng archive:: The man page for gprofng archive.
+* Man page for @command{gprofng collect app}:: The man page for gprofng collect app.
+* Man page for @command{gprofng display text}:: The man page for gprofng display text.
+* Man page for @command{gprofng display html}:: The man page for gprofng display html.
+* Man page for @command{gprofng display src}:: The man page for gprofng display src.
+* Man page for @command{gprofng archive}:: The man page for gprofng archive.
@c -- Index
@@ -1899,7 +1907,7 @@ referred to as
Similar to the commands for the threads, there are several commands related
to the usage of the cores, or @emph{CPUs} as they are called in @ToolName{}
-(@xref{The Concept of a CPU in @ProductName{}}).
+(@xref{The Concept of a CPU in gprofng}).
@IndexSubentry{Options, @code{-cpu_list}}
@IndexSubentry{Commands, @code{cpu_list}}
@@ -2615,7 +2623,8 @@ portable in case we would like to repeat this experiment on another processor.
@IndexSubentry{Hardware event counters, @code{hwc} metric}
This is where the special @code{hwc} metric comes very handy. It
-automatically expands to the active set of events used.
+automatically expands to the active set of hardware event counters used
+in the experiment(s).
With this, it is very easy to display the event counter values. Note that
although the regular clock based profiling was enabled, we only want to see
@@ -3205,25 +3214,47 @@ the results.
@item @DisplayText{}
@IndexSubentry{@code{gprofng}, @code{display text}}
+
Generates performance reports in ASCII format. Commandline
options, and/or commands in a script file are used to control the contents
and lay-out of the generated report(s).
@item @DisplayHTML{}
@IndexSubentry{@code{gprofng}, @code{display html}}
+
Takes one or more experiment directories and generates a directory with
HTML files. Starting from the index.html file, the performance data
may be examined in a browser.
@item @DisplaySRC{}
@IndexSubentry{@code{gprofng}, @code{display src}}
+
Displays the source code, interleaved with the disassembled instructions.
@item @Archive{}
@IndexSubentry{@code{gprofng}, @code{archive}}
+
Archives an experiment directory by (optionally) including source code and
object files, as well as the shared libraries that have been used.
+@item @GUI{}
+@IndexSubentry{@code{gprofng}, @code{display gui}}
+
+This is an optional component that can be installed in addition to the
+command line gprofng tools listed above. It supports the graphical
+analysis of one or more experiments that have been created using
+@CollectApp{}.
+
+The GUI part of @ProductName{} is a GNU project. This is the link to the
+@url{https://savannah.gnu.org/projects/gprofng-gui, gprofng GUI page}.
+This page contains more information (e.g. how to clone the repo).
+There is also a
+@url{https://ftp.gnu.org/gnu/gprofng-gui, tar file distribution directory}
+with tar files that include everything that is needed to build and install
+the GUI code. Various versions are available here.
+Be aware that in order to build and use the gprofng GUI, Java needs to be
+installed first. The minimum Java version required is Java 8.
+
@end table
@c -- A new section -----------------------------------------------------------
@@ -3232,13 +3263,14 @@ object files, as well as the shared libraries that have been used.
@c ----------------------------------------------------------------------------
The @file{gprofng.rc}
@cindex gprofng.rc
-file is used to define default settings for the @DisplayText{} and
-@DisplaySRC{} tools, but the user can override these defaults through local
-configuration files.
+file is used to define default settings for the @DisplayText{}, @Archive{},
+and @DisplaySRC{} tools, but the user can override these defaults through
+local configuration settings when building and installing from the source
+code..
There are three files that are checked when the tool starts up. The first
file has pre-defined settings and comes with the installation, but through
-a hidden file called @file{.gprofng.rc}, the user can (re)define the defaults:
+a hidden file called @file{.gprofng.rc}, the user can (re)define the defaults.
These are the locations and files that are checked upon starting the above
mentioned tools:
@@ -3247,7 +3279,7 @@ mentioned tools:
@item
The system-wide filename is called @file{gprofng.rc} and is located in
-the top level @file{/etc} directory.
+the @file{/etc} subdirectory in case an RPM was used for the installation..
If @ProductName{} has been built from the source, this file is in
subdirectory @file{etc} in the top level installation directory.
@@ -3256,7 +3288,7 @@ subdirectory @file{etc} in the top level installation directory.
The user's home directory may have a hidden file called @file{.gprofng.rc}.
@item
-The directory where @DisplayText{} (or @DisplaySRC{}) is invoked from may
+The directory where @DisplayText{} (or @DisplaySRC{}) is invoked from, may
have a hidden file called @file{.gprofng.rc}.
@end enumerate
@@ -3439,7 +3471,7 @@ For a list of all the predefined filters see @ref{Predefined Filters}.
Various environment variables are supported. We refer to the man page for
gprofng(1) for an overview and description
-(@xref{Man page for gprofng}).
+(@xref{Man page for @command{gprofng}}).
@c -- A new chapter -----------------------------------------------------------
@node Performance Data Collection
@@ -3456,8 +3488,8 @@ used to store the relevant information and forms the basis for a subsequent
analysis with one of the viewing tools.
@c -- A new section -----------------------------------------------------------
-@node The @CollectApp{} command
-@section The @CollectApp{} command
+@node The @command{gprofng collect app} Tool
+@section The @command{gprofng collect app} Tool
@c ----------------------------------------------------------------------------
This is the command to collect the performance information for the target
@@ -3483,8 +3515,8 @@ directories are available. In this chapter, these will all be covered in
detail.
@c -- A new section -----------------------------------------------------------
-@node The @code{gprofng display text} Tool
-@section The @code{gprofng display text} Tool
+@node The @command{gprofng display text} Tool
+@section The @command{gprofng display text} Tool
@c ----------------------------------------------------------------------------
This tool displays the performance information in ASCII format. It supports
@@ -3518,8 +3550,8 @@ or command, occurs multiple times, the rightmost setting is selected.
@c ----------------------------------------------------------------------------
The most commonly used commands are documented in the man page for this tool
-(@xref{gprofng display text}). In this section we list and describe all other
-commands that are supported.
+(@xref{Man page for @command{gprofng display text}}). In this section we list
+and describe all other commands that are supported.
@c -- A new sub subsection ----------------------------------------------------
@node Commands that List Experiment Details
@@ -4124,8 +4156,8 @@ Most of the functions correspond directly to the source model of the program, bu
there are exceptions. This topic is however outside of the scope of this guide.
@c ----------------------------------------------------------------------------
-@node The Concept of a CPU in @ProductName{}
-@section The Concept of a CPU in @ProductName{}
+@node The Concept of a CPU in gprofng
+@section The Concept of a CPU in gprofng
@c ----------------------------------------------------------------------------
@cindex CPU
@@ -4333,15 +4365,15 @@ in the make file in the @code{<my-build-dir/gprofng/doc} directory.
@end itemize
@c -- An appendix -------------------------------------------------------------
-@node The @ProductName{} Man Pages
-@appendix The @ProductName{} Man Pages
+@node The gprofng Man Pages
+@appendix The gprofng Man Pages
@c ----------------------------------------------------------------------------
In this appendix the man pages for the various @ProductName{} tools are listed.
@c -- A new node --------------------------------------------------------------
@c @node gprofng driver
-@node Man page for gprofng
+@node Man page for @command{gprofng}
@section Man page for @command{gprofng}
@c ----------------------------------------------------------------------------
@@ -4349,7 +4381,7 @@ In this appendix the man pages for the various @ProductName{} tools are listed.
@c -- A new node --------------------------------------------------------------
@page
-@node gprofng collect app
+@node Man page for @command{gprofng collect app}
@section Man page for @command{gprofng collect app}
@c ----------------------------------------------------------------------------
@@ -4357,7 +4389,7 @@ In this appendix the man pages for the various @ProductName{} tools are listed.
@c -- A new node --------------------------------------------------------------
@page
-@node gprofng display text
+@node Man page for @command{gprofng display text}
@section Man page for @command{gprofng display text}
@c ----------------------------------------------------------------------------
@@ -4365,7 +4397,7 @@ In this appendix the man pages for the various @ProductName{} tools are listed.
@c -- A new node --------------------------------------------------------------
@page
-@node gprofng display html
+@node Man page for @command{gprofng display html}
@section Man page for @command{gprofng display html}
@c ----------------------------------------------------------------------------
@@ -4373,7 +4405,7 @@ In this appendix the man pages for the various @ProductName{} tools are listed.
@c -- A new node --------------------------------------------------------------
@page
-@node gprofng display src
+@node Man page for @command{gprofng display src}
@section Man page for @command{gprofng display src}
@c ----------------------------------------------------------------------------
@@ -4381,7 +4413,7 @@ In this appendix the man pages for the various @ProductName{} tools are listed.
@c -- A new node --------------------------------------------------------------
@page
-@node gprofng archive
+@node Man page for @command{gprofng archive}
@section Man page for @command{gprofng archive}
@c ----------------------------------------------------------------------------
diff --git a/gprofng/doc/version.texi b/gprofng/doc/version.texi
index 9003d45572d..91da560975c 100644
--- a/gprofng/doc/version.texi
+++ b/gprofng/doc/version.texi
@@ -1,4 +1,4 @@
-@set UPDATED 4 September 2023
-@set UPDATED-MONTH September 2023
+@set UPDATED 28 November 2023
+@set UPDATED-MONTH November 2023
@set EDITION 2.41.50
-@set VERSION 2.41.50
+@set VERSION 2.2
--
2.31.1
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2023-11-28 19:58 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-11-28 19:58 [PATCH] gprofng: updated man pages and user guide vladimir.mezentsev
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).