| From c6e269febbc946a54ed9dbbb2dc70feba6017607 Mon Sep 17 00:00:00 2001 |
| From: Vladimir Mezentsev <vladimir.mezentsev@oracle.com> |
| Date: Fri, 20 Jan 2023 15:39:55 -0800 |
| Subject: [PATCH 18/50] gprofng: PR29521 [docs] man pages are not in the |
| release tarball |
| |
| gprofng/ChangeLog |
| 2023-01-20 Vladimir Mezentsev <vladimir.mezentsev@oracle.com> |
| |
| PR gprofng/29521 |
| * configure.ac: Check if $MAKEINFO and $HELP2MAN are missing. |
| * Makefile.am: Build doc if $MAKEINFO exists. |
| * doc/gprofng.texi: Update documentation for gprofng. |
| * doc/Makefile.am: Build gprofng.1. |
| * src/Makefile.am: Move the build of gprofng.1 to doc/Makefile.am. |
| * configure: Rebuild. |
| * Makefile.in: Rebuild. |
| * doc/Makefile.in: Rebuild. |
| * src/Makefile.in: Rebuild. |
| --- |
| gprofng/Makefile.am | 2 +- |
| gprofng/Makefile.in | 2 +- |
| gprofng/configure | 79 +++++++++++++++--- |
| gprofng/configure.ac | 21 +++-- |
| gprofng/doc/Makefile.am | 24 +++++- |
| gprofng/doc/Makefile.in | 93 ++++++++++++++++++--- |
| gprofng/doc/gprofng.texi | 169 +++++++++++++++++++++++++++++++++++++++ |
| gprofng/src/Makefile.am | 8 +- |
| gprofng/src/Makefile.in | 8 +- |
| 9 files changed, 364 insertions(+), 42 deletions(-) |
| |
| --- a/gprofng/Makefile.am |
| +++ b/gprofng/Makefile.am |
| @@ -23,7 +23,7 @@ AUTOMAKE_OPTIONS = dejagnu foreign |
| if BUILD_COLLECTOR |
| COLLECTOR_SUBDIRS = libcollector |
| endif |
| -if BUILD_MAN |
| +if BUILD_DOC |
| DOC_SUBDIR = doc |
| endif |
| if BUILD_SRC |
| --- a/gprofng/Makefile.in |
| +++ b/gprofng/Makefile.in |
| @@ -381,7 +381,7 @@ zlibinc = @zlibinc@ |
| ACLOCAL_AMFLAGS = -I . -I .. |
| AUTOMAKE_OPTIONS = dejagnu foreign |
| @BUILD_COLLECTOR_TRUE@COLLECTOR_SUBDIRS = libcollector |
| -@BUILD_MAN_TRUE@DOC_SUBDIR = doc |
| +@BUILD_DOC_TRUE@DOC_SUBDIR = doc |
| @BUILD_SRC_TRUE@SRC_SUBDIRS = src gp-display-html $(DOC_SUBDIR) |
| SUBDIRS = $(COLLECTOR_SUBDIRS) $(SRC_SUBDIRS) |
| DIST_SUBDIRS = libcollector src gp-display-html $(DOC_SUBDIR) |
| --- a/gprofng/configure |
| +++ b/gprofng/configure |
| @@ -639,6 +639,8 @@ GPROFNG_CPPFLAGS |
| GPROFNG_NO_FORMAT_TRUNCATION_CFLAGS |
| GPROFNG_CFLAGS |
| LD_NO_AS_NEEDED |
| +BUILD_DOC_FALSE |
| +BUILD_DOC_TRUE |
| BUILD_MAN_FALSE |
| BUILD_MAN_TRUE |
| HELP2MAN |
| @@ -12221,7 +12223,7 @@ else |
| lt_dlunknown=0; lt_dlno_uscore=1; lt_dlneed_uscore=2 |
| lt_status=$lt_dlunknown |
| cat > conftest.$ac_ext <<_LT_EOF |
| -#line 12224 "configure" |
| +#line 12226 "configure" |
| #include "confdefs.h" |
| |
| #if HAVE_DLFCN_H |
| @@ -12327,7 +12329,7 @@ else |
| lt_dlunknown=0; lt_dlno_uscore=1; lt_dlneed_uscore=2 |
| lt_status=$lt_dlunknown |
| cat > conftest.$ac_ext <<_LT_EOF |
| -#line 12330 "configure" |
| +#line 12332 "configure" |
| #include "confdefs.h" |
| |
| #if HAVE_DLFCN_H |
| @@ -16737,9 +16739,58 @@ fi |
| |
| # Generate manpages, if possible. |
| build_man=false |
| +build_doc=false |
| if test $cross_compiling = no; then |
| + for ac_prog in help2man |
| +do |
| + # Extract the first word of "$ac_prog", so it can be a program name with args. |
| +set dummy $ac_prog; ac_word=$2 |
| +{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 |
| +$as_echo_n "checking for $ac_word... " >&6; } |
| +if ${ac_cv_prog_HELP2MAN+:} false; then : |
| + $as_echo_n "(cached) " >&6 |
| +else |
| + if test -n "$HELP2MAN"; then |
| + ac_cv_prog_HELP2MAN="$HELP2MAN" # Let the user override the test. |
| +else |
| +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR |
| +for as_dir in $PATH |
| +do |
| + IFS=$as_save_IFS |
| + test -z "$as_dir" && as_dir=. |
| + for ac_exec_ext in '' $ac_executable_extensions; do |
| + if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then |
| + ac_cv_prog_HELP2MAN="$ac_prog" |
| + $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5 |
| + break 2 |
| + fi |
| +done |
| + done |
| +IFS=$as_save_IFS |
| + |
| +fi |
| +fi |
| +HELP2MAN=$ac_cv_prog_HELP2MAN |
| +if test -n "$HELP2MAN"; then |
| + { $as_echo "$as_me:${as_lineno-$LINENO}: result: $HELP2MAN" >&5 |
| +$as_echo "$HELP2MAN" >&6; } |
| +else |
| + { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 |
| +$as_echo "no" >&6; } |
| +fi |
| |
| -HELP2MAN=${HELP2MAN-"${am_missing_run}help2man"} |
| + |
| + test -n "$HELP2MAN" && break |
| +done |
| +test -n "$HELP2MAN" || HELP2MAN="$MISSING help2man" |
| + |
| + case "x$HELP2MAN" in |
| + x | */missing\ help2man* ) |
| + { $as_echo "$as_me:${as_lineno-$LINENO}: WARNING: gprofng: help2man is missing. Man pages will not be built." >&5 |
| +$as_echo "$as_me: WARNING: gprofng: help2man is missing. Man pages will not be built." >&2;} |
| + ;; |
| + * ) build_man=true ;; |
| + esac |
| |
| for ac_prog in makeinfo |
| do |
| @@ -16782,10 +16833,10 @@ fi |
| |
| test -n "$MAKEINFO" && break |
| done |
| -test -n "$MAKEINFO" || MAKEINFO=""@echo makeinfo missing; true"" |
| +test -n "$MAKEINFO" || MAKEINFO="$MISSING makeinfo" |
| |
| - case "$MAKEINFO" in |
| - *true) |
| + case "x$MAKEINFO" in |
| + x | */missing\ makeinfo*) |
| { $as_echo "$as_me:${as_lineno-$LINENO}: WARNING: gprofng: makeinfo is missing. Info documentation will not be built." >&5 |
| $as_echo "$as_me: WARNING: gprofng: makeinfo is missing. Info documentation will not be built." >&2;} |
| ;; |
| @@ -16796,9 +16847,7 @@ $as_echo "$as_me: WARNING: gprofng: make |
| $as_echo "$as_me: WARNING: gprofng: $MAKEINFO is too old. Info documentation will not be built." >&2;} |
| MAKEINFO="@echo $MAKEINFO is too old, 6.5 or newer required; true" |
| ;; |
| - x* ) |
| - build_man=true |
| - ;; |
| + x* ) build_doc=true ;; |
| esac |
| ;; |
| esac |
| @@ -16812,6 +16861,14 @@ else |
| BUILD_MAN_FALSE= |
| fi |
| |
| + if test x$build_doc = xtrue; then |
| + BUILD_DOC_TRUE= |
| + BUILD_DOC_FALSE='#' |
| +else |
| + BUILD_DOC_TRUE='#' |
| + BUILD_DOC_FALSE= |
| +fi |
| + |
| |
| LD_NO_AS_NEEDED=${no_as_needed} |
| |
| @@ -17070,6 +17127,10 @@ if test -z "${BUILD_MAN_TRUE}" && test - |
| as_fn_error $? "conditional \"BUILD_MAN\" was never defined. |
| Usually this means the macro was only invoked conditionally." "$LINENO" 5 |
| fi |
| +if test -z "${BUILD_DOC_TRUE}" && test -z "${BUILD_DOC_FALSE}"; then |
| + as_fn_error $? "conditional \"BUILD_DOC\" was never defined. |
| +Usually this means the macro was only invoked conditionally." "$LINENO" 5 |
| +fi |
| |
| : "${CONFIG_STATUS=./config.status}" |
| ac_write_fail=0 |
| --- a/gprofng/configure.ac |
| +++ b/gprofng/configure.ac |
| @@ -210,11 +210,19 @@ AM_ZLIB |
| |
| # Generate manpages, if possible. |
| build_man=false |
| +build_doc=false |
| if test $cross_compiling = no; then |
| - AM_MISSING_PROG(HELP2MAN, help2man) |
| - AC_CHECK_PROGS([MAKEINFO], makeinfo, ["@echo makeinfo missing; true"]) |
| - case "$MAKEINFO" in |
| - *true) |
| + AC_CHECK_PROGS([HELP2MAN], help2man, [$MISSING help2man]) |
| + case "x$HELP2MAN" in |
| + x | */missing\ help2man* ) |
| + AC_MSG_WARN([gprofng: help2man is missing. Man pages will not be built.]) |
| + ;; |
| + * ) build_man=true ;; |
| + esac |
| + |
| + AC_CHECK_PROGS([MAKEINFO], makeinfo, [$MISSING makeinfo]) |
| + case "x$MAKEINFO" in |
| + x | */missing\ makeinfo*) |
| AC_MSG_WARN([gprofng: makeinfo is missing. Info documentation will not be built.]) |
| ;; |
| *) |
| @@ -223,15 +231,14 @@ if test $cross_compiling = no; then |
| AC_MSG_WARN([gprofng: $MAKEINFO is too old. Info documentation will not be built.]) |
| MAKEINFO="@echo $MAKEINFO is too old, 6.5 or newer required; true" |
| ;; |
| - x* ) |
| - build_man=true |
| - ;; |
| + x* ) build_doc=true ;; |
| esac |
| ;; |
| esac |
| AC_SUBST(MAKEINFO) |
| fi |
| AM_CONDITIONAL([BUILD_MAN], [test x$build_man = xtrue]) |
| +AM_CONDITIONAL([BUILD_DOC], [test x$build_doc = xtrue]) |
| |
| AC_SUBST(LD_NO_AS_NEEDED, [${no_as_needed}]) |
| AC_SUBST(GPROFNG_CFLAGS, [${gprofng_cflags}]) |
| --- a/gprofng/doc/Makefile.am |
| +++ b/gprofng/doc/Makefile.am |
| @@ -19,9 +19,31 @@ |
| |
| AUTOMAKE_OPTIONS = info-in-builddir foreign no-texinfo.tex |
| |
| +# Options to extract the man page |
| +MANCONF = -Dman |
| + |
| +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 |
| TEXINFO_TEX = . |
| MAKEINFOHTML = $(MAKEINFO) --html --no-split |
| |
| -MAINTAINERCLEANFILES = gprofng.info |
| +man_MANS = gprofng.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 |
| + $(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 && \ |
| + mv -f $@.tmp $@) || (rm -f $@.tmp && exit 1) |
| + $(AM_V_at)rm -f gprofng.pod |
| + |
| +MAINTAINERCLEANFILES = gprofng.info $(man_MANS) |
| + |
| +info: $(man_MANS) |
| --- a/gprofng/doc/Makefile.in |
| +++ b/gprofng/doc/Makefile.in |
| @@ -182,7 +182,7 @@ am__can_run_installinfo = \ |
| n|no|NO) false;; \ |
| *) (install-info --version) >/dev/null 2>&1;; \ |
| esac |
| -am__installdirs = "$(DESTDIR)$(infodir)" |
| +am__installdirs = "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)" |
| am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; |
| am__vpath_adj = case $$p in \ |
| $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ |
| @@ -210,6 +210,9 @@ am__uninstall_files_from_dir = { \ |
| || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ |
| $(am__cd) "$$dir" && rm -f $$files; }; \ |
| } |
| +man1dir = $(mandir)/man1 |
| +NROFF = nroff |
| +MANS = $(man_MANS) |
| am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) |
| am__DIST_COMMON = $(gprofng_TEXINFOS) $(srcdir)/Makefile.in \ |
| $(top_srcdir)/../mkinstalldirs mdate-sh texinfo.tex |
| @@ -361,11 +364,19 @@ top_srcdir = @top_srcdir@ |
| zlibdir = @zlibdir@ |
| zlibinc = @zlibinc@ |
| AUTOMAKE_OPTIONS = info-in-builddir foreign no-texinfo.tex |
| + |
| +# Options to extract the man page |
| +MANCONF = -Dman |
| +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 |
| TEXINFO_TEX = . |
| MAKEINFOHTML = $(MAKEINFO) --html --no-split |
| -MAINTAINERCLEANFILES = gprofng.info |
| +man_MANS = gprofng.1 |
| +MAINTAINERCLEANFILES = gprofng.info $(man_MANS) |
| all: all-am |
| |
| .SUFFIXES: |
| @@ -558,6 +569,49 @@ maintainer-clean-aminfo: |
| echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ |
| rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ |
| done |
| +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: |
| @@ -600,9 +654,9 @@ distdir: $(DISTFILES) |
| dist-info |
| check-am: all-am |
| check: check-am |
| -all-am: Makefile $(INFO_DEPS) |
| +all-am: Makefile $(INFO_DEPS) $(MANS) |
| installdirs: |
| - for dir in "$(DESTDIR)$(infodir)"; do \ |
| + for dir in "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"; do \ |
| test -z "$$dir" || $(MKDIR_P) "$$dir"; \ |
| done |
| install: install-am |
| @@ -652,11 +706,9 @@ html: html-am |
| |
| html-am: $(HTMLS) |
| |
| -info: info-am |
| - |
| info-am: $(INFO_DEPS) |
| |
| -install-data-am: install-info-am |
| +install-data-am: install-info-am install-man |
| |
| install-dvi: install-dvi-am |
| |
| @@ -739,7 +791,7 @@ install-info-am: $(INFO_DEPS) |
| install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ |
| done; \ |
| else : ; fi |
| -install-man: |
| +install-man: install-man1 |
| |
| install-pdf: install-pdf-am |
| |
| @@ -794,7 +846,9 @@ ps: ps-am |
| ps-am: $(PSS) |
| |
| uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ |
| - uninstall-pdf-am uninstall-ps-am |
| + uninstall-man uninstall-pdf-am uninstall-ps-am |
| + |
| +uninstall-man: uninstall-man1 |
| |
| .MAKE: install-am install-strip |
| |
| @@ -804,19 +858,32 @@ uninstall-am: uninstall-dvi-am uninstall |
| html-am info info-am install install-am 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-pdf install-pdf-am \ |
| - install-ps install-ps-am install-strip installcheck \ |
| - installcheck-am installdirs maintainer-clean \ |
| + 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 \ |
| maintainer-clean-aminfo maintainer-clean-generic \ |
| maintainer-clean-vti mostlyclean mostlyclean-aminfo \ |
| mostlyclean-generic mostlyclean-libtool mostlyclean-vti pdf \ |
| pdf-am ps ps-am tags-am uninstall uninstall-am \ |
| uninstall-dvi-am uninstall-html-am uninstall-info-am \ |
| - uninstall-pdf-am uninstall-ps-am |
| + uninstall-man uninstall-man1 uninstall-pdf-am uninstall-ps-am |
| |
| .PRECIOUS: Makefile |
| |
| |
| +# 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 |
| + $(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 && \ |
| + mv -f $@.tmp $@) || (rm -f $@.tmp && exit 1) |
| + $(AM_V_at)rm -f gprofng.pod |
| + |
| +info: $(man_MANS) |
| + |
| # 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: |
| --- a/gprofng/doc/gprofng.texi |
| +++ b/gprofng/doc/gprofng.texi |
| @@ -1,5 +1,8 @@ |
| \input texinfo @c -*-texinfo-*- |
| |
| +@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES |
| +@c BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) { |
| + |
| @c ---------------------------------------------------------------------------- |
| @c This is the Texinfo source file for the GPROFNG manual. |
| @c |
| @@ -59,6 +62,10 @@ gprofng |
| @cindex \label\, \string\ |
| @end macro |
| |
| +@macro gcctabopt{body} |
| +@code{\body\} |
| +@end macro |
| + |
| @c -- Get the version information --------------------------------------------- |
| @include version.texi |
| |
| @@ -99,6 +106,20 @@ section entitled ``GNU Free Documentatio |
| @page |
| @vskip 0pt plus 1filll |
| @insertcopying |
| + |
| +@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 |
| + |
| @end titlepage |
| |
| @c -- Generate the Table of Contents ------------------------------------------ |
| @@ -163,6 +184,154 @@ Terminology |
| @end menu |
| @end ifinfo |
| |
| +@ifset man |
| + |
| +@c man title gprofng the driver for the gprofng tool suite |
| + |
| +@c man begin SYNOPSIS |
| +gprofng [OPTION(S)] ACTION [@b{QUALIFIER}] [ARGUMENTS] TARGET |
| +@c man end |
| + |
| +@c man begin DESCRIPTION |
| +This is the driver for the GPROFNG tools suite to gather and analyze performance data. |
| + |
| +The driver executes the action specified. An example of an action is @code{collect} |
| +to collect performance data. Depending on the action, a qualifier may be needed to |
| +define the command. Several qualifiers support options. The last item on the command |
| +is the target the command applies to. |
| + |
| +For example, to collect performance data for an application called @code{a.out} and |
| +store the results in experiment directory @code{mydata.er}, the following command may |
| +be used: |
| + |
| +@smallexample |
| +$ gprofng collect app -o mydata.er a.out |
| +@end smallexample |
| + |
| +In this example, the action is @code{collect}, the qualifier is @code{app}, the single |
| +argument is @code{-o mydata.er} and the target is @code{a.out}. |
| + |
| +If gprofng is executed without any additional option, action, or target, a usage |
| +overview is printed. |
| + |
| +@c man end |
| + |
| +@c man begin OPTIONS |
| + |
| +@table @gcctabopt |
| + |
| +@item @var{--version} |
| +print the version number and exit. |
| + |
| +@item @var{--help} |
| +print usage information and exit. |
| + |
| +@end table |
| + |
| +@c man end |
| + |
| +@c man begin NOTES |
| + |
| +The gprofng driver supports the following commands. |
| + |
| +@c The man pages for the commands below can be viewed using the command name with "gprofng" replaced by "gp" and the spaces replaced by a dash ("-"). For example the man page |
| +@c name for "gprofng collect app" is "gp-collect-app". |
| + |
| +Collect performance data: |
| + |
| +@table @code |
| + |
| +@item gprofng collect app |
| +collect application performance data. |
| + |
| +@end table |
| + |
| +Display the performance results: |
| + |
| +@table @code |
| + |
| +@item gprofng display text |
| +display the performance data in ASCII format. |
| + |
| +@item gprofng display html |
| +generate an HTML file from one or more experiments. |
| + |
| +@end table |
| + |
| +Miscellaneous commands: |
| + |
| +@table @code |
| + |
| +@item gprofng display src |
| +display source or disassembly with compiler annotations. |
| + |
| +@item gprofng archive |
| +include binaries and source code in an experiment directory. |
| + |
| +@end table |
| + |
| +It is also possible to invoke the lower level commands directly, but since |
| +these are subject to change, in particular the options, we recommend to |
| +use the driver. |
| + |
| +@c man end |
| + |
| +@c man begin ENVIRONMENT |
| +The following environment variables are supported: |
| + |
| +@table @code |
| + |
| +@item @env{GPROFNG_MAX_CALL_STACK_DEPTH} |
| +set the depth of the call stack (default is 256). |
| + |
| +@item @env{GPROFNG_USE_JAVA_OPTIONS} |
| +may be set when profiling a C/C++ application that uses dlopen() to execute Java code. |
| + |
| +@item @env{GPROFNG_SSH_REMOTE_DISPLAY} |
| +use this variable to define the ssh command executed by the remote display tool. |
| + |
| +@item @env{GPROFNG_SKIP_VALIDATION} |
| +set this variable to disable checking hardware, system, and Java versions. |
| + |
| +@item @env{GPROFNG_ALLOW_CORE_DUMP} |
| +set this variable to allow a core file to be generated; otherwise an error report is created on /tmp. |
| + |
| +@item @env{GPROFNG_ARCHIVE} |
| +use this variable to define the settings for automatic archiving upon experiment recording completion. |
| + |
| +@item @env{GPROFNG_ARCHIVE_COMMON_DIR} |
| +set this variable to the location of the common archive. |
| + |
| +@item @env{GPROFNG_JAVA_MAX_CALL_STACK_DEPTH} |
| +set the depth of the Java call stack; the default is 256; set to 0 to disable capturing of call stacks. |
| + |
| +@item @env{GPROFNG_JAVA_NATIVE_MAX_CALL_STACK_DEPTH} |
| +set the depth of the Java native call stack; the default is 256; set to 0 to disable capturing of call stacks (JNI and assembly call stacks are not captured). |
| + |
| +@end table |
| + |
| +@c man end |
| + |
| +@c man begin SEEALSO |
| +The man pages for the various gprofng commands are not available yet, but |
| +the @option{--help} option supported on each of the commands lists the options |
| +and provides more information. |
| + |
| +For example this displays the options supported on the @command{gprofng collect app} |
| +command: |
| + |
| +@smallexample |
| +$ gprofng collect app --help |
| +@end smallexample |
| + |
| +The user guide is available as an Info entry for @file{gprofng}. |
| +@c man end |
| + |
| +@end ifset |
| + |
| +@c man begin DESCRIPTION |
| +@c man end |
| + |
| @c -- A new node -------------------------------------------------------------- |
| @node Introduction |
| @chapter Introduction |
| --- a/gprofng/src/Makefile.am |
| +++ b/gprofng/src/Makefile.am |
| @@ -160,7 +160,7 @@ gp_display_text_LDADD = $(LIBGPROFNG) $( |
| |
| if BUILD_MAN |
| |
| -man_MANS = gprofng.1 \ |
| +man_MANS = \ |
| gp-archive.1 \ |
| gp-collect-app.1 \ |
| gp-display-src.1 \ |
| @@ -191,10 +191,6 @@ H2M_FILTER = | sed 's/\.TP/\.TP\n.B/' | |
| | sed 's/See also:/\.SH SEE ALSO/' | sed 's/Documentation:/.SH DOCUMENTATION/' \ |
| | sed 's/Limitations:/.SH LIMITATIONS/' |
| |
| -gprofng.1: $(srcdir)/gprofng.cc $(common_mandeps) | ./gprofng$(EXEEXT) |
| - $(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \ |
| - --name=$(TEXT_GPROFNG) ./gprofng$(EXEEXT) $(H2M_FILTER) > $@ |
| - |
| 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) > $@ |
| @@ -223,3 +219,5 @@ dist-hook: $(LIBGPROFNG) |
| |
| install-data-local: install-pkglibLTLIBRARIES |
| rm -f $(DESTDIR)/$(pkglibdir)/*.la $(DESTDIR)/$(pkglibdir)/*.a |
| + |
| +$(srcdir)/DbeSession.cc: QLParser.tab.hh |
| --- a/gprofng/src/Makefile.in |
| +++ b/gprofng/src/Makefile.in |
| @@ -572,7 +572,7 @@ gp_display_src_SOURCES = gp-display-src. |
| 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 = gprofng.1 \ |
| +@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 \ |
| @@ -1176,10 +1176,6 @@ uninstall-man: uninstall-man1 |
| QLParser.tab.cc QLParser.tab.hh: QLParser.yy |
| $(BISON) $^ |
| |
| -@BUILD_MAN_TRUE@gprofng.1: $(srcdir)/gprofng.cc $(common_mandeps) | ./gprofng$(EXEEXT) |
| -@BUILD_MAN_TRUE@ $(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \ |
| -@BUILD_MAN_TRUE@ --name=$(TEXT_GPROFNG) ./gprofng$(EXEEXT) $(H2M_FILTER) > $@ |
| - |
| @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) > $@ |
| @@ -1207,6 +1203,8 @@ dist-hook: $(LIBGPROFNG) |
| install-data-local: install-pkglibLTLIBRARIES |
| rm -f $(DESTDIR)/$(pkglibdir)/*.la $(DESTDIR)/$(pkglibdir)/*.a |
| |
| +$(srcdir)/DbeSession.cc: QLParser.tab.hh |
| + |
| # 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: |