mirror/binutils-gdb
2
0
Fork 0
mirror of https://sourceware.org/git/binutils-gdb.git synced 2025-01-18 12:24:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

gprofng: Update documentation

Browse Source 
This patch addresses bugzilla 29521:
Bug 29521 - [docs] man pages are not in the release tarball

The dependence on help2man to create the man pages has been eliminated.
All man pages are now written in Texinfo. Texi2pod and pod2man are used
to generate the man pages from the source.

The user guide has been significantly expanded. It also includes all
the man pages. These are formatted appropriately in the INFO, PDF, and
HTML formats.

The index in the user guide has been enhanced to include an overview
of all options and commands that have been documented so far.

The work on the documentation has not been completed, but this is
a significant step forward.

gprofng/ChangeLog
2023-04-15  Vladimir Mezentsev  <vladimir.mezentsev@oracle.com>

	PR gprofng/29521
	* doc/Makefile.am: Build documentation.
	* doc/gprofng.texi: Update documentation.
	* doc/version.texi: Likewise.
	* src/Makefile.am: Move the man pages generation to doc/Makefile.am.
	* gp-display-html/Makefile.am: Likewise.
	* doc/gp-archive.texi: New file.
	* doc/gp-collect-app.texi: New file.
	* doc/gp-display-html.texi: New file.
	* doc/gp-display-src.texi: New file.
	* doc/gp-display-text.texi: New file.
	* doc/gp-macros.texi: New file.
	* doc/gprofng_ug.texi: New file.
	* doc/Makefile.in: Rebuild.
	* gp-display-html/Makefile.in: Rebuild.
	* src/Makefile.in" Rebuild.
This commit is contained in:
Vladimir Mezentsev 2023-04-15 17:54:15 -07:00
parent 66cf935043
commit 7a515757db
15 changed files with 6371 additions and 3841 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
gprofng/doc/Makefile.am
View File

@ -19,6 +19,9 @@
AUTOMAKE_OPTIONS = info-in-builddir foreign no-texinfo.tex
PDFS = gprofng.pdf
HTMLS = gprofng.html
# Options to extract the man page
MANCONF = -Dman
@ -26,24 +29,31 @@ TEXI2POD = perl $(srcdir)/../../etc/texi2pod.pl $(AM_MAKEINFOFLAGS)
POD2MAN = pod2man --center="User Commands" \
--release="binutils-$(VERSION)" --section=1
info_TEXINFOS = gprofng.texi
gprofng_TEXINFOS = fdl.texi
info_TEXINFOS = gprofng_ug.texi
gprofng_ug_TEXINFOS = fdl.texi gp-macros.texi
TEXINFO_TEX = .
MAKEINFOHTML = $(MAKEINFO) --html --no-split
man_MANS = gprofng.1
man_MANS = gprofng.1 gp-archive.1 gp-collect-app.1 gp-display-html.1 gp-display-src.1 gp-display-text.1
# Build the man page from the texinfo file
# The sed command removes the no-adjust Nroff command so that
# the man output looks standard.
gprofng.1: $(srcdir)/gprofng.texi
$(man_MANS): $(srcdir)/gp-macros.texi
$(AM_V_GEN)touch $@
$(AM_V_at)-$(TEXI2POD) $(MANCONF) < $(srcdir)/gprofng.texi > gprofng.pod
$(AM_V_at)-($(POD2MAN) gprofng.pod | \
sed -e '/^.if n .na/d' > $@.tmp && \
$(AM_V_at)-$(TEXI2POD) $(MANCONF) < $(srcdir)/`basename $@ .1`.texi > $@.pod
$(AM_V_at)-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.tmp && \
mv -f $@.tmp $@) || (rm -f $@.tmp && exit 1)
$(AM_V_at)rm -f gprofng.pod
$(AM_V_at)rm -f $@.pod
gprofng.1: $(srcdir)/gprofng.texi
gp-archive.1: $(srcdir)/gp-archive.texi
gp-collect-app.1: $(srcdir)/gp-collect-app.texi
gp-display-html.1: $(srcdir)/gp-display-html.texi
gp-display-src.1: $(srcdir)/gp-display-src.texi
gp-display-text.1: $(srcdir)/gp-display-text.texi
MAINTAINERCLEANFILES = gprofng.info $(man_MANS)
EXTRA_DIST = $(man_MANS) version.texi
info: $(man_MANS)

59
gprofng/doc/Makefile.in
View File

@ -168,11 +168,9 @@ am__v_texidevnull_0 = > /dev/null
am__v_texidevnull_1 =
INFO_DEPS = gprofng.info
am__TEXINFO_TEX_DIR = $(srcdir)/.
DVIS = gprofng.dvi
PDFS = gprofng.pdf
PSS = gprofng.ps
HTMLS = gprofng.html
TEXINFOS = gprofng.texi
DVIS = gprofng_ug.dvi
PSS = gprofng_ug.ps
TEXINFOS = gprofng_ug.texi
TEXI2DVI = texi2dvi
TEXI2PDF = $(TEXI2DVI) --pdf --batch
AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS)
@ -214,7 +212,7 @@ man1dir = $(mandir)/man1
NROFF = nroff
MANS = $(man_MANS)
am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
am__DIST_COMMON = $(gprofng_TEXINFOS) $(srcdir)/Makefile.in \
am__DIST_COMMON = $(gprofng_ug_TEXINFOS) $(srcdir)/Makefile.in \
$(top_srcdir)/../mkinstalldirs mdate-sh texinfo.tex
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
ACLOCAL = @ACLOCAL@
@ -364,6 +362,8 @@ top_srcdir = @top_srcdir@
zlibdir = @zlibdir@
zlibinc = @zlibinc@
AUTOMAKE_OPTIONS = info-in-builddir foreign no-texinfo.tex
PDFS = gprofng.pdf
HTMLS = gprofng.html
# Options to extract the man page
MANCONF = -Dman
@ -371,12 +371,13 @@ TEXI2POD = perl $(srcdir)/../../etc/texi2pod.pl $(AM_MAKEINFOFLAGS)
POD2MAN = pod2man --center="User Commands" \
--release="binutils-$(VERSION)" --section=1
info_TEXINFOS = gprofng.texi
gprofng_TEXINFOS = fdl.texi
info_TEXINFOS = gprofng_ug.texi
gprofng_ug_TEXINFOS = fdl.texi gp-macros.texi
TEXINFO_TEX = .
MAKEINFOHTML = $(MAKEINFO) --html --no-split
man_MANS = gprofng.1
man_MANS = gprofng.1 gp-archive.1 gp-collect-app.1 gp-display-html.1 gp-display-src.1 gp-display-text.1
MAINTAINERCLEANFILES = gprofng.info $(man_MANS)
EXTRA_DIST = $(man_MANS) version.texi
all: all-am
.SUFFIXES:
@ -417,7 +418,7 @@ mostlyclean-libtool:
clean-libtool:
-rm -rf .libs _libs
gprofng.info: gprofng.texi $(srcdir)/version.texi $(gprofng_TEXINFOS)
gprofng.info: gprofng_ug.texi $(srcdir)/version.texi $(gprofng_ug_TEXINFOS)
$(AM_V_MAKEINFO)restore=: && backupdir="$(am__leading_dot)am$$$$" && \
rm -rf $$backupdir && mkdir $$backupdir && \
if ($(MAKEINFO) --version) >/dev/null 2>&1; then \
@ -426,7 +427,7 @@ gprofng.info: gprofng.texi $(srcdir)/version.texi $(gprofng_TEXINFOS)
done; \
else :; fi && \
if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \
-o $@ `test -f 'gprofng.texi' || echo '$(srcdir)/'`gprofng.texi; \
-o $@ `test -f 'gprofng_ug.texi' || echo '$(srcdir)/'`gprofng_ug.texi; \
then \
rc=0; \
else \
@ -435,31 +436,31 @@ gprofng.info: gprofng.texi $(srcdir)/version.texi $(gprofng_TEXINFOS)
fi; \
rm -rf $$backupdir; exit $$rc
gprofng.dvi: gprofng.texi $(srcdir)/version.texi $(gprofng_TEXINFOS)
gprofng.dvi: gprofng_ug.texi $(srcdir)/version.texi $(gprofng_ug_TEXINFOS)
$(AM_V_TEXI2DVI)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
$(TEXI2DVI) $(AM_V_texinfo) --build-dir=$(@:.dvi=.t2d) -o $@ $(AM_V_texidevnull) \
`test -f 'gprofng.texi' || echo '$(srcdir)/'`gprofng.texi
`test -f 'gprofng_ug.texi' || echo '$(srcdir)/'`gprofng_ug.texi
gprofng.pdf: gprofng.texi $(srcdir)/version.texi $(gprofng_TEXINFOS)
gprofng.pdf: gprofng_ug.texi $(srcdir)/version.texi $(gprofng_ug_TEXINFOS)
$(AM_V_TEXI2PDF)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
$(TEXI2PDF) $(AM_V_texinfo) --build-dir=$(@:.pdf=.t2p) -o $@ $(AM_V_texidevnull) \
`test -f 'gprofng.texi' || echo '$(srcdir)/'`gprofng.texi
`test -f 'gprofng_ug.texi' || echo '$(srcdir)/'`gprofng_ug.texi
gprofng.html: gprofng.texi $(srcdir)/version.texi $(gprofng_TEXINFOS)
gprofng.html: gprofng_ug.texi $(srcdir)/version.texi $(gprofng_ug_TEXINFOS)
$(AM_V_MAKEINFO)rm -rf $(@:.html=.htp)
$(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \
-o $(@:.html=.htp) `test -f 'gprofng.texi' || echo '$(srcdir)/'`gprofng.texi; \
-o $(@:.html=.htp) `test -f 'gprofng_ug.texi' || echo '$(srcdir)/'`gprofng_ug.texi; \
then \
rm -rf $@ && mv $(@:.html=.htp) $@; \
else \
rm -rf $(@:.html=.htp); exit 1; \
fi
$(srcdir)/version.texi: @MAINTAINER_MODE_TRUE@ $(srcdir)/stamp-vti
$(srcdir)/stamp-vti: gprofng.texi $(top_srcdir)/configure
@(dir=.; test -f ./gprofng.texi || dir=$(srcdir); \
set `$(SHELL) $(srcdir)/mdate-sh $$dir/gprofng.texi`; \
$(srcdir)/stamp-vti: gprofng_ug.texi $(top_srcdir)/configure
@(dir=.; test -f ./gprofng_ug.texi || dir=$(srcdir); \
set `$(SHELL) $(srcdir)/mdate-sh $$dir/gprofng_ug.texi`; \
echo "@set UPDATED $$1 $$2 $$3"; \
echo "@set UPDATED-MONTH $$2 $$3"; \
echo "@set EDITION $(VERSION)"; \
@ -557,7 +558,7 @@ dist-info: $(INFO_DEPS)
done
mostlyclean-aminfo:
-rm -rf gprofng.t2d gprofng.t2p
-rm -rf gprofng_ug.t2d gprofng_ug.t2p
clean-aminfo:
-test -z "gprofng.dvi gprofng.pdf gprofng.ps gprofng.html" \
@ -874,13 +875,19 @@ uninstall-man: uninstall-man1
# Build the man page from the texinfo file
# The sed command removes the no-adjust Nroff command so that
# the man output looks standard.
gprofng.1: $(srcdir)/gprofng.texi
$(man_MANS): $(srcdir)/gp-macros.texi
$(AM_V_GEN)touch $@
$(AM_V_at)-$(TEXI2POD) $(MANCONF) < $(srcdir)/gprofng.texi > gprofng.pod
$(AM_V_at)-($(POD2MAN) gprofng.pod | \
sed -e '/^.if n .na/d' > $@.tmp && \
$(AM_V_at)-$(TEXI2POD) $(MANCONF) < $(srcdir)/`basename $@ .1`.texi > $@.pod
$(AM_V_at)-($(POD2MAN) $@.pod | sed -e '/^.if n .na/d' > $@.tmp && \
mv -f $@.tmp $@) || (rm -f $@.tmp && exit 1)
$(AM_V_at)rm -f gprofng.pod
$(AM_V_at)rm -f $@.pod
gprofng.1: $(srcdir)/gprofng.texi
gp-archive.1: $(srcdir)/gp-archive.texi
gp-collect-app.1: $(srcdir)/gp-collect-app.texi
gp-display-html.1: $(srcdir)/gp-display-html.texi
gp-display-src.1: $(srcdir)/gp-display-src.texi
gp-display-text.1: $(srcdir)/gp-display-text.texi
info: $(man_MANS)

246
gprofng/doc/gp-archive.texi Normal file
View File

@ -0,0 +1,246 @@
@c ----------------------------------------------------------------------------
@c This is the Texinfo source file for the gp-collect-app man page.
@c
@c Author: Ruud van der Pas
@c ----------------------------------------------------------------------------
@ifset man
\input texinfo @c -*-texinfo-*-
@setfilename gprofng archive
@settitle Archive gprofng experiment data
@include gp-macros.texi
@end ifset
@c ----------------------------------------------------------------------------
@c This is from the man-pages(7) man page
@c
@c "The list below shows conventional or suggested sections. Most manual pages
@c should include at least the highlighted sections. Arrange a new manual
@c page so that sections are placed in the order shown in the list."
@c
@c NAME
@c SYNOPSIS
@c CONFIGURATION [Normally only in Section 4]
@c DESCRIPTION
@c OPTIONS [Normally only in Sections 1, 8]
@c EXIT STATUS [Normally only in Sections 1, 8]
@c RETURN VALUE [Normally only in Sections 2, 3]
@c ERRORS [Typically only in Sections 2, 3]
@c ENVIRONMENT
@c FILES
@c VERSIONS [Normally only in Sections 2, 3]
@c ATTRIBUTES [Normally only in Sections 2, 3]
@c CONFORMING TO
@c NOTES
@c BUGS
@c EXAMPLES
@c AUTHORS [Discouraged]
@c REPORTING BUGS [Not used in man-pages]
@c COPYRIGHT [Not used in man-pages]
@c SEE ALSO
@c
@c This is what the texi2pod.pl tool recognizes:
@c
@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
@c BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
@c
@c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
@c makes sense and adhered to for the other formats.
@c ----------------------------------------------------------------------------
@c ----------------------------------------------------------------------------
@c NAME section
@c ----------------------------------------------------------------------------
@ManPageStart{NAME}
@c man begin NAME
gprofng archive - Archive gprofng experiment data
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c SYNOPSIS section
@c ----------------------------------------------------------------------------
@ManPageStart{SYNOPSIS}
@c man begin SYNOPSIS
@command{gprofng archive} [@var{option(s)}] @var{experiment}
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c DESCRIPTION section
@c ----------------------------------------------------------------------------
@ManPageStart{DESCRIPTION}
@c man begin DESCRIPTION
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.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c OPTIONS section
@c ----------------------------------------------------------------------------
@ManPageStart{OPTIONS}
@c man begin OPTIONS
@table @gcctabopt
@item --version
@ifclear man
@IndexSubentry{Options, @code{--version}}
@end ifclear
Print the version number and exit.
@item --help
@ifclear man
@IndexSubentry{Options, @code{--help}}
@end ifclear
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@}
@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.
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}.
@item -n
@ifclear man
@IndexSubentry{Options, @code{-n}}
@end ifclear
Archive the named experiment only, not any of its descendants.
@item -m @var{regex}
@ifclear man
@IndexSubentry{Options, @code{-m}}
@end ifclear
Archive only those source, object, and debug info files whose full path name
matches the given POSIX compliant @var{regex} regular expression.
@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}.
@item -F
@ifclear man
@IndexSubentry{Options, @code{-F}}
@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.
@item -d @var{path}
@ifclear man
@IndexSubentry{Options, @code{-d}}
@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.
@end table
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c NOTES section
@c ----------------------------------------------------------------------------
@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.
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.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c SEEALSO section
@c ----------------------------------------------------------------------------
@ManPageStart{SEEALSO}
@c man begin SEEALSO
gprofng(1), gp-collect-app(1), gp-display-html(1), gp-display-src(1), gp-display-text(1)
The user guide for gprofng is maintained as a Texinfo manual. If the info
and gprofng programs are correctly installed, the command
@command{info gprofng} should give access to this document.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c COPYRIGHT section
@c ----------------------------------------------------------------------------
@ManPageStart{COPYRIGHT}
@c man begin COPYRIGHT
Copyright @copyright{} 2022-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled ``GNU Free Documentation License''.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c If this text is used for a man page, exit. Otherwise we need to continue.
@c ----------------------------------------------------------------------------
@ifset man
@bye
@end ifset

380
gprofng/doc/gp-collect-app.texi Normal file
View File

@ -0,0 +1,380 @@
@c ----------------------------------------------------------------------------
@c This is the Texinfo source file for the gp-collect-app man page.
@c
@c Author: Ruud van der Pas
@c ----------------------------------------------------------------------------
@ifset man
\input texinfo @c -*-texinfo-*-
@setfilename gprofng collect app
@settitle Collect performance data for the target application
@include gp-macros.texi
@end ifset
@c ----------------------------------------------------------------------------
@c This is from the man-pages(7) man page
@c
@c "The list below shows conventional or suggested sections. Most manual pages
@c should include at least the highlighted sections. Arrange a new manual
@c page so that sections are placed in the order shown in the list."
@c
@c NAME
@c SYNOPSIS
@c CONFIGURATION [Normally only in Section 4]
@c DESCRIPTION
@c OPTIONS [Normally only in Sections 1, 8]
@c EXIT STATUS [Normally only in Sections 1, 8]
@c RETURN VALUE [Normally only in Sections 2, 3]
@c ERRORS [Typically only in Sections 2, 3]
@c ENVIRONMENT
@c FILES
@c VERSIONS [Normally only in Sections 2, 3]
@c ATTRIBUTES [Normally only in Sections 2, 3]
@c CONFORMING TO
@c NOTES
@c BUGS
@c EXAMPLES
@c AUTHORS [Discouraged]
@c REPORTING BUGS [Not used in man-pages]
@c COPYRIGHT [Not used in man-pages]
@c SEE ALSO
@c
@c This is what the texi2pod.pl tool recognizes:
@c
@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
@c BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
@c
@c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
@c makes sense and adhered to for the other formats.
@c ----------------------------------------------------------------------------
@c ----------------------------------------------------------------------------
@c NAME section
@c ----------------------------------------------------------------------------
@ManPageStart{NAME}
@c man begin NAME
gprofng collect app - Collect performance data for the target program
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c SYNOPSIS section
@c ----------------------------------------------------------------------------
@ManPageStart{SYNOPSIS}
@c man begin SYNOPSIS
@command{gprofng collect app} [@var{option(s)}] @var{target} [@var{option(s)}]
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c DESCRIPTION section
@c ----------------------------------------------------------------------------
@ManPageStart{DESCRIPTION}
@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.
For example, this command collects performance data for an executable called
@samp{a.out} and stores the data collected in an experiment directory with
the name @samp{example.er}.
@smallexample
$ gprofng collect app -o example.er ./a.out
@end smallexample
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c OPTIONS section
@c ----------------------------------------------------------------------------
@ManPageStart{OPTIONS}
@c man begin OPTIONS
@table @gcctabopt
@item --version
@ifclear man
@IndexSubentry{Options, @code{--version}}
@end ifclear
Print the version number and exit.
@item --help
@ifclear man
@IndexSubentry{Options, @code{--help}}
@end ifclear
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 -p @{off|on|lo|hi|@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}).
@item -h @var{@{<ctr_def>...,<ctr_n_def>@}}
@ifclear man
@IndexSubentry{Options, @code{-h}}
@end ifclear
Enable hardware event counter profiling and select the counter(s).
To see the supported counters on this system, use the @samp{-h} option
without other arguments.
@item -o @var{<exp_name>}
@ifclear man
@IndexSubentry{Options, @code{-o}}
@end ifclear
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}).
@item -O @var{<exp_name>}
@ifclear man
@IndexSubentry{Options, @code{-O}}
@end ifclear
This is the same as the @samp{-o} option, but unlike this option, silently
overwrites an existing experiment directory with the same name.
@item -C @var{<comment_string>}
@ifclear man
@IndexSubentry{Options, @code{-C}}
@end ifclear
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.
@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}
@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}.
@item off
Does 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>}.
@end table
@item -J @var{<jvm-options>}
@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.
Each item is passed as a separate option to the JVM. Note that this option
implies @samp{-j on}.
@item -t @var{<duration>}[m|s]
@ifclear man
@IndexSubentry{Options, @code{-t}}
@end ifclear
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.
@item -n
@ifclear man
@IndexSubentry{Options, @code{-n}}
@end ifclear
This is used for a dry run. Several run-time settings are displayed, but the
target is not executed and no performance data is collected.
@item -F @{off|on|=@var{regex}@}
@ifclear man
@IndexSubentry{Options, @code{-F}}
@end ifclear
Control whether descendant processes should have their data recorded.
To disable/enable this feature, use @samp{off}/@samp{on}. Use
@samp{=}@var{regex} to record data on those processes whose executable name
matches the regular expression. Only the basename of the executable is used,
not the full path. If spaces or characters interpreted by the shell are used,
enclose the @var{regex} in single quotes. The default is @samp{-F on}.
@item -a @{off|on|ldobjects|src|usedldobjects|usedsrc@}
@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.
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}.
@item -S @{off|on|@var{<seconds>}@}
@ifclear man
@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}.
@item -y @var{<signal>}[,r]
@ifclear man
@IndexSubentry{Options, @code{-y}}
@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
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
@samp{r} is given, data collection begins in the resumed state and data
collection begins immediately.
SIGUSR1 or SIGUSR2 are recommended for this use, but any signal that is
not used by the target can be used.
@item -l @var{<signal>}
@ifclear man
@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.
The signal can be specified using the full name, without the initial
letters @code{SIG}, or the signal number. Note that the @command{kill}
command can be used to deliver a signal.
If both the @samp{-l} and @samp{-y} options are used, the signal must be
different.
@item -s @var{<option>}[,@var{<API>}]
@ifclear man
@IndexSubentry{Options, @code{-s}}
@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
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}.
@item -H @{off|on@}
@ifclear man
@IndexSubentry{Options, @code{-H}}
@end ifclear
Disable (off), or enable (on) heap tracing. The default is @samp{-H off}.
@item -i @{off|on@}
@ifclear man
@IndexSubentry{Options, @code{-i}}
@end ifclear
Disable (off), or enable (on) I/O tracing. The default is @samp{-i off}.
@end table
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c NOTES section
@c ----------------------------------------------------------------------------
@ManPageStart{NOTES}
@c man begin NOTES
Any executable in the ELF (Executable and Linkable Format) object format can
be used for profiling with gprofng. If debug information is available,
gprofng can provide more details, but this is not a requirement.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c SEEALSO section
@c ----------------------------------------------------------------------------
@ManPageStart{SEEALSO}
@c man begin SEEALSO
gprofng(1), gp-archive(1), gp-display-html(1), gp-display-src(1), gp-display-text(1)
The user guide for gprofng is maintained as a Texinfo manual. If the
@command{info} and @command{gprofng} programs are correctly installed, the
command @command{info gprofng} should give access to this document.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c COPYRIGHT section
@c ----------------------------------------------------------------------------
@ManPageStart{COPYRIGHT}
@c man begin COPYRIGHT
Copyright @copyright{} 2022-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled ``GNU Free Documentation License''.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c If this text is used for a man page, exit. Otherwise we need to continue.
@c ----------------------------------------------------------------------------
@ifset man
@bye
@end ifset

252
gprofng/doc/gp-display-html.texi Normal file
View File

@ -0,0 +1,252 @@
@c ----------------------------------------------------------------------------
@c This is the Texinfo source file for the gp-collect-app man page.
@c
@c Author: Ruud van der Pas
@c ----------------------------------------------------------------------------
@ifset man
\input texinfo @c -*-texinfo-*-
@setfilename gprofng display html
@settitle Generate an HTML based directory structure to browse the profiles
@include gp-macros.texi
@end ifset
@c ----------------------------------------------------------------------------
@c This is from the man-pages(7) man page
@c
@c "The list below shows conventional or suggested sections. Most manual pages
@c should include at least the highlighted sections. Arrange a new manual
@c page so that sections are placed in the order shown in the list."
@c
@c NAME
@c SYNOPSIS
@c CONFIGURATION [Normally only in Section 4]
@c DESCRIPTION
@c OPTIONS [Normally only in Sections 1, 8]
@c EXIT STATUS [Normally only in Sections 1, 8]
@c RETURN VALUE [Normally only in Sections 2, 3]
@c ERRORS [Typically only in Sections 2, 3]
@c ENVIRONMENT
@c FILES
@c VERSIONS [Normally only in Sections 2, 3]
@c ATTRIBUTES [Normally only in Sections 2, 3]
@c CONFORMING TO
@c NOTES
@c BUGS
@c EXAMPLES
@c AUTHORS [Discouraged]
@c REPORTING BUGS [Not used in man-pages]
@c COPYRIGHT [Not used in man-pages]
@c SEE ALSO
@c
@c This is what the texi2pod.pl tool recognizes:
@c
@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
@c BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
@c
@c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
@c makes sense and adhered to for the other formats.
@c ----------------------------------------------------------------------------
@c ----------------------------------------------------------------------------
@c NAME section
@c ----------------------------------------------------------------------------
@ManPageStart{NAME}
@c man begin NAME
gprofng display html - Generate an HTML based directory structure to browse the profiles
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c SYNOPSIS section
@c ----------------------------------------------------------------------------
@ManPageStart{SYNOPSIS}
@c man begin SYNOPSIS
@command{gprofng display html} [@var{option(s)}] @var{experiment(s)}
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c DESCRIPTION section
@c ----------------------------------------------------------------------------
@ManPageStart{DESCRIPTION}
@c man begin DESCRIPTION
Process one or more experiments to generate a directory containing the
@file{index.html} file that may be used to browse the experiment data.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c OPTIONS section
@c ----------------------------------------------------------------------------
@ManPageStart{OPTIONS}
@c man begin OPTIONS
@table @gcctabopt
@item --version
@ifclear man
@IndexSubentry{Options, @code{--version}}
@end ifclear
Print the version number and exit.
@item --help
@ifclear man
@IndexSubentry{Options, @code{--help}}
@end ifclear
Print usage information and exit.
@item --verbose @{on|off@}
@ifclear man
@IndexSubentry{Options, @code{--verbose}}
@end ifclear
Enable (@samp{on}) or disable (@samp{off)} verbose mode.
The default is @samp{off}.
@item --debug @{on|s|m|l|xl|off@}
@item -d @{on|s|m|l|xl|off@}
@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.
Note that currently @samp{on}, @samp{s}, @samp{m}, and @samp{l} are
equivalent. This is expected to change in future updates.
@item ---highlight-percentage @var{value}
@item -hp @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 (%).
A value of zero @samp{(-hp 0)} disables this feature.
@item --output @var{dirname}
@item -o @var{dirname}
@ifclear man
@IndexSubentry{Options, @code{--output}}
@IndexSubentry{Options, @code{-o}}
@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.
@item --overwrite @var{dirname}
@item -O @var{dirname}
@ifclear man
@IndexSubentry{Options, @code{--overwrite}}
@IndexSubentry{Options, @code{-O}}
@end ifclear
Use @var{dirname} as the directory name to store the HTML files in.
@item --quiet @{on|off@}
@item -q @{on|off@}
@ifclear man
@IndexSubentry{Options, @code{--quiet}}
@IndexSubentry{Options, @code{-q}}
@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}).
@item --warnings @{on|off@}
@item -w @{on|off@}
@ifclear man
@IndexSubentry{Options, @code{--warnings}}
@IndexSubentry{Options, @code{-w}}
@end ifclear
Enable (@samp{on}), or disable (@samp{off}) run time warning messages from
the tool. By default these are enabled.
@end table
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c NOTES section
@c ----------------------------------------------------------------------------
@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.
Regardless of the setting for the warning messages, any warnings are accessible
through the main @file{index.html} page.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c SEEALSO section
@c ----------------------------------------------------------------------------
@ManPageStart{SEEALSO}
@c man begin SEEALSO
gprofng(1), gp-archive(1), gp-collect-app(1), gp-display-src(1), gp-display-text(1)
The user guide for gprofng is maintained as a Texinfo manual. If the
@command{info} and @command{gprofng} programs are correctly installed, the
command @command{info gprofng} should give access to this document.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c COPYRIGHT section
@c ----------------------------------------------------------------------------
@ManPageStart{COPYRIGHT}
@c man begin COPYRIGHT
Copyright @copyright{} 2022-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled ``GNU Free Documentation License''.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c If this text is used for a man page, exit. Otherwise we need to continue.
@c ----------------------------------------------------------------------------
@ifset man
@bye
@end ifset

246
gprofng/doc/gp-display-src.texi Normal file
View File

@ -0,0 +1,246 @@
@c ----------------------------------------------------------------------------
@c This is the Texinfo source file for the gp-collect-app 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
@include gp-macros.texi
@end ifset
@c ----------------------------------------------------------------------------
@c This is from the man-pages(7) man page
@c
@c "The list below shows conventional or suggested sections. Most manual pages
@c should include at least the highlighted sections. Arrange a new manual
@c page so that sections are placed in the order shown in the list."
@c
@c NAME
@c SYNOPSIS
@c CONFIGURATION [Normally only in Section 4]
@c DESCRIPTION
@c OPTIONS [Normally only in Sections 1, 8]
@c EXIT STATUS [Normally only in Sections 1, 8]
@c RETURN VALUE [Normally only in Sections 2, 3]
@c ERRORS [Typically only in Sections 2, 3]
@c ENVIRONMENT
@c FILES
@c VERSIONS [Normally only in Sections 2, 3]
@c ATTRIBUTES [Normally only in Sections 2, 3]
@c CONFORMING TO
@c NOTES
@c BUGS
@c EXAMPLES
@c AUTHORS [Discouraged]
@c REPORTING BUGS [Not used in man-pages]
@c COPYRIGHT [Not used in man-pages]
@c SEE ALSO
@c
@c This is what the texi2pod.pl tool recognizes:
@c
@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
@c BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
@c
@c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
@c makes sense and adhered to for the other formats.
@c ----------------------------------------------------------------------------
@c ----------------------------------------------------------------------------
@c NAME section
@c ----------------------------------------------------------------------------
@ManPageStart{NAME}
@c man begin NAME
gprofng display src - Display the source code, optionally interleaved with the disassembly of the target object
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c SYNOPSIS section
@c ----------------------------------------------------------------------------
@ManPageStart{SYNOPSIS}
@c man begin SYNOPSIS
@command{gprofng display src} [@var{option(s)}] @var{target_file}
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c DESCRIPTION section
@c ----------------------------------------------------------------------------
@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).
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
@end smallexample
To list the source code and disassembly for all the functions in this file,
use the following command:
@smallexample
$ 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
file (.o), or a Java .class 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.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c OPTIONS section
@c ----------------------------------------------------------------------------
@ManPageStart{OPTIONS}
@c man begin OPTIONS
@table @gcctabopt
@item --version
@ifclear man
@IndexSubentry{Options, @code{--version}}
@end ifclear
Print the version number and exit.
@item --help
@ifclear man
@IndexSubentry{Options, @code{--help}}
@end ifclear
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}}
@IndexSubentry{Commands, @code{functions}}
@end ifclear
List all the functions from the given object.
@item -source @var{item} @var{tag}
@ifclear man
@IndexSubentry{Options, @code{-source}}
@IndexSubentry{Commands, @code{source}}
@end ifclear
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}.
@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
of the disassembly only.
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.
@end table
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c NOTES section
@c ----------------------------------------------------------------------------
@ManPageStart{NOTES}
@c man begin NOTES
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
be ignored if not necessary to resolve the function.
The @var{item} may also be specified in the form @samp{function`file`}, in
which case the source or disassembly of the named function in the source
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}.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c SEEALSO section
@c ----------------------------------------------------------------------------
@ManPageStart{SEEALSO}
@c man begin SEEALSO
gprofng(1), gp-archive(1), gp-collect-app(1), gp-display-html(1), gp-display-text(1)
The user guide for gprofng is maintained as a Texinfo manual. If the info
and gprofng programs are correctly installed, the command
@command{info gprofng} should give access to this document.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c COPYRIGHT section
@c ----------------------------------------------------------------------------
@ManPageStart{COPYRIGHT}
@c man begin COPYRIGHT
Copyright @copyright{} 2022-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled ``GNU Free Documentation License''.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c If this text is used for a man page, exit. Otherwise we need to continue.
@c ----------------------------------------------------------------------------
@ifset man
@bye
@end ifset

437
gprofng/doc/gp-display-text.texi Normal file
View File

@ -0,0 +1,437 @@
@c ----------------------------------------------------------------------------
@c This is the Texinfo source file for the gp-collect-app man page.
@c
@c Author: Ruud van der Pas
@c ----------------------------------------------------------------------------
@ifset man
\input texinfo @c -*-texinfo-*-
@setfilename gprofng display text
@settitle Display the performance data in plain text format
@include gp-macros.texi
@end ifset
@c ----------------------------------------------------------------------------
@c This is from the man-pages(7) man page
@c
@c "The list below shows conventional or suggested sections. Most manual pages
@c should include at least the highlighted sections. Arrange a new manual
@c page so that sections are placed in the order shown in the list."
@c
@c NAME
@c SYNOPSIS
@c CONFIGURATION [Normally only in Section 4]
@c DESCRIPTION
@c OPTIONS [Normally only in Sections 1, 8]
@c EXIT STATUS [Normally only in Sections 1, 8]
@c RETURN VALUE [Normally only in Sections 2, 3]
@c ERRORS [Typically only in Sections 2, 3]
@c ENVIRONMENT
@c FILES
@c VERSIONS [Normally only in Sections 2, 3]
@c ATTRIBUTES [Normally only in Sections 2, 3]
@c CONFORMING TO
@c NOTES
@c BUGS
@c EXAMPLES
@c AUTHORS [Discouraged]
@c REPORTING BUGS [Not used in man-pages]
@c COPYRIGHT [Not used in man-pages]
@c SEE ALSO
@c
@c This is what the texi2pod.pl tool recognizes:
@c
@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
@c BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
@c
@c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
@c makes sense and adhered to for the other formats.
@c ----------------------------------------------------------------------------
@c ----------------------------------------------------------------------------
@c NAME section
@c ----------------------------------------------------------------------------
@ManPageStart{NAME}
@c man begin NAME
gprofng display text - Display the performance data in plain text format
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c SYNOPSIS section
@c ----------------------------------------------------------------------------
@ManPageStart{SYNOPSIS}
@c man begin SYNOPSIS
@command{gprofng display text} [@var{option(s)}] [@var{commands}]
[-script @var{script-file}] @var{experiment(s)}
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c DESCRIPTION section
@c ----------------------------------------------------------------------------
@ManPageStart{DESCRIPTION}
@c man begin DESCRIPTION
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
lists all the commands supported.
Commands specified on the command line need to be prepended with the dash ('-')
symbol.
In this example, a function overview will be shown, followed by the source
code listing of function @samp{my-func}, annotated with the
performance metrics that have been recorded during the data collection
and stored in experiment directory @samp{my-exp.er}:
@smallexample
$ gprofng display text -functions -source my-func my-exp.er
@end smallexample
Instead of, or in addition to, specifying these commands on the command line,
commands may also be included in a file called the @var{script-file}.
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.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c OPTIONS section
@c ----------------------------------------------------------------------------
@ManPageStart{OPTIONS}
@c man begin OPTIONS
@table @gcctabopt
@item --version
@ifclear man
@IndexSubentry{Options, @code{--version}}
@end ifclear
Print the version number and exit.
@item --help
@ifclear man
@IndexSubentry{Options, @code{--help}}
@end ifclear
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}}
@IndexSubentry{Commands, @code{script}}
@end ifclear
Execute the commands stored in the script file. This feature may be combined
with commands specified at the command line.
@end table
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c NOTES section
@c ----------------------------------------------------------------------------
@ManPageStart{NOTES}
@c man begin NOTES
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.
@end ifset
@table @code
@item callers-callees
@ifclear man
@IndexSubentry{Options, @code{-callers-callees}}
@IndexSubentry{Commands, @code{callers-callees}}
@end ifclear
In a callers-callees panel, it is shown which function(s) call the target
function (the @emph{callers}) and what functions it is calling (the
@emph{callees}).
This command prints the callers-callees panel for each of the functions,
in the order specified by the function sort metric.
@item calltree
@ifclear man
@IndexSubentry{Options, @code{-calltree}}
@IndexSubentry{Commands, @code{calltree}}
@end ifclear
Display the dynamic call graph from the experiment, showing the hierarchical
metrics at each level.
@item compare @{on | off | delta | ratio@}
@ifclear man
@IndexSubentry{Options, @code{-compare}}
@IndexSubentry{Commands, @code{compare}}
@end ifclear
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:
@table @code
@item on
For each experiment specified on the command line, print the values for
the metrics that have been activated for the experiment.
@item off
Disable the comparison of experiments. This is the default.
@item delta
Print the values for the reference experiment. The results for the other
experiments are shown as a delta relative to the reference (current-reference).
@item ratio
Print the values for the reference experiment. The results for the other
experiments are shown as a ratio relative to the reference (current/reference).
@end table
@item disasm @var{function-name}
@ifclear man
@IndexSubentry{Options, @code{-disasm}}
@IndexSubentry{Commands, @code{disasm}}
@end ifclear
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}]
@ifclear man
@IndexSubentry{Options, @code{-fsingle}}
@IndexSubentry{Commands, @code{fsingle}}
@end ifclear
Write a summary panel for the specified function. The optional parameter
@var{n} is needed for those cases where several functions have the same name.
@item fsummary
@ifclear man
@IndexSubentry{Options, @code{-fsummary}}
@IndexSubentry{Commands, @code{fsummary}}
@end ifclear
Write a summary panel for each function in the function list.
@item functions
@ifclear man
@IndexSubentry{Options, @code{-functions}}
@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.
@item header
@ifclear man
@IndexSubentry{Options, @code{-header}}
@IndexSubentry{Commands, @code{header}}
@end ifclear
Shows several operational characteristics of the experiment(s) specified
on the command line.
@item limit @var{n}
@ifclear man
@IndexSubentry{Options, @code{-limit}}
@IndexSubentry{Commands, @code{limit}}
@end ifclear
Limit the output to @var{n} lines.
@item lines
@ifclear man
@IndexSubentry{Options, @code{-lines}}
@IndexSubentry{Commands, @code{lines}}
@end ifclear
Write a list of source lines and their metrics, ordered by the current
sort metric.
@item metric_list
@ifclear man
@IndexSubentry{Options, @code{-metric_list}}
@IndexSubentry{Commands, @code{metric_list}}
@end ifclear
Display the currently selected metrics in the function view and a list
of all the metrics available for the target experiment(s).
@item metrics @var{metric-spec}
@ifclear man
@IndexSubentry{Options, @code{-metrics}}
@IndexSubentry{Commands, @code{metrics}}
@end ifclear
Define the metrics to be displayed in the function and callers-callees
overviews.
The @var{metric-spec} can either be the keyword @samp{default}
to restore the default metrics selection, or a colon separated list
with metrics.
The gprofng user guide has more details how to define metrics.
@item name @{short | long | mangled@}[:@{soname | nosoname@}]
@ifclear man
@IndexSubentry{Options, @code{-name}}
@IndexSubentry{Commands, @code{name}}
@end ifclear
Specify whether to use the short, long, or mangled form of function names.
Optionally, the load object that the function is part of can be included in
the output by adding the @emph{soname} keyword. It can also be ommitted
(@emph{nosoname}), which is the default.
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
colon (@samp{:}).
@item overview
@ifclear man
@IndexSubentry{Options, @code{-overview}}
@IndexSubentry{Commands, @code{overview}}
@end ifclear
Shows a summary of the recorded performance data for the experiment(s)
specified on the command line.
@item pcs
@ifclear man
@IndexSubentry{Options, @code{-pcs}}
@IndexSubentry{Commands, @code{pcs}}
@end ifclear
Write a list of program counters (PCs) and their metrics, ordered by
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.
@IndexSubentry{Sort, Reverse order}
The data can be sorted in reverse order by prepending the metric definition
with a minus (@samp{-}) sign.
@noindent
For example @command{sort -e.totalcpu}.
@IndexSubentry{Sort, Reset to default}
A default metric for the sort operation has been defined and since this is
a persistent command, this default can be restored with @code{default} as
the key (@command{sort default}).
@item source @var{function-name}
@ifclear man
@IndexSubentry{Options, @code{-source}}
@IndexSubentry{Commands, @code{source}}
@end ifclear
List the source code for the function specified, annotated with the metrics
used.
@item viewmode @{user | expert | machine@}
@ifclear man
@IndexSubentry{Options, @code{-viewmode}}
@IndexSubentry{Commands, @code{viewmode}}
@end ifclear
This command is only relevant for Java programs. For all other languages
supported, the viewmode setting has no effect.
The following options are supported:
@table @code
@item user
Show the Java call stacks for Java threads, but do not show housekeeping
threads. The function view includes a function called @samp{<JVM-System>}.
This represents the aggregated time from non-Java threads.
In case the JVM software does not report a Java call stack, time is reported
against the function @samp{<no Java callstack recorded>}.
@item expert
Show the Java call stacks for Java threads when the user Java code is executed,
and machine call stacks when JVM code is executed, or when the JVM software
does not report a Java call stack. Show the machine call stacks for
housekeeping threads.
@item machine
Show the actual native call stacks for all threads. This is the view mode
for C, C++, and Fortran.
@end table
@end table
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c SEEALSO section
@c ----------------------------------------------------------------------------
@ManPageStart{SEEALSO}
@c man begin SEEALSO
gprofng(1), gp-archive(1), gp-collect-app(1), gp-display-html(1), gp-display-src(1)
The user guide for gprofng is maintained as a Texinfo manual. If the
@command{info} and @command{gprofng} programs are correctly installed, the
command @command{info gprofng} should give access to this document.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c COPYRIGHT section
@c ----------------------------------------------------------------------------
@ManPageStart{COPYRIGHT}
@c man begin COPYRIGHT
Copyright @copyright{} 2022-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled ``GNU Free Documentation License''.
@c man end
@ManPageEnd{}
@c ----------------------------------------------------------------------------
@c If this text is used for a man page, exit. Otherwise we need to continue.
@c ----------------------------------------------------------------------------
@ifset man
@bye
@end ifset

72
gprofng/doc/gp-macros.texi Normal file
View File

@ -0,0 +1,72 @@
@c -- Macro definitions -------------------------------------------------------
@c
@c Since only letters can be used, we use capitalization to distinguish
@c different words.
@c ----------------------------------------------------------------------------
@macro CollectApp{}
@command{gprofng collect app}
@end macro
@macro DisplayHTML{}
@command{gprofng display html}
@end macro
@macro DisplayText{}
@command{gprofng display text}
@end macro
@macro DisplaySRC{}
@command{gprofng display src}
@end macro
@macro Archive{}
@command{gprofng archive}
@end macro
@macro Driver{}
@command{gprofng}
@end macro
@macro ProductName{}
gprofng
@end macro
@macro ToolName{}
@command{gprofng}
@end macro
@macro IndexSubentry{label, string}
@c -- @cindex \label\ @subentry \string\
@cindex \label\, \string\
@end macro
@macro vspace {lines}
@sp \lines\
@end macro
@c -- For some reason ending this macro with @noindent does not work out well.
@macro OptionHeader {lines, option, description}
@sp \lines\
@noindent
@code{\option\} @ @emph{\description\}
@c -- @sp 1
@end macro
@macro gcctabopt{body}
@code{\body\}
@end macro
@macro ManPageStart{headername}
@ifclear man
@sp 1
@noindent @b{\headername\}
@indentedblock
@end ifclear
@end macro
@macro ManPageEnd{}
@ifclear man
@end indentedblock
@end ifclear
@end macro

3796
gprofng/doc/gprofng.texi
View File

File diff suppressed because it is too large Load Diff

4396
gprofng/doc/gprofng_ug.texi Normal file
View File

File diff suppressed because it is too large Load Diff

6
gprofng/doc/version.texi
View File

@ -1,4 +1,4 @@
@set UPDATED 28 September 2022
@set UPDATED-MONTH September 2022
@set UPDATED 14 April 2022
@set UPDATED-MONTH April 2022
@set EDITION 2.40.50
@set VERSION 2.40.50
@set VERSION 2.0

32
gprofng/gp-display-html/Makefile.am
View File

@ -27,35 +27,3 @@ do_subst = sed -e 's/BINUTILS_VERSION/$(VERSION)/'
gp-display-html: gp-display-html.in Makefile
$(do_subst) < $(srcdir)/gp-display-html.in > $@
chmod +x $@
if BUILD_MAN
man_MANS = gp-display-html.1
MAINTAINERCLEANFILES = $(man_MANS)
# Use this if the man pages depend on the version number.
# common_mandeps = $(top_srcdir)/../bfd/version.m4
#
# Also change the dependence line below to this:
# gp-display-html.1: $(common_mandeps) gp-display-html
#
# Currently, the version number shown in the man page is derived from
# the output printed with --version.
# These variables are used by help2man to generate the man pages.
INFO_PAGE = "gprofng"
MANUAL = "User Commands"
TEXT_GP_DISPLAY_HTML = "generate an HTML based directory structure to browse the profiles"
HELP2MAN_OPT = --libtool --no-info --info-page=$(INFO_PAGE) --manual=$(MANUAL)
H2M_FILTER = | sed 's/\.TP/\.TP\n.B/' | sed 's/Commands:/\.SH COMMANDS/' \
| sed 's/See also:/\.SH SEE ALSO/' | sed 's/Documentation:/.SH DOCUMENTATION/' \
| sed 's/Limitations:/.SH LIMITATIONS/'
gp-display-html.1: gp-display-html
$(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
--name=$(TEXT_GP_DISPLAY_HTML) ./gp-display-html $(H2M_FILTER) > $@
endif

94
gprofng/gp-display-html/Makefile.in
View File

@ -150,7 +150,7 @@ am__uninstall_files_from_dir = { \
|| { echo " ( cd '$$dir' && rm -f" $$files ")"; \
$(am__cd) "$$dir" && rm -f $$files; }; \
}
am__installdirs = "$(DESTDIR)$(bindir)" "$(DESTDIR)$(man1dir)"
am__installdirs = "$(DESTDIR)$(bindir)"
SCRIPTS = $(bin_SCRIPTS)
AM_V_P = $(am__v_P_@AM_V@)
am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
@ -171,9 +171,6 @@ am__can_run_installinfo = \
n|no|NO) false;; \
*) (install-info --version) >/dev/null 2>&1;; \
esac
man1dir = $(mandir)/man1
NROFF = nroff
MANS = $(man_MANS)
am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
am__DIST_COMMON = $(srcdir)/Makefile.in $(top_srcdir)/../mkinstalldirs
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
@ -328,27 +325,6 @@ ACLOCAL_AMFLAGS = -I . -I .. -I ../..
bin_SCRIPTS = gp-display-html
CLEANFILES = $(bin_SCRIPTS)
do_subst = sed -e 's/BINUTILS_VERSION/$(VERSION)/'
@BUILD_MAN_TRUE@man_MANS = gp-display-html.1
@BUILD_MAN_TRUE@MAINTAINERCLEANFILES = $(man_MANS)
# Use this if the man pages depend on the version number.
# common_mandeps = $(top_srcdir)/../bfd/version.m4
#
# Also change the dependence line below to this:
# gp-display-html.1: $(common_mandeps) gp-display-html
#
# Currently, the version number shown in the man page is derived from
# the output printed with --version.
# These variables are used by help2man to generate the man pages.
@BUILD_MAN_TRUE@INFO_PAGE = "gprofng"
@BUILD_MAN_TRUE@MANUAL = "User Commands"
@BUILD_MAN_TRUE@TEXT_GP_DISPLAY_HTML = "generate an HTML based directory structure to browse the profiles"
@BUILD_MAN_TRUE@HELP2MAN_OPT = --libtool --no-info --info-page=$(INFO_PAGE) --manual=$(MANUAL)
@BUILD_MAN_TRUE@H2M_FILTER = | sed 's/\.TP/\.TP\n.B/' | sed 's/Commands:/\.SH COMMANDS/' \
@BUILD_MAN_TRUE@ | sed 's/See also:/\.SH SEE ALSO/' | sed 's/Documentation:/.SH DOCUMENTATION/' \
@BUILD_MAN_TRUE@ | sed 's/Limitations:/.SH LIMITATIONS/'
all: all-am
.SUFFIXES:
@ -422,49 +398,6 @@ mostlyclean-libtool:
clean-libtool:
-rm -rf .libs _libs
install-man1: $(man_MANS)
@$(NORMAL_INSTALL)
@list1=''; \
list2='$(man_MANS)'; \
test -n "$(man1dir)" \
&& test -n "`echo $$list1$$list2`" \
|| exit 0; \
echo " $(MKDIR_P) '$(DESTDIR)$(man1dir)'"; \
$(MKDIR_P) "$(DESTDIR)$(man1dir)" || exit 1; \
{ for i in $$list1; do echo "$$i"; done; \
if test -n "$$list2"; then \
for i in $$list2; do echo "$$i"; done \
| sed -n '/\.1[a-z]*$$/p'; \
fi; \
} | while read p; do \
if test -f $$p; then d=; else d="$(srcdir)/"; fi; \
echo "$$d$$p"; echo "$$p"; \
done | \
sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
-e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \
sed 'N;N;s,\n, ,g' | { \
list=; while read file base inst; do \
if test "$$base" = "$$inst"; then list="$$list $$file"; else \
echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \
$(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst" || exit $$?; \
fi; \
done; \
for i in $$list; do echo "$$i"; done | $(am__base_list) | \
while read files; do \
test -z "$$files" || { \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man1dir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(man1dir)" || exit $$?; }; \
done; }
uninstall-man1:
@$(NORMAL_UNINSTALL)
@list=''; test -n "$(man1dir)" || exit 0; \
files=`{ for i in $$list; do echo "$$i"; done; \
l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \
sed -n '/\.1[a-z]*$$/p'; \
} | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
-e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
dir='$(DESTDIR)$(man1dir)'; $(am__uninstall_files_from_dir)
tags TAGS:
ctags CTAGS:
@ -504,9 +437,9 @@ distdir: $(DISTFILES)
done
check-am: all-am
check: check-am
all-am: Makefile $(SCRIPTS) $(MANS)
all-am: Makefile $(SCRIPTS)
installdirs:
for dir in "$(DESTDIR)$(bindir)" "$(DESTDIR)$(man1dir)"; do \
for dir in "$(DESTDIR)$(bindir)"; do \
test -z "$$dir" || $(MKDIR_P) "$$dir"; \
done
install: install-am
@ -540,7 +473,6 @@ distclean-generic:
maintainer-clean-generic:
@echo "This command is intended for maintainers to use"
@echo "it deletes files that may require special tools to rebuild."
-test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES)
clean: clean-am
clean-am: clean-generic clean-libtool mostlyclean-am
@ -561,7 +493,7 @@ info: info-am
info-am:
install-data-am: install-man
install-data-am:
install-dvi: install-dvi-am
@ -577,7 +509,7 @@ install-info: install-info-am
install-info-am:
install-man: install-man1
install-man:
install-pdf: install-pdf-am
@ -605,9 +537,7 @@ ps: ps-am
ps-am:
uninstall-am: uninstall-binSCRIPTS uninstall-man
uninstall-man: uninstall-man1
uninstall-am: uninstall-binSCRIPTS
.MAKE: install-am install-strip
@ -617,12 +547,12 @@ uninstall-man: uninstall-man1
install install-am install-binSCRIPTS install-data \
install-data-am install-dvi install-dvi-am install-exec \
install-exec-am install-html install-html-am install-info \
install-info-am install-man install-man1 install-pdf \
install-pdf-am install-ps install-ps-am install-strip \
installcheck installcheck-am installdirs maintainer-clean \
install-info-am install-man install-pdf install-pdf-am \
install-ps install-ps-am install-strip installcheck \
installcheck-am installdirs maintainer-clean \
maintainer-clean-generic mostlyclean mostlyclean-generic \
mostlyclean-libtool pdf pdf-am ps ps-am tags-am uninstall \
uninstall-am uninstall-binSCRIPTS uninstall-man uninstall-man1
uninstall-am uninstall-binSCRIPTS
.PRECIOUS: Makefile
@ -631,10 +561,6 @@ gp-display-html: gp-display-html.in Makefile
$(do_subst) < $(srcdir)/gp-display-html.in > $@
chmod +x $@
@BUILD_MAN_TRUE@gp-display-html.1: gp-display-html
@BUILD_MAN_TRUE@ $(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
@BUILD_MAN_TRUE@ --name=$(TEXT_GP_DISPLAY_HTML) ./gp-display-html $(H2M_FILTER) > $@
# Tell versions [3.59,3.63) of GNU make to not export all variables.
# Otherwise a system limit (for SysV at least) may be exceeded.
.NOEXPORT:

56
gprofng/src/Makefile.am
View File

@ -121,7 +121,7 @@ QLParser.tab.cc QLParser.tab.hh: QLParser.yy
$(BISON) $^
BUILT_SOURCES = QLParser.tab.hh
EXTRA_DIST = QLParser.yy $(man_MANS)
EXTRA_DIST = QLParser.yy
lib_LTLIBRARIES = $(LIBGPROFNG)
@ -157,60 +157,6 @@ gp_display_src_LDADD = $(LIBGPROFNG) $(CLOCK_GETTIME_LINK) $(ZLIB)
gp_display_text_SOURCES = gp-display-text.cc ipc.cc ipcio.cc
gp_display_text_LDADD = $(LIBGPROFNG) $(CLOCK_GETTIME_LINK) $(ZLIB)
if BUILD_MAN
man_MANS = \
gp-archive.1 \
gp-collect-app.1 \
gp-display-src.1 \
gp-display-text.1
MAINTAINERCLEANFILES = $(man_MANS)
# The man pages depend on the version number and on a help2man include file.
common_mandeps = $(top_srcdir)/../bfd/version.m4
# Use -o so that the `missing' program can infer the output file.
# Embolden subcommand names in the output, and include a SEE ALSO.
# Arrange to regenerate the output if we have help2man, but leave the
# disted output there otherwise.
# Some extra annoying complexity is in place so that people without
# help2man dno't accidentally overwrite the manpage.
INFO_PAGE = "gprofng"
MANUAL = "User Commands"
TEXT_GPROFNG = "the driver for the gprofng tool suite"
TEXT_GP_ARCHIVE = "archive gprofng experiment data"
TEXT_GP_COLLECT_APP = "collect performance data for the target application"
TEXT_GP_DISPLAY_SRC = "display the source code, optionally interleaved with the disassembly of the target object"
TEXT_GP_DISPLAY_TEXT = "display the performance data in plain text format"
HELP2MAN_OPT = --libtool --no-info --info-page=$(INFO_PAGE) --manual=$(MANUAL)
H2M_FILTER = | sed 's/\.TP/\.TP\n.B/' | sed 's/Commands:/\.SH COMMANDS/' \
| sed 's/See also:/\.SH SEE ALSO/' | sed 's/Documentation:/.SH DOCUMENTATION/' \
| sed 's/Limitations:/.SH LIMITATIONS/'
gp-archive.1: $(srcdir)/gp-archive.cc $(common_mandeps) | ./gp-archive$(EXEEXT)
$(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
--name=$(TEXT_GP_ARCHIVE) ./gp-archive$(EXEEXT) $(H2M_FILTER) > $@
gp-collect-app.1: $(srcdir)/gp-collect-app.cc $(common_mandeps) | ./gp-collect-app$(EXEEXT)
$(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
--name=$(TEXT_GP_COLLECT_APP) ./gp-collect-app$(EXEEXT) $(H2M_FILTER) > $@
gp-display-src.1: $(srcdir)/gp-display-src.cc $(srcdir)/Command.cc \
$(common_mandeps) | ./gp-display-src$(EXEEXT)
$(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
--name=$(TEXT_GP_DISPLAY_SRC) ./gp-display-src$(EXEEXT) $(H2M_FILTER) > $@
gp-display-text.1: $(srcdir)/gp-display-text.cc $(srcdir)/Command.cc \
$(common_mandeps) | ./gp-display-text$(EXEEXT)
$(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
--name=$(TEXT_GP_DISPLAY_TEXT) ./gp-display-text$(EXEEXT) $(H2M_FILTER) > $@
endif
# Distribution involves building the binaries to generate the manpage,
# so ensure that the necessary libraries are built at dist time.
dist-hook: $(LIBGPROFNG)

114
gprofng/src/Makefile.in
View File

@ -156,7 +156,7 @@ am__uninstall_files_from_dir = { \
$(am__cd) "$$dir" && rm -f $$files; }; \
}
am__installdirs = "$(DESTDIR)$(libdir)" "$(DESTDIR)$(bindir)" \
"$(DESTDIR)$(man1dir)" "$(DESTDIR)$(dbedir)"
"$(DESTDIR)$(dbedir)"
LTLIBRARIES = $(lib_LTLIBRARIES)
am__DEPENDENCIES_1 =
libgprofng_la_DEPENDENCIES = $(top_builddir)/../opcodes/libopcodes.la \
@ -275,9 +275,6 @@ am__can_run_installinfo = \
n|no|NO) false;; \
*) (install-info --version) >/dev/null 2>&1;; \
esac
man1dir = $(mandir)/man1
NROFF = nroff
MANS = $(man_MANS)
DATA = $(dbe_DATA)
am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
# Read a list of newline-separated strings from the standard input,
@ -547,7 +544,7 @@ AM_CFLAGS = $(GPROFNG_CFLAGS) $(PTHREAD_CFLAGS) \
AM_CXXFLAGS = $(AM_CFLAGS)
BUILT_SOURCES = QLParser.tab.hh
EXTRA_DIST = QLParser.yy $(man_MANS)
EXTRA_DIST = QLParser.yy
lib_LTLIBRARIES = $(LIBGPROFNG)
libgprofng_la_SOURCES = $(CCSOURCES) $(CSOURCES)
libgprofng_la_LDFLAGS = -version-info 0:0:0
@ -572,35 +569,6 @@ gp_display_src_SOURCES = gp-display-src.cc
gp_display_src_LDADD = $(LIBGPROFNG) $(CLOCK_GETTIME_LINK) $(ZLIB)
gp_display_text_SOURCES = gp-display-text.cc ipc.cc ipcio.cc
gp_display_text_LDADD = $(LIBGPROFNG) $(CLOCK_GETTIME_LINK) $(ZLIB)
@BUILD_MAN_TRUE@man_MANS = \
@BUILD_MAN_TRUE@ gp-archive.1 \
@BUILD_MAN_TRUE@ gp-collect-app.1 \
@BUILD_MAN_TRUE@ gp-display-src.1 \
@BUILD_MAN_TRUE@ gp-display-text.1
@BUILD_MAN_TRUE@MAINTAINERCLEANFILES = $(man_MANS)
# The man pages depend on the version number and on a help2man include file.
@BUILD_MAN_TRUE@common_mandeps = $(top_srcdir)/../bfd/version.m4
# Use -o so that the `missing' program can infer the output file.
# Embolden subcommand names in the output, and include a SEE ALSO.
# Arrange to regenerate the output if we have help2man, but leave the
# disted output there otherwise.
# Some extra annoying complexity is in place so that people without
# help2man dno't accidentally overwrite the manpage.
@BUILD_MAN_TRUE@INFO_PAGE = "gprofng"
@BUILD_MAN_TRUE@MANUAL = "User Commands"
@BUILD_MAN_TRUE@TEXT_GPROFNG = "the driver for the gprofng tool suite"
@BUILD_MAN_TRUE@TEXT_GP_ARCHIVE = "archive gprofng experiment data"
@BUILD_MAN_TRUE@TEXT_GP_COLLECT_APP = "collect performance data for the target application"
@BUILD_MAN_TRUE@TEXT_GP_DISPLAY_SRC = "display the source code, optionally interleaved with the disassembly of the target object"
@BUILD_MAN_TRUE@TEXT_GP_DISPLAY_TEXT = "display the performance data in plain text format"
@BUILD_MAN_TRUE@HELP2MAN_OPT = --libtool --no-info --info-page=$(INFO_PAGE) --manual=$(MANUAL)
@BUILD_MAN_TRUE@H2M_FILTER = | sed 's/\.TP/\.TP\n.B/' | sed 's/Commands:/\.SH COMMANDS/' \
@BUILD_MAN_TRUE@ | sed 's/See also:/\.SH SEE ALSO/' | sed 's/Documentation:/.SH DOCUMENTATION/' \
@BUILD_MAN_TRUE@ | sed 's/Limitations:/.SH LIMITATIONS/'
all: $(BUILT_SOURCES)
$(MAKE) $(AM_MAKEFLAGS) all-am
@ -885,49 +853,6 @@ mostlyclean-libtool:
clean-libtool:
-rm -rf .libs _libs
install-man1: $(man_MANS)
@$(NORMAL_INSTALL)
@list1=''; \
list2='$(man_MANS)'; \
test -n "$(man1dir)" \
&& test -n "`echo $$list1$$list2`" \
|| exit 0; \
echo " $(MKDIR_P) '$(DESTDIR)$(man1dir)'"; \
$(MKDIR_P) "$(DESTDIR)$(man1dir)" || exit 1; \
{ for i in $$list1; do echo "$$i"; done; \
if test -n "$$list2"; then \
for i in $$list2; do echo "$$i"; done \
| sed -n '/\.1[a-z]*$$/p'; \
fi; \
} | while read p; do \
if test -f $$p; then d=; else d="$(srcdir)/"; fi; \
echo "$$d$$p"; echo "$$p"; \
done | \
sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
-e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \
sed 'N;N;s,\n, ,g' | { \
list=; while read file base inst; do \
if test "$$base" = "$$inst"; then list="$$list $$file"; else \
echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \
$(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst" || exit $$?; \
fi; \
done; \
for i in $$list; do echo "$$i"; done | $(am__base_list) | \
while read files; do \
test -z "$$files" || { \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man1dir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(man1dir)" || exit $$?; }; \
done; }
uninstall-man1:
@$(NORMAL_UNINSTALL)
@list=''; test -n "$(man1dir)" || exit 0; \
files=`{ for i in $$list; do echo "$$i"; done; \
l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \
sed -n '/\.1[a-z]*$$/p'; \
} | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
-e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
dir='$(DESTDIR)$(man1dir)'; $(am__uninstall_files_from_dir)
install-dbeDATA: $(dbe_DATA)
@$(NORMAL_INSTALL)
@list='$(dbe_DATA)'; test -n "$(dbedir)" || list=; \
@ -1038,11 +963,11 @@ distdir: $(DISTFILES)
check-am: all-am
check: $(BUILT_SOURCES)
$(MAKE) $(AM_MAKEFLAGS) check-am
all-am: Makefile $(LTLIBRARIES) $(PROGRAMS) $(MANS) $(DATA)
all-am: Makefile $(LTLIBRARIES) $(PROGRAMS) $(DATA)
install-binPROGRAMS: install-libLTLIBRARIES
installdirs:
for dir in "$(DESTDIR)$(libdir)" "$(DESTDIR)$(bindir)" "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(dbedir)"; do \
for dir in "$(DESTDIR)$(libdir)" "$(DESTDIR)$(bindir)" "$(DESTDIR)$(dbedir)"; do \
test -z "$$dir" || $(MKDIR_P) "$$dir"; \
done
install: $(BUILT_SOURCES)
@ -1077,7 +1002,6 @@ maintainer-clean-generic:
@echo "This command is intended for maintainers to use"
@echo "it deletes files that may require special tools to rebuild."
-test -z "$(BUILT_SOURCES)" || rm -f $(BUILT_SOURCES)
-test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES)
clean: clean-am
clean-am: clean-binPROGRAMS clean-generic clean-libLTLIBRARIES \
@ -1101,7 +1025,7 @@ info: info-am
info-am:
install-data-am: install-dbeDATA install-man
install-data-am: install-dbeDATA
install-dvi: install-dvi-am
@ -1117,7 +1041,7 @@ install-info: install-info-am
install-info-am:
install-man: install-man1
install-man:
install-pdf: install-pdf-am
@ -1148,9 +1072,7 @@ ps: ps-am
ps-am:
uninstall-am: uninstall-binPROGRAMS uninstall-dbeDATA \
uninstall-libLTLIBRARIES uninstall-man
uninstall-man: uninstall-man1
uninstall-libLTLIBRARIES
.MAKE: all check install install-am install-strip
@ -1163,13 +1085,13 @@ uninstall-man: uninstall-man1
install-data-am install-dbeDATA install-dvi install-dvi-am \
install-exec install-exec-am install-html install-html-am \
install-info install-info-am install-libLTLIBRARIES \
install-man install-man1 install-pdf install-pdf-am install-ps \
install-man install-pdf install-pdf-am install-ps \
install-ps-am install-strip installcheck installcheck-am \
installdirs maintainer-clean maintainer-clean-generic \
mostlyclean mostlyclean-compile mostlyclean-generic \
mostlyclean-libtool pdf pdf-am ps ps-am tags tags-am uninstall \
uninstall-am uninstall-binPROGRAMS uninstall-dbeDATA \
uninstall-libLTLIBRARIES uninstall-man uninstall-man1
uninstall-libLTLIBRARIES
.PRECIOUS: Makefile
@ -1177,24 +1099,6 @@ uninstall-man: uninstall-man1
QLParser.tab.cc QLParser.tab.hh: QLParser.yy
$(BISON) $^
@BUILD_MAN_TRUE@gp-archive.1: $(srcdir)/gp-archive.cc $(common_mandeps) | ./gp-archive$(EXEEXT)
@BUILD_MAN_TRUE@ $(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
@BUILD_MAN_TRUE@ --name=$(TEXT_GP_ARCHIVE) ./gp-archive$(EXEEXT) $(H2M_FILTER) > $@
@BUILD_MAN_TRUE@gp-collect-app.1: $(srcdir)/gp-collect-app.cc $(common_mandeps) | ./gp-collect-app$(EXEEXT)
@BUILD_MAN_TRUE@ $(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
@BUILD_MAN_TRUE@ --name=$(TEXT_GP_COLLECT_APP) ./gp-collect-app$(EXEEXT) $(H2M_FILTER) > $@
@BUILD_MAN_TRUE@gp-display-src.1: $(srcdir)/gp-display-src.cc $(srcdir)/Command.cc \
@BUILD_MAN_TRUE@ $(common_mandeps) | ./gp-display-src$(EXEEXT)
@BUILD_MAN_TRUE@ $(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
@BUILD_MAN_TRUE@ --name=$(TEXT_GP_DISPLAY_SRC) ./gp-display-src$(EXEEXT) $(H2M_FILTER) > $@
@BUILD_MAN_TRUE@gp-display-text.1: $(srcdir)/gp-display-text.cc $(srcdir)/Command.cc \
@BUILD_MAN_TRUE@ $(common_mandeps) | ./gp-display-text$(EXEEXT)
@BUILD_MAN_TRUE@ $(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
@BUILD_MAN_TRUE@ --name=$(TEXT_GP_DISPLAY_TEXT) ./gp-display-text$(EXEEXT) $(H2M_FILTER) > $@
# Distribution involves building the binaries to generate the manpage,
# so ensure that the necessary libraries are built at dist time.
dist-hook: $(LIBGPROFNG)