toolchain/binutils/patches/2.40/018-gprofng-PR29521-docs-man-pages-are-not-in-the-releas.patch

   1 From c6e269febbc946a54ed9dbbb2dc70feba6017607 Mon Sep 17 00:00:00 2001
   2 From: Vladimir Mezentsev <vladimir.mezentsev@oracle.com>
   3 Date: Fri, 20 Jan 2023 15:39:55 -0800
   4 Subject: [PATCH 18/50] gprofng: PR29521 [docs] man pages are not in the
   5  release tarball
   6
   7 gprofng/ChangeLog
   8 2023-01-20  Vladimir Mezentsev  <vladimir.mezentsev@oracle.com>
   9
  10         PR gprofng/29521
  11         * configure.ac: Check if $MAKEINFO and $HELP2MAN are missing.
  12         * Makefile.am: Build doc if $MAKEINFO exists.
  13         * doc/gprofng.texi: Update documentation for gprofng.
  14         * doc/Makefile.am: Build gprofng.1.
  15         * src/Makefile.am: Move the build of gprofng.1 to doc/Makefile.am.
  16         * configure: Rebuild.
  17         * Makefile.in: Rebuild.
  18         * doc/Makefile.in: Rebuild.
  19         * src/Makefile.in: Rebuild.
  20 ---
  21  gprofng/Makefile.am      |   2 +-
  22  gprofng/Makefile.in      |   2 +-
  23  gprofng/configure        |  79 +++++++++++++++---
  24  gprofng/configure.ac     |  21 +++--
  25  gprofng/doc/Makefile.am  |  24 +++++-
  26  gprofng/doc/Makefile.in  |  93 ++++++++++++++++++---
  27  gprofng/doc/gprofng.texi | 169 +++++++++++++++++++++++++++++++++++++++
  28  gprofng/src/Makefile.am  |   8 +-
  29  gprofng/src/Makefile.in  |   8 +-
  30  9 files changed, 364 insertions(+), 42 deletions(-)
  31
  32 --- a/gprofng/Makefile.am
  33 +++ b/gprofng/Makefile.am
  34 @@ -23,7 +23,7 @@ AUTOMAKE_OPTIONS = dejagnu foreign
  35  if BUILD_COLLECTOR
  36      COLLECTOR_SUBDIRS = libcollector
  37  endif
  38 -if BUILD_MAN
  39 +if BUILD_DOC
  40      DOC_SUBDIR = doc
  41  endif
  42  if BUILD_SRC
  43 --- a/gprofng/Makefile.in
  44 +++ b/gprofng/Makefile.in
  45 @@ -381,7 +381,7 @@ zlibinc = @zlibinc@
  46  ACLOCAL_AMFLAGS = -I . -I ..
  47  AUTOMAKE_OPTIONS = dejagnu foreign
  48  @BUILD_COLLECTOR_TRUE@COLLECTOR_SUBDIRS = libcollector
  49 -@BUILD_MAN_TRUE@DOC_SUBDIR = doc
  50 +@BUILD_DOC_TRUE@DOC_SUBDIR = doc
  51  @BUILD_SRC_TRUE@SRC_SUBDIRS = src gp-display-html $(DOC_SUBDIR)
  52  SUBDIRS = $(COLLECTOR_SUBDIRS) $(SRC_SUBDIRS)
  53  DIST_SUBDIRS = libcollector src gp-display-html $(DOC_SUBDIR)
  54 --- a/gprofng/configure
  55 +++ b/gprofng/configure
  56 @@ -639,6 +639,8 @@ GPROFNG_CPPFLAGS
  57  GPROFNG_NO_FORMAT_TRUNCATION_CFLAGS
  58  GPROFNG_CFLAGS
  59  LD_NO_AS_NEEDED
  60 +BUILD_DOC_FALSE
  61 +BUILD_DOC_TRUE
  62  BUILD_MAN_FALSE
  63  BUILD_MAN_TRUE
  64  HELP2MAN
  65 @@ -12221,7 +12223,7 @@ else
  66    lt_dlunknown=0; lt_dlno_uscore=1; lt_dlneed_uscore=2
  67    lt_status=$lt_dlunknown
  68    cat > conftest.$ac_ext <<_LT_EOF
  69 -#line 12224 "configure"
  70 +#line 12226 "configure"
  71  #include "confdefs.h"
  72
  73  #if HAVE_DLFCN_H
  74 @@ -12327,7 +12329,7 @@ else
  75    lt_dlunknown=0; lt_dlno_uscore=1; lt_dlneed_uscore=2
  76    lt_status=$lt_dlunknown
  77    cat > conftest.$ac_ext <<_LT_EOF
  78 -#line 12330 "configure"
  79 +#line 12332 "configure"
  80  #include "confdefs.h"
  81
  82  #if HAVE_DLFCN_H
  83 @@ -16737,9 +16739,58 @@ fi
  84
  85  # Generate manpages, if possible.
  86  build_man=false
  87 +build_doc=false
  88  if test $cross_compiling = no; then
  89 +  for ac_prog in help2man
  90 +do
  91 +  # Extract the first word of "$ac_prog", so it can be a program name with args.
  92 +set dummy $ac_prog; ac_word=$2
  93 +{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
  94 +$as_echo_n "checking for $ac_word... " >&6; }
  95 +if ${ac_cv_prog_HELP2MAN+:} false; then :
  96 +  $as_echo_n "(cached) " >&6
  97 +else
  98 +  if test -n "$HELP2MAN"; then
  99 +  ac_cv_prog_HELP2MAN="$HELP2MAN" # Let the user override the test.
 100 +else
 101 +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
 102 +for as_dir in $PATH
 103 +do
 104 +  IFS=$as_save_IFS
 105 +  test -z "$as_dir" && as_dir=.
 106 +    for ac_exec_ext in '' $ac_executable_extensions; do
 107 +  if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
 108 +    ac_cv_prog_HELP2MAN="$ac_prog"
 109 +    $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
 110 +    break 2
 111 +  fi
 112 +done
 113 +  done
 114 +IFS=$as_save_IFS
 115 +
 116 +fi
 117 +fi
 118 +HELP2MAN=$ac_cv_prog_HELP2MAN
 119 +if test -n "$HELP2MAN"; then
 120 +  { $as_echo "$as_me:${as_lineno-$LINENO}: result: $HELP2MAN" >&5
 121 +$as_echo "$HELP2MAN" >&6; }
 122 +else
 123 +  { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
 124 +$as_echo "no" >&6; }
 125 +fi
 126
 127 -HELP2MAN=${HELP2MAN-"${am_missing_run}help2man"}
 128 +
 129 +  test -n "$HELP2MAN" && break
 130 +done
 131 +test -n "$HELP2MAN" || HELP2MAN="$MISSING help2man"
 132 +
 133 +  case "x$HELP2MAN" in
 134 +    x | */missing\ help2man* )
 135 +      { $as_echo "$as_me:${as_lineno-$LINENO}: WARNING: gprofng: help2man is missing. Man pages will not be built." >&5
 136 +$as_echo "$as_me: WARNING: gprofng: help2man is missing. Man pages will not be built." >&2;}
 137 +      ;;
 138 +    * ) build_man=true ;;
 139 +    esac
 140
 141    for ac_prog in makeinfo
 142  do
 143 @@ -16782,10 +16833,10 @@ fi
 144
 145    test -n "$MAKEINFO" && break
 146  done
 147 -test -n "$MAKEINFO" || MAKEINFO=""@echo makeinfo missing; true""
 148 +test -n "$MAKEINFO" || MAKEINFO="$MISSING makeinfo"
 149
 150 -  case "$MAKEINFO" in
 151 -    *true)
 152 +  case "x$MAKEINFO" in
 153 +    x | */missing\ makeinfo*)
 154        { $as_echo "$as_me:${as_lineno-$LINENO}: WARNING: gprofng: makeinfo is missing. Info documentation will not be built." >&5
 155  $as_echo "$as_me: WARNING: gprofng: makeinfo is missing. Info documentation will not be built." >&2;}
 156        ;;
 157 @@ -16796,9 +16847,7 @@ $as_echo "$as_me: WARNING: gprofng: make
 158  $as_echo "$as_me: WARNING: gprofng: $MAKEINFO is too old. Info documentation will not be built." >&2;}
 159           MAKEINFO="@echo $MAKEINFO is too old, 6.5 or newer required; true"
 160           ;;
 161 -       x* )
 162 -         build_man=true
 163 -         ;;
 164 +       x* ) build_doc=true ;;
 165         esac
 166        ;;
 167      esac
 168 @@ -16812,6 +16861,14 @@ else
 169    BUILD_MAN_FALSE=
 170  fi
 171
 172 + if test x$build_doc = xtrue; then
 173 +  BUILD_DOC_TRUE=
 174 +  BUILD_DOC_FALSE='#'
 175 +else
 176 +  BUILD_DOC_TRUE='#'
 177 +  BUILD_DOC_FALSE=
 178 +fi
 179 +
 180
 181  LD_NO_AS_NEEDED=${no_as_needed}
 182
 183 @@ -17070,6 +17127,10 @@ if test -z "${BUILD_MAN_TRUE}" && test -
 184    as_fn_error $? "conditional \"BUILD_MAN\" was never defined.
 185  Usually this means the macro was only invoked conditionally." "$LINENO" 5
 186  fi
 187 +if test -z "${BUILD_DOC_TRUE}" && test -z "${BUILD_DOC_FALSE}"; then
 188 +  as_fn_error $? "conditional \"BUILD_DOC\" was never defined.
 189 +Usually this means the macro was only invoked conditionally." "$LINENO" 5
 190 +fi
 191
 192  : "${CONFIG_STATUS=./config.status}"
 193  ac_write_fail=0
 194 --- a/gprofng/configure.ac
 195 +++ b/gprofng/configure.ac
 196 @@ -210,11 +210,19 @@ AM_ZLIB
 197
 198  # Generate manpages, if possible.
 199  build_man=false
 200 +build_doc=false
 201  if test $cross_compiling = no; then
 202 -  AM_MISSING_PROG(HELP2MAN, help2man)
 203 -  AC_CHECK_PROGS([MAKEINFO], makeinfo, ["@echo makeinfo missing; true"])
 204 -  case "$MAKEINFO" in
 205 -    *true)
 206 +  AC_CHECK_PROGS([HELP2MAN], help2man, [$MISSING help2man])
 207 +  case "x$HELP2MAN" in
 208 +    x | */missing\ help2man* )
 209 +      AC_MSG_WARN([gprofng: help2man is missing. Man pages will not be built.])
 210 +      ;;
 211 +    * ) build_man=true ;;
 212 +    esac
 213 +
 214 +  AC_CHECK_PROGS([MAKEINFO], makeinfo, [$MISSING makeinfo])
 215 +  case "x$MAKEINFO" in
 216 +    x | */missing\ makeinfo*)
 217        AC_MSG_WARN([gprofng: makeinfo is missing. Info documentation will not be built.])
 218        ;;
 219      *)
 220 @@ -223,15 +231,14 @@ if test $cross_compiling = no; then
 221           AC_MSG_WARN([gprofng: $MAKEINFO is too old. Info documentation will not be built.])
 222           MAKEINFO="@echo $MAKEINFO is too old, 6.5 or newer required; true"
 223           ;;
 224 -       x* )
 225 -         build_man=true
 226 -         ;;
 227 +       x* ) build_doc=true ;;
 228         esac
 229        ;;
 230      esac
 231    AC_SUBST(MAKEINFO)
 232  fi
 233  AM_CONDITIONAL([BUILD_MAN], [test x$build_man = xtrue])
 234 +AM_CONDITIONAL([BUILD_DOC], [test x$build_doc = xtrue])
 235
 236  AC_SUBST(LD_NO_AS_NEEDED, [${no_as_needed}])
 237  AC_SUBST(GPROFNG_CFLAGS, [${gprofng_cflags}])
 238 --- a/gprofng/doc/Makefile.am
 239 +++ b/gprofng/doc/Makefile.am
 240 @@ -19,9 +19,31 @@
 241
 242  AUTOMAKE_OPTIONS = info-in-builddir foreign no-texinfo.tex
 243
 244 +# Options to extract the man page
 245 +MANCONF = -Dman
 246 +
 247 +TEXI2POD = perl $(srcdir)/../../etc/texi2pod.pl $(AM_MAKEINFOFLAGS)
 248 +POD2MAN = pod2man --center="User Commands" \
 249 +       --release="binutils-$(VERSION)" --section=1
 250 +
 251  info_TEXINFOS       = gprofng.texi
 252  gprofng_TEXINFOS    = fdl.texi
 253  TEXINFO_TEX         = .
 254  MAKEINFOHTML        = $(MAKEINFO) --html --no-split
 255
 256 -MAINTAINERCLEANFILES = gprofng.info
 257 +man_MANS = gprofng.1
 258 +
 259 +# Build the man page from the texinfo file
 260 +# The sed command removes the no-adjust Nroff command so that
 261 +# the man output looks standard.
 262 +gprofng.1: $(srcdir)/gprofng.texi
 263 +       $(AM_V_GEN)touch $@
 264 +       $(AM_V_at)-$(TEXI2POD) $(MANCONF) < $(srcdir)/gprofng.texi > gprofng.pod
 265 +       $(AM_V_at)-($(POD2MAN) gprofng.pod | \
 266 +         sed -e '/^.if n .na/d' > $@.tmp && \
 267 +         mv -f $@.tmp $@) || (rm -f $@.tmp && exit 1)
 268 +       $(AM_V_at)rm -f gprofng.pod
 269 +
 270 +MAINTAINERCLEANFILES = gprofng.info $(man_MANS)
 271 +
 272 +info: $(man_MANS)
 273 --- a/gprofng/doc/Makefile.in
 274 +++ b/gprofng/doc/Makefile.in
 275 @@ -182,7 +182,7 @@ am__can_run_installinfo = \
 276      n|no|NO) false;; \
 277      *) (install-info --version) >/dev/null 2>&1;; \
 278    esac
 279 -am__installdirs = "$(DESTDIR)$(infodir)"
 280 +am__installdirs = "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"
 281  am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
 282  am__vpath_adj = case $$p in \
 283      $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \
 284 @@ -210,6 +210,9 @@ am__uninstall_files_from_dir = { \
 285      || { echo " ( cd '$$dir' && rm -f" $$files ")"; \
 286           $(am__cd) "$$dir" && rm -f $$files; }; \
 287    }
 288 +man1dir = $(mandir)/man1
 289 +NROFF = nroff
 290 +MANS = $(man_MANS)
 291  am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
 292  am__DIST_COMMON = $(gprofng_TEXINFOS) $(srcdir)/Makefile.in \
 293         $(top_srcdir)/../mkinstalldirs mdate-sh texinfo.tex
 294 @@ -361,11 +364,19 @@ top_srcdir = @top_srcdir@
 295  zlibdir = @zlibdir@
 296  zlibinc = @zlibinc@
 297  AUTOMAKE_OPTIONS = info-in-builddir foreign no-texinfo.tex
 298 +
 299 +# Options to extract the man page
 300 +MANCONF = -Dman
 301 +TEXI2POD = perl $(srcdir)/../../etc/texi2pod.pl $(AM_MAKEINFOFLAGS)
 302 +POD2MAN = pod2man --center="User Commands" \
 303 +       --release="binutils-$(VERSION)" --section=1
 304 +
 305  info_TEXINFOS = gprofng.texi
 306  gprofng_TEXINFOS = fdl.texi
 307  TEXINFO_TEX = .
 308  MAKEINFOHTML = $(MAKEINFO) --html --no-split
 309 -MAINTAINERCLEANFILES = gprofng.info
 310 +man_MANS = gprofng.1
 311 +MAINTAINERCLEANFILES = gprofng.info $(man_MANS)
 312  all: all-am
 313
 314  .SUFFIXES:
 315 @@ -558,6 +569,49 @@ maintainer-clean-aminfo:
 316           echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \
 317           rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \
 318         done
 319 +install-man1: $(man_MANS)
 320 +       @$(NORMAL_INSTALL)
 321 +       @list1=''; \
 322 +       list2='$(man_MANS)'; \
 323 +       test -n "$(man1dir)" \
 324 +         && test -n "`echo $$list1$$list2`" \
 325 +         || exit 0; \
 326 +       echo " $(MKDIR_P) '$(DESTDIR)$(man1dir)'"; \
 327 +       $(MKDIR_P) "$(DESTDIR)$(man1dir)" || exit 1; \
 328 +       { for i in $$list1; do echo "$$i"; done;  \
 329 +       if test -n "$$list2"; then \
 330 +         for i in $$list2; do echo "$$i"; done \
 331 +           | sed -n '/\.1[a-z]*$$/p'; \
 332 +       fi; \
 333 +       } | while read p; do \
 334 +         if test -f $$p; then d=; else d="$(srcdir)/"; fi; \
 335 +         echo "$$d$$p"; echo "$$p"; \
 336 +       done | \
 337 +       sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
 338 +             -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \
 339 +       sed 'N;N;s,\n, ,g' | { \
 340 +       list=; while read file base inst; do \
 341 +         if test "$$base" = "$$inst"; then list="$$list $$file"; else \
 342 +           echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \
 343 +           $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst" || exit $$?; \
 344 +         fi; \
 345 +       done; \
 346 +       for i in $$list; do echo "$$i"; done | $(am__base_list) | \
 347 +       while read files; do \
 348 +         test -z "$$files" || { \
 349 +           echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man1dir)'"; \
 350 +           $(INSTALL_DATA) $$files "$(DESTDIR)$(man1dir)" || exit $$?; }; \
 351 +       done; }
 352 +
 353 +uninstall-man1:
 354 +       @$(NORMAL_UNINSTALL)
 355 +       @list=''; test -n "$(man1dir)" || exit 0; \
 356 +       files=`{ for i in $$list; do echo "$$i"; done; \
 357 +       l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \
 358 +         sed -n '/\.1[a-z]*$$/p'; \
 359 +       } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
 360 +             -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
 361 +       dir='$(DESTDIR)$(man1dir)'; $(am__uninstall_files_from_dir)
 362  tags TAGS:
 363
 364  ctags CTAGS:
 365 @@ -600,9 +654,9 @@ distdir: $(DISTFILES)
 366           dist-info
 367  check-am: all-am
 368  check: check-am
 369 -all-am: Makefile $(INFO_DEPS)
 370 +all-am: Makefile $(INFO_DEPS) $(MANS)
 371  installdirs:
 372 -       for dir in "$(DESTDIR)$(infodir)"; do \
 373 +       for dir in "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"; do \
 374           test -z "$$dir" || $(MKDIR_P) "$$dir"; \
 375         done
 376  install: install-am
 377 @@ -652,11 +706,9 @@ html: html-am
 378
 379  html-am: $(HTMLS)
 380
 381 -info: info-am
 382 -
 383  info-am: $(INFO_DEPS)
 384
 385 -install-data-am: install-info-am
 386 +install-data-am: install-info-am install-man
 387
 388  install-dvi: install-dvi-am
 389
 390 @@ -739,7 +791,7 @@ install-info-am: $(INFO_DEPS)
 391             install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\
 392           done; \
 393         else : ; fi
 394 -install-man:
 395 +install-man: install-man1
 396
 397  install-pdf: install-pdf-am
 398
 399 @@ -794,7 +846,9 @@ ps: ps-am
 400  ps-am: $(PSS)
 401
 402  uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \
 403 -       uninstall-pdf-am uninstall-ps-am
 404 +       uninstall-man uninstall-pdf-am uninstall-ps-am
 405 +
 406 +uninstall-man: uninstall-man1
 407
 408  .MAKE: install-am install-strip
 409
 410 @@ -804,19 +858,32 @@ uninstall-am: uninstall-dvi-am uninstall
 411         html-am info info-am install install-am install-data \
 412         install-data-am install-dvi install-dvi-am install-exec \
 413         install-exec-am install-html install-html-am install-info \
 414 -       install-info-am install-man install-pdf install-pdf-am \
 415 -       install-ps install-ps-am install-strip installcheck \
 416 -       installcheck-am installdirs maintainer-clean \
 417 +       install-info-am install-man install-man1 install-pdf \
 418 +       install-pdf-am install-ps install-ps-am install-strip \
 419 +       installcheck installcheck-am installdirs maintainer-clean \
 420         maintainer-clean-aminfo maintainer-clean-generic \
 421         maintainer-clean-vti mostlyclean mostlyclean-aminfo \
 422         mostlyclean-generic mostlyclean-libtool mostlyclean-vti pdf \
 423         pdf-am ps ps-am tags-am uninstall uninstall-am \
 424         uninstall-dvi-am uninstall-html-am uninstall-info-am \
 425 -       uninstall-pdf-am uninstall-ps-am
 426 +       uninstall-man uninstall-man1 uninstall-pdf-am uninstall-ps-am
 427
 428  .PRECIOUS: Makefile
 429
 430
 431 +# Build the man page from the texinfo file
 432 +# The sed command removes the no-adjust Nroff command so that
 433 +# the man output looks standard.
 434 +gprofng.1: $(srcdir)/gprofng.texi
 435 +       $(AM_V_GEN)touch $@
 436 +       $(AM_V_at)-$(TEXI2POD) $(MANCONF) < $(srcdir)/gprofng.texi > gprofng.pod
 437 +       $(AM_V_at)-($(POD2MAN) gprofng.pod | \
 438 +         sed -e '/^.if n .na/d' > $@.tmp && \
 439 +         mv -f $@.tmp $@) || (rm -f $@.tmp && exit 1)
 440 +       $(AM_V_at)rm -f gprofng.pod
 441 +
 442 +info: $(man_MANS)
 443 +
 444  # Tell versions [3.59,3.63) of GNU make to not export all variables.
 445  # Otherwise a system limit (for SysV at least) may be exceeded.
 446  .NOEXPORT:
 447 --- a/gprofng/doc/gprofng.texi
 448 +++ b/gprofng/doc/gprofng.texi
 449 @@ -1,5 +1,8 @@
 450  \input texinfo @c -*-texinfo-*-
 451
 452 +@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
 453 +@c               BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
 454 +
 455  @c ----------------------------------------------------------------------------
 456  @c This is the Texinfo source file for the GPROFNG manual.
 457  @c
 458 @@ -59,6 +62,10 @@ gprofng
 459  @cindex \label\, \string\
 460  @end macro
 461
 462 +@macro gcctabopt{body}
 463 +@code{\body\}
 464 +@end macro
 465 +
 466  @c -- Get the version information ---------------------------------------------
 467  @include version.texi
 468
 469 @@ -99,6 +106,20 @@ section entitled ``GNU Free Documentatio
 470  @page
 471  @vskip 0pt plus 1filll
 472  @insertcopying
 473 +
 474 +@c man begin COPYRIGHT
 475 +
 476 +Copyright @copyright{} 2022-2023 Free Software Foundation, Inc.
 477 +
 478 +Permission is granted to copy, distribute and/or modify this document
 479 +under the terms of the GNU Free Documentation License, Version 1.3
 480 +or any later version published by the Free Software Foundation;
 481 +with no Invariant Sections, with no Front-Cover Texts, and with no
 482 +Back-Cover Texts.  A copy of the license is included in the
 483 +section entitled ``GNU Free Documentation License''.
 484 +
 485 +@c man end
 486 +
 487  @end titlepage
 488
 489  @c -- Generate the Table of Contents ------------------------------------------
 490 @@ -163,6 +184,154 @@ Terminology
 491  @end menu
 492  @end ifinfo
 493
 494 +@ifset man
 495 +
 496 +@c man title gprofng the driver for the gprofng tool suite
 497 +
 498 +@c man begin SYNOPSIS
 499 +gprofng [OPTION(S)] ACTION [@b{QUALIFIER}] [ARGUMENTS] TARGET
 500 +@c man end
 501 +
 502 +@c man begin DESCRIPTION
 503 +This is the driver for the GPROFNG tools suite to gather and analyze performance data.
 504 +
 505 +The driver executes the action specified. An example of an action is @code{collect}
 506 +to collect performance data. Depending on the action, a qualifier may be needed to
 507 +define the command. Several qualifiers support options. The last item on the command
 508 +is the target the command applies to.
 509 +
 510 +For example, to collect performance data for an application called @code{a.out} and
 511 +store the results in experiment directory @code{mydata.er}, the following command may
 512 +be used:
 513 +
 514 +@smallexample
 515 +$ gprofng collect app -o mydata.er a.out
 516 +@end smallexample
 517 +
 518 +In this example, the action is @code{collect}, the qualifier is @code{app}, the single
 519 +argument is @code{-o mydata.er} and the target is @code{a.out}.
 520 +
 521 +If gprofng is executed without any additional option, action, or target, a usage
 522 +overview is printed.
 523 +
 524 +@c man end
 525 +
 526 +@c man begin OPTIONS
 527 +
 528 +@table @gcctabopt
 529 +
 530 +@item @var{--version}
 531 +print the version number and exit.
 532 +
 533 +@item @var{--help}
 534 +print usage information and exit.
 535 +
 536 +@end table
 537 +
 538 +@c man end
 539 +
 540 +@c man begin NOTES
 541 +
 542 +The gprofng driver supports the following commands.
 543 +
 544 +@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
 545 +@c        name for "gprofng collect app" is "gp-collect-app".
 546 +
 547 +Collect performance data:
 548 +
 549 +@table @code
 550 +
 551 +@item gprofng collect app
 552 +collect application performance data.
 553 +
 554 +@end table
 555 +
 556 +Display the performance results:
 557 +
 558 +@table @code
 559 +
 560 +@item gprofng display text
 561 +display the performance data in ASCII format.
 562 +
 563 +@item gprofng display html
 564 +generate an HTML file from one or more experiments.
 565 +
 566 +@end table
 567 +
 568 +Miscellaneous commands:
 569 +
 570 +@table @code
 571 +
 572 +@item gprofng display src
 573 +display source or disassembly with compiler annotations.
 574 +
 575 +@item gprofng archive
 576 +include binaries and source code in an experiment directory.
 577 +
 578 +@end table
 579 +
 580 +It is also possible to invoke the lower level commands directly, but since
 581 +these are subject to change, in particular the options, we recommend to
 582 +use the driver.
 583 +
 584 +@c man end
 585 +
 586 +@c man begin ENVIRONMENT
 587 +The following environment variables are supported:
 588 +
 589 +@table @code
 590 +
 591 +@item @env{GPROFNG_MAX_CALL_STACK_DEPTH}
 592 +set the depth of the call stack (default is 256).
 593 +
 594 +@item @env{GPROFNG_USE_JAVA_OPTIONS}
 595 +may be set when profiling a C/C++ application that uses dlopen() to execute Java code.
 596 +
 597 +@item @env{GPROFNG_SSH_REMOTE_DISPLAY}
 598 +use this variable to define the ssh command executed by the remote display tool.
 599 +
 600 +@item @env{GPROFNG_SKIP_VALIDATION}
 601 +set this variable to disable checking hardware, system, and Java versions.
 602 +
 603 +@item @env{GPROFNG_ALLOW_CORE_DUMP}
 604 +set this variable to allow a core file to be generated; otherwise an error report is created on /tmp.
 605 +
 606 +@item @env{GPROFNG_ARCHIVE}
 607 +use this variable to define the settings for automatic archiving upon experiment recording completion.
 608 +
 609 +@item @env{GPROFNG_ARCHIVE_COMMON_DIR}
 610 +set this variable to the location of the common archive.
 611 +
 612 +@item @env{GPROFNG_JAVA_MAX_CALL_STACK_DEPTH}
 613 +set the depth of the Java call stack; the default is 256; set to 0 to disable capturing of call stacks.
 614 +
 615 +@item @env{GPROFNG_JAVA_NATIVE_MAX_CALL_STACK_DEPTH}
 616 +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).
 617 +
 618 +@end table
 619 +
 620 +@c man end
 621 +
 622 +@c man begin SEEALSO
 623 +The man pages for the various gprofng commands are not available yet, but
 624 +the @option{--help} option supported on each of the commands lists the options
 625 +and provides more information.
 626 +
 627 +For example this displays the options supported on the @command{gprofng collect app}
 628 +command:
 629 +
 630 +@smallexample
 631 +$ gprofng collect app --help
 632 +@end smallexample
 633 +
 634 +The user guide is available as an Info entry for @file{gprofng}.
 635 +@c man end
 636 +
 637 +@end ifset
 638 +
 639 +@c man begin DESCRIPTION
 640 +@c man end
 641 +
 642  @c -- A new node --------------------------------------------------------------
 643  @node    Introduction
 644  @chapter Introduction
 645 --- a/gprofng/src/Makefile.am
 646 +++ b/gprofng/src/Makefile.am
 647 @@ -160,7 +160,7 @@ gp_display_text_LDADD = $(LIBGPROFNG) $(
 648
 649  if BUILD_MAN
 650
 651 -man_MANS = gprofng.1 \
 652 +man_MANS = \
 653         gp-archive.1 \
 654         gp-collect-app.1 \
 655         gp-display-src.1 \
 656 @@ -191,10 +191,6 @@ H2M_FILTER = | sed 's/\.TP/\.TP\n.B/' |
 657    | sed 's/See also:/\.SH SEE ALSO/' | sed 's/Documentation:/.SH DOCUMENTATION/' \
 658    | sed 's/Limitations:/.SH LIMITATIONS/'
 659
 660 -gprofng.1: $(srcdir)/gprofng.cc $(common_mandeps) | ./gprofng$(EXEEXT)
 661 -       $(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
 662 -         --name=$(TEXT_GPROFNG) ./gprofng$(EXEEXT) $(H2M_FILTER) > $@
 663 -
 664  gp-archive.1: $(srcdir)/gp-archive.cc $(common_mandeps) | ./gp-archive$(EXEEXT)
 665         $(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
 666           --name=$(TEXT_GP_ARCHIVE) ./gp-archive$(EXEEXT) $(H2M_FILTER) > $@
 667 @@ -223,3 +219,5 @@ dist-hook: $(LIBGPROFNG)
 668
 669  install-data-local: install-pkglibLTLIBRARIES
 670         rm -f $(DESTDIR)/$(pkglibdir)/*.la $(DESTDIR)/$(pkglibdir)/*.a
 671 +
 672 +$(srcdir)/DbeSession.cc: QLParser.tab.hh
 673 --- a/gprofng/src/Makefile.in
 674 +++ b/gprofng/src/Makefile.in
 675 @@ -572,7 +572,7 @@ gp_display_src_SOURCES = gp-display-src.
 676  gp_display_src_LDADD = $(LIBGPROFNG) $(CLOCK_GETTIME_LINK) $(ZLIB)
 677  gp_display_text_SOURCES = gp-display-text.cc ipc.cc ipcio.cc
 678  gp_display_text_LDADD = $(LIBGPROFNG) $(CLOCK_GETTIME_LINK) $(ZLIB)
 679 -@BUILD_MAN_TRUE@man_MANS = gprofng.1 \
 680 +@BUILD_MAN_TRUE@man_MANS = \
 681  @BUILD_MAN_TRUE@       gp-archive.1 \
 682  @BUILD_MAN_TRUE@       gp-collect-app.1 \
 683  @BUILD_MAN_TRUE@       gp-display-src.1 \
 684 @@ -1176,10 +1176,6 @@ uninstall-man: uninstall-man1
 685  QLParser.tab.cc QLParser.tab.hh: QLParser.yy
 686         $(BISON) $^
 687
 688 -@BUILD_MAN_TRUE@gprofng.1: $(srcdir)/gprofng.cc $(common_mandeps) | ./gprofng$(EXEEXT)
 689 -@BUILD_MAN_TRUE@       $(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
 690 -@BUILD_MAN_TRUE@         --name=$(TEXT_GPROFNG) ./gprofng$(EXEEXT) $(H2M_FILTER) > $@
 691 -
 692  @BUILD_MAN_TRUE@gp-archive.1: $(srcdir)/gp-archive.cc $(common_mandeps) | ./gp-archive$(EXEEXT)
 693  @BUILD_MAN_TRUE@       $(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
 694  @BUILD_MAN_TRUE@         --name=$(TEXT_GP_ARCHIVE) ./gp-archive$(EXEEXT) $(H2M_FILTER) > $@
 695 @@ -1207,6 +1203,8 @@ dist-hook: $(LIBGPROFNG)
 696  install-data-local: install-pkglibLTLIBRARIES
 697         rm -f $(DESTDIR)/$(pkglibdir)/*.la $(DESTDIR)/$(pkglibdir)/*.a
 698
 699 +$(srcdir)/DbeSession.cc: QLParser.tab.hh
 700 +
 701  # Tell versions [3.59,3.63) of GNU make to not export all variables.
 702  # Otherwise a system limit (for SysV at least) may be exceeded.
 703  .NOEXPORT: