gprofng/doc/gprofng.texi

   1 @c ----------------------------------------------------------------------------
   2 @c This is the Texinfo source file for the gprofng man page.
   3 @c
   4 @c Author: Ruud van der Pas
   5 @c ----------------------------------------------------------------------------
   6 @ifset man
   7 \input texinfo @c -*-texinfo-*-
   8 @setfilename gprofng
   9 @settitle The next generation GNU application profiling tool
  10 @include gp-macros.texi
  11 @end ifset
  12
  13 @c @ManPageStart{NAME}
  14 @c @ManPageStart{SYNOPSIS}
  15 @c @ManPageStart{DESCRIPTION}
  16 @c @ManPageStart{OPTIONS}
  17 @c @ManPageStart{NOTES}
  18 @c @ManPageStart{SEEALSO}
  19 @c @ManPageStart{COPYRIGHT}
  20
  21 @c ----------------------------------------------------------------------------
  22 @c This is from the man-pages(7) man page
  23 @c
  24 @c "The list below shows conventional or suggested sections.  Most manual pages
  25 @c  should include at least the highlighted sections.  Arrange a new manual
  26 @c  page so that sections are placed in the order shown in the list."
  27 @c
  28 @c              NAME
  29 @c              SYNOPSIS
  30 @c              CONFIGURATION    [Normally only in Section 4]
  31 @c              DESCRIPTION
  32 @c              OPTIONS          [Normally only in Sections 1, 8]
  33 @c              EXIT STATUS      [Normally only in Sections 1, 8]
  34 @c              RETURN VALUE     [Normally only in Sections 2, 3]
  35 @c              ERRORS           [Typically only in Sections 2, 3]
  36 @c              ENVIRONMENT
  37 @c              FILES
  38 @c              VERSIONS         [Normally only in Sections 2, 3]
  39 @c              ATTRIBUTES       [Normally only in Sections 2, 3]
  40 @c              CONFORMING TO
  41 @c              NOTES
  42 @c              BUGS
  43 @c              EXAMPLES
  44 @c              AUTHORS          [Discouraged]
  45 @c              REPORTING BUGS   [Not used in man-pages]
  46 @c              COPYRIGHT        [Not used in man-pages]
  47 @c              SEE ALSO
  48 @c
  49 @c This is what the texi2pod.pl tool recognizes:
  50 @c
  51 @c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
  52 @c               BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
  53 @c
  54 @c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
  55 @c makes sense and adhered to for the other formats.
  56 @c ----------------------------------------------------------------------------
  57
  58 @c ----------------------------------------------------------------------------
  59 @c NAME section
  60 @c ----------------------------------------------------------------------------
  61
  62 @ManPageStart{NAME}
  63 @c man begin NAME
  64
  65 gprofng - The driver for the gprofng application profiling tool
  66
  67 @c man end
  68 @ManPageEnd{}
  69
  70 @c ----------------------------------------------------------------------------
  71 @c SYNOPSIS section
  72 @c ----------------------------------------------------------------------------
  73
  74 @ManPageStart{SYNOPSIS}
  75 @c man begin SYNOPSIS
  76
  77 @command{gprofng} [@var{option(s)}] @var{action} [@var{qualifier}]
  78 [@var{option(s)}] @var{target} [@var{options}]
  79
  80 @c man end
  81 @ManPageEnd{}
  82
  83 @c ----------------------------------------------------------------------------
  84 @c DESCRIPTION section
  85 @c ----------------------------------------------------------------------------
  86
  87 @ManPageStart{DESCRIPTION}
  88 @c man begin DESCRIPTION
  89
  90 This is the driver for the gprofng tools suite to gather and analyze
  91 performance data.
  92
  93 The driver executes the @var{action} specified.  An example of an action is
  94 @samp{collect} to collect performance data.  Depending on the action, a
  95 @var{qualifier} may be needed to further define the command.
  96 The last item is the @var{target} that the command applies to.
  97
  98 There are three places where options are supported.  The driver supports
  99 options.  These can be found below.  The @var{action}, possibly in combination
 100 with the @var{qualifier} also supports options.  A description of these can be
 101 found in the man page for the command.  Any options needed to execute the
 102 target command should follow the target name.
 103
 104 For example, to collect performance data for an application called
 105 @command{a.out} and store the results in experiment directory @samp{mydata.er},
 106 the following command may be used:
 107
 108 @smallexample
 109 $ gprofng collect app -o mydata.er a.out -t 2
 110 @end smallexample
 111
 112 In this example, the action is @samp{collect}, the qualifier is @samp{app},
 113 the single argument to the command is @code{-o mydata.er} and the target is
 114 @command{a.out}.  The target command is invoked with the @samp{-t 2} option.
 115
 116 If gprofng is executed without any additional option, action, or target, a
 117 usage overview is printed.
 118
 119 @c man end
 120 @ManPageEnd{}
 121
 122 @c ----------------------------------------------------------------------------
 123 @c OPTIONS section
 124 @c ----------------------------------------------------------------------------
 125
 126 @ManPageStart{OPTIONS}
 127 @c man begin OPTIONS
 128
 129 @table @gcctabopt
 130
 131 @item @var{--version}
 132 @ifclear man
 133 @IndexSubentry{Options, @code{--version}}
 134 @end ifclear
 135 Print the version number and exit.
 136
 137 @item @var{--help}
 138 @ifclear man
 139 @IndexSubentry{Options, @code{--help}}
 140 @end ifclear
 141 Print usage information and exit.
 142
 143 @end table
 144
 145 @c man end
 146 @ManPageEnd{}
 147
 148 @c ----------------------------------------------------------------------------
 149 @c ENVIRONMENT SECTION
 150 @c ----------------------------------------------------------------------------
 151
 152 @ManPageStart{ENVIRONMENT}
 153 @c man begin ENVIRONMENT
 154
 155 The following environment variables are supported:
 156
 157 @table @samp
 158
 159 @item @env{GPROFNG_MAX_CALL_STACK_DEPTH}
 160
 161 @ifclear man
 162 @cindex Environment variables
 163 @end ifclear
 164
 165 Set the depth of the call stack (default is 256).
 166
 167 @item @env{GPROFNG_USE_JAVA_OPTIONS}
 168
 169 @ifclear man
 170 @cindex Environment variables
 171 @end ifclear
 172
 173 May be set when profiling a C/C++ application that uses dlopen() to execute
 174 Java code.
 175
 176 @c -- deferred @item @env{GPROFNG_SSH_REMOTE_DISPLAY}
 177 @c -- deferred Use this variable to define the ssh command executed by the
 178 @c -- remote display tool.
 179
 180 @c -- deferred @item @env{GPROFNG_SKIP_VALIDATION}
 181 @c -- deferred Set this variable to disable checking hardware, system, and
 182 @c -- Java versions.
 183
 184 @item @env{GPROFNG_ALLOW_CORE_DUMP}
 185
 186 @ifclear man
 187 @cindex Environment variables
 188 @end ifclear
 189
 190 Set this variable to allow a core file to be generated; otherwise an error
 191 report is created on @samp{/tmp}.
 192
 193 @item @env{GPROFNG_ARCHIVE}
 194
 195 @ifclear man
 196 @cindex Environment variables
 197 @end ifclear
 198
 199 Use this variable to define the settings for automatic archiving upon
 200 experiment recording completion.
 201
 202 @item @env{GPROFNG_ARCHIVE_COMMON_DIR}
 203
 204 @ifclear man
 205 @cindex Environment variables
 206 @end ifclear
 207
 208 Set this variable to the location of the common archive.
 209
 210 @item @env{GPROFNG_JAVA_MAX_CALL_STACK_DEPTH}
 211
 212 @ifclear man
 213 @cindex Environment variables
 214 @end ifclear
 215
 216 Set the depth of the Java call stack; the default is 256; set to 0 to disable
 217 capturing of call stacks.
 218
 219 @item @env{GPROFNG_JAVA_NATIVE_MAX_CALL_STACK_DEPTH}
 220
 221 @ifclear man
 222 @cindex Environment variables
 223 @end ifclear
 224
 225 Set the depth of the Java native call stack; the default is 256; set to 0 to
 226 disable capturing of call stacks (JNI and assembly call stacks are not
 227 captured).
 228
 229 @item @env{GPROFNG_SYSCONFDIR}
 230
 231 @ifclear man
 232 @cindex Environment variables
 233 @end ifclear
 234
 235 Set the path to the @file{gprofng.rc} configuration file.  By default, this
 236 file is placed in the @file{etc} subdirectory of the binutils installation
 237 directory.  In case an RPM has been used for the installation, this file is
 238 in directory @file{/etc}.
 239
 240 When building and installing from the source, the user can set the path
 241 to this configuration file to a non-default location.  If this is the case,
 242 the user may set the @code{GPROFNG_SYSCONFDIR} environment variable to point
 243 to this location.
 244
 245 Otherwise, the @command{gprofng display text}, @command{gprofng display src},
 246 and @command{gprofng archive} tools cannot find this file.
 247
 248 @end table
 249
 250 @c man end
 251 @ManPageEnd{}
 252
 253 @c ----------------------------------------------------------------------------
 254 @c NOTES section
 255 @c ----------------------------------------------------------------------------
 256
 257 @ManPageStart{NOTES}
 258 @c man begin NOTES
 259
 260 The gprofng driver supports the following commands.
 261
 262 @iftex
 263 @vspace{1}
 264 @end iftex
 265
 266 @c The man pages for the commands below can be viewed using the command name
 267 @c with the spaces replaced by a dash ("-").  For example
 268 @c the man page name for "gprofng collect app" is "gprofng-collect-app".
 269
 270 @i{Collect performance data:}
 271
 272 @table @code
 273
 274 @item gprofng collect app
 275 Collect application performance data.
 276
 277 @end table
 278
 279 @i{Display the performance results:}
 280
 281 @table @code
 282
 283 @item gprofng display text
 284 Display the performance data in ASCII format.
 285
 286 @item gprofng display html
 287 Generate an HTML file from one or more experiments.
 288
 289 @item gprofng display gui
 290 Start the GUI.  Note that this tool is not available by default and needs to
 291 be installed seperately.
 292
 293 @end table
 294
 295 @i{Miscellaneous commands:}
 296
 297 @table @code
 298
 299 @item gprofng display src
 300 Display source or disassembly with compiler annotations.
 301
 302 @item gprofng archive
 303 Include binaries and source code in an experiment directory.
 304
 305 @end table
 306
 307 It is also possible to invoke the lower level commands directly, but since
 308 these are subject to change, in particular the options, we recommend to
 309 use the driver.
 310
 311 The @emph{gprofng GUI} is an optional tool that provides a graphical interface
 312 for @code{gprofng}.  It is easy to use and supports many views into the
 313 performance data.  For those interested in this GUI, we
 314 recommend to search for @code{gprofng-gui} how to obtain, install and use it.
 315
 316 @c man end
 317 @ManPageEnd{}
 318
 319 @c ----------------------------------------------------------------------------
 320 @c SEEALSO section
 321 @c ----------------------------------------------------------------------------
 322
 323 @ManPageStart{SEE ALSO}
 324 @c man begin SEEALSO
 325
 326 gprofng-archive(1),
 327 gprofng-collect-app(1),
 328 @c -- gprofng-display-gui(1),
 329 gprofng-display-html(1),
 330 gprofng-display-src(1),
 331 gprofng-display-text(1)
 332
 333 @iftex
 334 @vspace{1}
 335 @end iftex
 336
 337 Each gprofng command also supports the @option{--help} option.  This lists the
 338 options and a short description for each option.
 339
 340 For example this displays the options supported on the
 341 @command{gprofng collect app} command:
 342
 343 @smallexample
 344 $ gprofng collect app --help
 345 @end smallexample
 346
 347 The user guide for gprofng is maintained as a Texinfo manual.  If the
 348 @command{info} and @command{gprofng} programs are correctly installed, the
 349 command @command{info gprofng} should give access to this document.
 350
 351 @c man end
 352 @ManPageEnd{}
 353
 354 @c ----------------------------------------------------------------------------
 355 @c COPYRIGHT section
 356 @c ----------------------------------------------------------------------------
 357
 358 @ManPageStart{COPYRIGHT}
 359 @c man begin COPYRIGHT
 360
 361 Copyright @copyright{} 2022-2024 Free Software Foundation, Inc.
 362
 363 Permission is granted to copy, distribute and/or modify this document
 364 under the terms of the GNU Free Documentation License, Version 1.3
 365 or any later version published by the Free Software Foundation;
 366 with no Invariant Sections, with no Front-Cover Texts, and with no
 367 Back-Cover Texts.  A copy of the license is included in the
 368 section entitled ``GNU Free Documentation License''.
 369
 370 @c man end
 371 @ManPageEnd{}
 372
 373 @c ----------------------------------------------------------------------------
 374 @c If this text is used for a man page, exit.  Otherwise we need to continue.
 375 @c ----------------------------------------------------------------------------
 376
 377 @ifset man
 378 @bye
 379 @end ifset