From 7a515757db9681e86926b7068b3a4a6a2df70299 Mon Sep 17 00:00:00 2001 From: Vladimir Mezentsev Date: Sat, 15 Apr 2023 17:54:15 -0700 Subject: [PATCH] gprofng: Update documentation 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 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. --- gprofng/doc/Makefile.am | 26 +- gprofng/doc/Makefile.in | 59 +- gprofng/doc/gp-archive.texi | 246 ++ gprofng/doc/gp-collect-app.texi | 380 +++ gprofng/doc/gp-display-html.texi | 252 ++ gprofng/doc/gp-display-src.texi | 246 ++ gprofng/doc/gp-display-text.texi | 437 +++ gprofng/doc/gp-macros.texi | 72 + gprofng/doc/gprofng.texi | 3644 ++-------------------- gprofng/doc/gprofng_ug.texi | 4396 +++++++++++++++++++++++++++ gprofng/doc/version.texi | 6 +- gprofng/gp-display-html/Makefile.am | 32 - gprofng/gp-display-html/Makefile.in | 94 +- gprofng/src/Makefile.am | 56 +- gprofng/src/Makefile.in | 114 +- 15 files changed, 6295 insertions(+), 3765 deletions(-) create mode 100644 gprofng/doc/gp-archive.texi create mode 100644 gprofng/doc/gp-collect-app.texi create mode 100644 gprofng/doc/gp-display-html.texi create mode 100644 gprofng/doc/gp-display-src.texi create mode 100644 gprofng/doc/gp-display-text.texi create mode 100644 gprofng/doc/gp-macros.texi create mode 100644 gprofng/doc/gprofng_ug.texi diff --git a/gprofng/doc/Makefile.am b/gprofng/doc/Makefile.am index 8be0e92fa0b..ad72c268e99 100644 --- a/gprofng/doc/Makefile.am +++ b/gprofng/doc/Makefile.am @@ -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) diff --git a/gprofng/doc/Makefile.in b/gprofng/doc/Makefile.in index 3cd2068cbf6..78f8ae11fc7 100644 --- a/gprofng/doc/Makefile.in +++ b/gprofng/doc/Makefile.in @@ -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) diff --git a/gprofng/doc/gp-archive.texi b/gprofng/doc/gp-archive.texi new file mode 100644 index 00000000000..722a9546081 --- /dev/null +++ b/gprofng/doc/gp-archive.texi @@ -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 diff --git a/gprofng/doc/gp-collect-app.texi b/gprofng/doc/gp-collect-app.texi new file mode 100644 index 00000000000..7e81f8505e7 --- /dev/null +++ b/gprofng/doc/gp-collect-app.texi @@ -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{}@} +@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{@{...,@}} +@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{} +@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{} +@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{} +@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{}@} +@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{} 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{} +Records profiling data for the JVM, and use the JVM as installed in @var{}. + +@end table + +@item -J @var{} +@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{}[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{}@} +@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{} +option to change this. The default is @samp{-S on}. + +@item -y @var{}[,r] +@ifclear man +@IndexSubentry{Options, @code{-y}} +@end ifclear + +Controls recording of data with the signal named @var{}, 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{} +@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{} 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{