gprofng/doc/gp-archive.texi

   1 @c ----------------------------------------------------------------------------
   2 @c This is the Texinfo source file for the gp-archive man page.
   3 @c
   4 @c Author: Ruud van der Pas
   5 @c ----------------------------------------------------------------------------
   6 @ifset man
   7 \input texinfo @c -*-texinfo-*-
   8 @setfilename gp-archive
   9 @settitle Archive gprofng experiment data
  10 @include gp-macros.texi
  11 @end ifset
  12
  13 @c ----------------------------------------------------------------------------
  14 @c This is from the man-pages(7) man page
  15 @c
  16 @c "The list below shows conventional or suggested sections.  Most manual pages
  17 @c  should include at least the highlighted sections.  Arrange a new manual
  18 @c  page so that sections are placed in the order shown in the list."
  19 @c
  20 @c              NAME
  21 @c              SYNOPSIS
  22 @c              CONFIGURATION    [Normally only in Section 4]
  23 @c              DESCRIPTION
  24 @c              OPTIONS          [Normally only in Sections 1, 8]
  25 @c              EXIT STATUS      [Normally only in Sections 1, 8]
  26 @c              RETURN VALUE     [Normally only in Sections 2, 3]
  27 @c              ERRORS           [Typically only in Sections 2, 3]
  28 @c              ENVIRONMENT
  29 @c              FILES
  30 @c              VERSIONS         [Normally only in Sections 2, 3]
  31 @c              ATTRIBUTES       [Normally only in Sections 2, 3]
  32 @c              CONFORMING TO
  33 @c              NOTES
  34 @c              BUGS
  35 @c              EXAMPLES
  36 @c              AUTHORS          [Discouraged]
  37 @c              REPORTING BUGS   [Not used in man-pages]
  38 @c              COPYRIGHT        [Not used in man-pages]
  39 @c              SEE ALSO
  40 @c
  41 @c This is what the texi2pod.pl tool recognizes:
  42 @c
  43 @c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
  44 @c               BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
  45 @c
  46 @c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
  47 @c makes sense and adhered to for the other formats.
  48 @c ----------------------------------------------------------------------------
  49
  50 @c ----------------------------------------------------------------------------
  51 @c NAME section
  52 @c ----------------------------------------------------------------------------
  53
  54 @ManPageStart{NAME}
  55 @c man begin NAME
  56
  57 gp-archive - Archive the associated application binaries and sources for a
  58 gprofng experiment
  59
  60 @c man end
  61 @ManPageEnd{}
  62
  63 @c ----------------------------------------------------------------------------
  64 @c SYNOPSIS section
  65 @c ----------------------------------------------------------------------------
  66
  67 @ManPageStart{SYNOPSIS}
  68 @c man begin SYNOPSIS
  69
  70 @command{gprofng archive} [@var{option(s)}] @var{experiment}
  71
  72 @c man end
  73 @ManPageEnd{}
  74
  75 @c ----------------------------------------------------------------------------
  76 @c DESCRIPTION section
  77 @c ----------------------------------------------------------------------------
  78
  79 @ManPageStart{DESCRIPTION}
  80 @c man begin DESCRIPTION
  81
  82 Archive the associated application binaries and source files in a gprofng
  83 experiment to make it self contained and portable.
  84
  85 By default, the binaries are archived as part of the data collection, but the
  86 application source files are not archived.  Use this tool to change this and
  87 afterwards archive additional components.
  88
  89 This tool has to be executed on the same system where the profiling data was
  90 recorded.
  91
  92 @c man end
  93 @ManPageEnd{}
  94
  95 @c ----------------------------------------------------------------------------
  96 @c OPTIONS section
  97 @c ----------------------------------------------------------------------------
  98
  99 @ManPageStart{OPTIONS}
 100 @c man begin OPTIONS
 101
 102 @table @gcctabopt
 103
 104 @item --version
 105 @ifclear man
 106 @IndexSubentry{Options, @code{--version}}
 107 @end ifclear
 108
 109 Print the version number and exit.
 110
 111 @item --help
 112 @ifclear man
 113 @IndexSubentry{Options, @code{--help}}
 114 @end ifclear
 115
 116 Print usage information and exit.
 117
 118 @item -a @{off | on | ldobjects | src | usedldobjects | used[src]@}
 119 @ifclear man
 120 @IndexSubentry{Options, @code{-a}}
 121 @end ifclear
 122
 123 Specify archiving of binaries and other files.  In addition to disable this
 124 feature (@samp{off}), or enable archiving of all loadobjects and sources
 125 (@samp{on}), the other choices support a more refined selection.
 126
 127 All of these choices enable archiving, but the keyword controls what exactly
 128 is selected: all load objects (@samp{ldobjects}), all source files
 129 (@samp{src}), the loadobjects associated with a program counter
 130 (@samp{usedldobjects}), or the source files associated with a program counter
 131 (@samp{used[src]}).  The default is @samp{-a ldobjects}.
 132
 133 @item -d @var{path}
 134 @ifclear man
 135 @IndexSubentry{Options, @code{-d}}
 136 @end ifclear
 137
 138 The @var{path} is the absolute path to a common archive, which is a
 139 directory that contains archived files.  If the directory does not
 140 exist, then it will be created.  Files are saved in the common archive
 141 directory, and a symbolic link is created in the experiment archive.
 142
 143 @item -F
 144 @ifclear man
 145 @IndexSubentry{Options, @code{-F}}
 146 @end ifclear
 147
 148 Force writing, or rewriting of .archive files.  All archived files will be
 149 removed and recreated, except if the @samp{-n} or @samp{-m} option is used,
 150 or if the experiment is a subexperiment.
 151
 152 @item -m @var{regex}
 153 @ifclear man
 154 @IndexSubentry{Options, @code{-m}}
 155 @end ifclear
 156
 157 Archive only those source, object, and debug info files whose full path name
 158 matches the given POSIX compliant @var{regex} regular expression.
 159
 160 @item -n
 161 @ifclear man
 162 @IndexSubentry{Options, @code{-n}}
 163 @end ifclear
 164
 165 Archive the named experiment only, not any of its descendants.
 166
 167 @item -q
 168 @ifclear man
 169 @IndexSubentry{Options, @code{-q}}
 170 @end ifclear
 171
 172 Do not write any warnings to @file{stderr}.  Warnings are incorporated into
 173 the .archive file in the experiment directory.  They are shown in the output
 174 of the @command{gprofng display text} command.
 175
 176 @item -r @var{path}
 177 @ifclear man
 178 @IndexSubentry{Options, @code{-r}}
 179 @end ifclear
 180
 181 This option specifies the location of a common archive.  The value is the
 182 relative path to a common archive, which is a directory that contains
 183 archived files.
 184 If the directory does not exist, then it will be created.  Files are saved
 185 in the common archive directory, and a symbolic link is created in the
 186 experiment archive.
 187
 188 @item -s @var{selection}
 189 @ifclear man
 190 @IndexSubentry{Options, @code{-s}}
 191 @end ifclear
 192
 193 Specify archiving of source files.  The allowed values for @var{selection} are:
 194
 195 @table @gcctabopt
 196
 197 @item no
 198
 199 Do not archive any source files.
 200
 201 @item all
 202
 203 Archive all source and object files that can be found.
 204
 205 @item used[src]
 206
 207 Archive source and object files for functions against which data was
 208 recorded in the experiment, and that can be found.
 209 @end table
 210
 211 By default, application source files are not archived into the experiment.
 212 If the @samp{-s all}, or @samp{-s used} option is used, sources and object
 213 files are archived.
 214 These options also ensure that source files are available in the experiment,
 215 even if the original source files have been modified, or are inaccessible
 216 afterwards.
 217
 218 In case archive files cannot be found, use the @samp{addpath}, or
 219 @samp{pathmap} command, or both, in an @file{.er.rc} file to specify the
 220 location of the missing file(s).
 221
 222 @end table
 223
 224 @c man end
 225 @ManPageEnd{}
 226
 227 @c ----------------------------------------------------------------------------
 228 @c NOTES section
 229 @c ----------------------------------------------------------------------------
 230
 231 @ManPageStart{NOTES}
 232 @c man begin NOTES
 233
 234 @itemize @minus
 235
 236 @c ----------------------------------------------------------------------------
 237 @item
 238 Archiving of application binaries -
 239 By default, binaries are archived automatically when an experiment is
 240 created.  However, archiving does not occur in one or more of the
 241 following circumstances:
 242
 243 @itemize @bullet
 244
 245 @item
 246 If the profiled application is terminated before it exits normally.
 247
 248 @item
 249 If a running process is profiled.
 250
 251 @item
 252 If archiving is explicitly disabled when profiling.  For example by using
 253 the @samp{-a off} option on @command{gprofng collect app}.
 254
 255 @end itemize
 256
 257 In these cases, @command{gprofng archive} must be run manually and on the same
 258 machine where the profiling data was recorded.
 259
 260 Archiving of experiment data during the data collection process can be quite
 261 expensive.  Especially if the experiment has many descendant processes.
 262 @ifclear man
 263 @IndexSubentry{Options, @code{-a}}
 264 @end ifclear
 265 In such cases, a more efficient strategy is to use the @samp{-a off} option
 266 when collecting the data.  Once the collection has completed, the data can be
 267 @ifclear man
 268 @IndexSubentry{Options, @code{-s}}
 269 @end ifclear
 270 archived using the @samp{-s all} option.  This saves all executables and
 271 source files in the experiment.
 272
 273 If during the archiving there is an error message that an executable, or
 274 @ifclear man
 275 @IndexSubentry{Commands, @code{addpath}}
 276 @end ifclear
 277 source file cannot be found, the @samp{addpath} command to add the path
 278 to the missing file(s) can be included in the @file{.er.rc} file.
 279 After this command has been added, archive the experiment again.  The
 280 archiving archiving can be repeated as many times as necessary to archive all
 281 files.
 282
 283 Archiving should be done on the same system as was used to collect the
 284 experiment.  If some files cannot be accessed from this system (e.g.  sources
 285 or object files), then additional archiving can be done using another system
 286 that can access them.  For example, the system where the application was built.
 287
 288 Some Java applications store shared objects in jar files.  By default, such
 289 shared objects are not automatically archived.  To archive shared objects
 290 contained in jar files, make sure to include the @samp{addpath} command in
 291 an @file{.er.rc} file.
 292 The @samp{addpath} command should give the path to the jar file, including
 293 the jar file itself.  The @file{.er.rc} file should be saved in the user home
 294 directory, or experiment parent directory.
 295
 296 @item
 297 Archiving of application sources -
 298 By default, application source files are not archived in the experiment.
 299 Execute the @command{gprofng archive} command with the @samp{-s all}, or
 300 @samp{-s used} option on each experiment to store source files in the
 301 experiment.
 302
 303 @item
 304 Automatic archiving of application sources -
 305 Environment variable @samp{GPROFNG_ARCHIVE} may be set to automatically
 306 archive sources when the experiment has completed.  This environment
 307 variable can contain @samp{-s} and @samp{-m} arguments, as pairs of
 308 argument and options, separated by one or more blanks.
 309 @ifclear man
 310 @IndexSubentry{Environment variables, @code{GPROFNG_ARCHIVE}}
 311 @IndexSubentry{Options, @code{-a}}
 312 @IndexSubentry{Options, @code{-m}}
 313 @IndexSubentry{Options, @code{-s}}
 314 @end ifclear
 315
 316 If more than one @samp{-s} argument appears on the command line, the
 317 last one prevails.  If @samp{-s} is both passed on the command line, and
 318 set by the environment variable, the option from the environment variable
 319 prevails.
 320
 321 Note that in case automatic source archiving during data collection has
 322 been enabled using either the @samp{GPROFNG_ARCHIVE} variable, or the
 323 @samp{-a src}, or @samp{-a usedsrc} option, it is recommended to confirm that
 324 source files have been correctly resolved by executing the
 325 @command{gprofng archive -s all}, or @command{gprofng archive -s used}
 326 command.
 327
 328 @item
 329 The @samp{-d} and @samp{-r} options are mutually exclusive.
 330 @ifclear man
 331 @IndexSubentry{Options, @code{-d}}
 332 @IndexSubentry{Options, @code{-r}}
 333 @end ifclear
 334
 335 @item
 336 When using the @samp{-d} or @samp{-r} option, environment variable
 337 @ifclear man
 338 @IndexSubentry{Options, @code{-d}}
 339 @IndexSubentry{Options, @code{-r}}
 340 @IndexSubentry{Environment variables, @code{GPROFNG_ARCHIVE_COMMON_DIR}}
 341 @end ifclear
 342 @samp{GPROFNG_ARCHIVE_COMMON_DIR} can be used to specify the location of
 343 the common archive.  This can be very convenient when using a script to
 344 profile applications.
 345
 346 @item
 347 If more than one @samp{-s} option is given on the command line, or
 348 specified in the environment variable, the specified option for all must
 349 be the same.  If not, @command{gprofng archive} exits with an error.
 350
 351 @item
 352 This tool does not work on experiments recorded with earlier versions of
 353 the tools.  If invoked on such experiments, a warning is printed.  Use the
 354 version of @command{gprofng archive} from the same release with which the
 355 experiment was recorded.
 356
 357 @end itemize
 358
 359 @c man end
 360 @ManPageEnd{}
 361
 362 @c ----------------------------------------------------------------------------
 363 @c SEEALSO section
 364 @c ----------------------------------------------------------------------------
 365
 366 @ManPageStart{SEE ALSO}
 367 @c man begin SEEALSO
 368
 369 gprofng(1),
 370 gp-collect-app(1),
 371 gp-display-gui(1),
 372 gp-display-html(1),
 373 gp-display-src(1),
 374 gp-display-text(1)
 375
 376 @iftex
 377 @vspace{1}
 378 @end iftex
 379
 380 The user guide for gprofng is maintained as a Texinfo manual.  If the info
 381 and gprofng programs are correctly installed, the command
 382 @command{info gprofng} should give access to this document.
 383
 384 @c man end
 385 @ManPageEnd{}
 386
 387 @c ----------------------------------------------------------------------------
 388 @c COPYRIGHT section
 389 @c ----------------------------------------------------------------------------
 390
 391 @ManPageStart{COPYRIGHT}
 392 @c man begin COPYRIGHT
 393
 394 Copyright @copyright{} 2022-2024 Free Software Foundation, Inc.
 395
 396 Permission is granted to copy, distribute and/or modify this document
 397 under the terms of the GNU Free Documentation License, Version 1.3
 398 or any later version published by the Free Software Foundation;
 399 with no Invariant Sections, with no Front-Cover Texts, and with no
 400 Back-Cover Texts.  A copy of the license is included in the
 401 section entitled ``GNU Free Documentation License''.
 402
 403 @c man end
 404 @ManPageEnd{}
 405
 406 @c ----------------------------------------------------------------------------
 407 @c If this text is used for a man page, exit.  Otherwise we need to continue.
 408 @c ----------------------------------------------------------------------------
 409
 410 @ifset man
 411 @bye
 412 @end ifset