gprofng/doc/gp-archive.texi

   1 @c ----------------------------------------------------------------------------
   2 @c This is the Texinfo source file for the gp-collect-app man page.
   3 @c
   4 @c Author: Ruud van der Pas
   5 @c ----------------------------------------------------------------------------
   6 @ifset man
   7 \input texinfo @c -*-texinfo-*-
   8 @setfilename gprofng 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 gprofng archive - Archive gprofng experiment data
  58
  59 @c man end
  60 @ManPageEnd{}
  61
  62 @c ----------------------------------------------------------------------------
  63 @c SYNOPSIS section
  64 @c ----------------------------------------------------------------------------
  65
  66 @ManPageStart{SYNOPSIS}
  67 @c man begin SYNOPSIS
  68
  69 @command{gprofng archive} [@var{option(s)}] @var{experiment}
  70
  71 @c man end
  72 @ManPageEnd{}
  73
  74 @c ----------------------------------------------------------------------------
  75 @c DESCRIPTION section
  76 @c ----------------------------------------------------------------------------
  77
  78 @ManPageStart{DESCRIPTION}
  79 @c man begin DESCRIPTION
  80
  81 Archive the associated application binaries and source files in a gprofng
  82 experiment to make it self contained and portable.
  83
  84 By default, the binaries are archived, but the application source files
  85 are not archived.  Use this tool to change this and afterwards archive
  86 additional components.
  87
  88 @c man end
  89 @ManPageEnd{}
  90
  91 @c ----------------------------------------------------------------------------
  92 @c OPTIONS section
  93 @c ----------------------------------------------------------------------------
  94
  95 @ManPageStart{OPTIONS}
  96 @c man begin OPTIONS
  97
  98 @table @gcctabopt
  99
 100 @item --version
 101 @ifclear man
 102 @IndexSubentry{Options, @code{--version}}
 103 @end ifclear
 104
 105 Print the version number and exit.
 106
 107 @item --help
 108 @ifclear man
 109 @IndexSubentry{Options, @code{--help}}
 110 @end ifclear
 111
 112 Print usage information and exit.
 113
 114 @c -- @item --verbose @{on|off@}
 115 @c -- @ifclear man
 116 @c -- @IndexSubentry{Options, @code{--verbose}}
 117 @c -- @end ifclear
 118
 119 @c -- Enable (on) or disable (off) verbose mode; the default is @samp{off}.
 120
 121 @item -a @{off|on|ldobjects|src|usedldobjects|usedsrc@}
 122 @ifclear man
 123 @IndexSubentry{Options, @code{-a}}
 124 @end ifclear
 125
 126 Specify archiving of binaries and other files.  In addition to disable this
 127 feature (off), or enable archiving off all loadobjects and sources (on),
 128 the  other  op tions support a more refined selection.
 129
 130 All of these options enable archiving, but the keyword controls what exactly
 131 is selected: all load objects (ldobjects), all source files (src), the
 132 loadobjects asscoiated with a program counter (usedldobjects), or the source
 133 files associated with a program counter (usedsrc).
 134 The default is @samp{-a ldobjects}.
 135
 136 @item -n
 137 @ifclear man
 138 @IndexSubentry{Options, @code{-n}}
 139 @end ifclear
 140
 141 Archive the named experiment only, not any of its descendants.
 142
 143 @item -m @var{regex}
 144 @ifclear man
 145 @IndexSubentry{Options, @code{-m}}
 146 @end ifclear
 147
 148 Archive only those source, object, and debug info files whose full path name
 149 matches the given POSIX compliant @var{regex} regular expression.
 150
 151 @item -q
 152 @ifclear man
 153 @IndexSubentry{Options, @code{-q}}
 154 @end ifclear
 155
 156 Do not write any warnings to stderr.  Warnings are incorporated into the
 157 .archive file in the experiment directory.  They are shown in the output
 158 of @command{gprofng display text}.
 159
 160 @item -F
 161 @ifclear man
 162 @IndexSubentry{Options, @code{-F}}
 163 @end ifclear
 164
 165 Force writing or rewriting of the archive.  This is ignored with the
 166 @samp{-n} or @samp{-m} option, or if this is a subexperiment.
 167
 168 @item -d @var{path}
 169 @ifclear man
 170 @IndexSubentry{Options, @code{-d}}
 171 @end ifclear
 172
 173 The @var{path} is the absolute path path to a common archive, which is a
 174 directory that contains archived files.  If the directory does not
 175 exist, then it will be created.  Files are saved in the common archive
 176 directory, and a symbolic link is created in the experiment archive.
 177
 178 @end table
 179
 180 @c man end
 181 @ManPageEnd{}
 182
 183 @c ----------------------------------------------------------------------------
 184 @c NOTES section
 185 @c ----------------------------------------------------------------------------
 186
 187 @ManPageStart{NOTES}
 188 @c man begin NOTES
 189
 190 Default archiving does not occur in case the application profiled terminates
 191 prematurely, or if archiving is disabled when collecting the performance data.
 192 In such cases, this tool can be used to afterwards archive the information,
 193 but it has to be run on the same system where the profiling data was recorded.
 194
 195 Some Java applications store shared objects in jar files.  By default, such
 196 shared objects are not automatically archived.  To archive shared objects
 197 contained in jar files, the addpath directive in an .er.rc file. The addpath
 198 directive should give the path to the jar file, including the jar file itself.
 199 The .er.rc file should be saved in the user home directory or parent of the
 200 experiment directory.
 201
 202 @c man end
 203 @ManPageEnd{}
 204
 205 @c ----------------------------------------------------------------------------
 206 @c SEEALSO section
 207 @c ----------------------------------------------------------------------------
 208
 209 @ManPageStart{SEEALSO}
 210 @c man begin SEEALSO
 211
 212 gprofng(1), gp-collect-app(1), gp-display-html(1), gp-display-src(1), gp-display-text(1)
 213
 214 The user guide for gprofng is maintained as a Texinfo manual.  If the info
 215 and gprofng programs are correctly installed, the command
 216 @command{info gprofng} should give access to this document.
 217
 218 @c man end
 219 @ManPageEnd{}
 220
 221 @c ----------------------------------------------------------------------------
 222 @c COPYRIGHT section
 223 @c ----------------------------------------------------------------------------
 224
 225 @ManPageStart{COPYRIGHT}
 226 @c man begin COPYRIGHT
 227
 228 Copyright @copyright{} 2022-2023 Free Software Foundation, Inc.
 229
 230 Permission is granted to copy, distribute and/or modify this document
 231 under the terms of the GNU Free Documentation License, Version 1.3
 232 or any later version published by the Free Software Foundation;
 233 with no Invariant Sections, with no Front-Cover Texts, and with no
 234 Back-Cover Texts.  A copy of the license is included in the
 235 section entitled ``GNU Free Documentation License''.
 236
 237 @c man end
 238 @ManPageEnd{}
 239
 240 @c ----------------------------------------------------------------------------
 241 @c If this text is used for a man page, exit.  Otherwise we need to continue.
 242 @c ----------------------------------------------------------------------------
 243
 244 @ifset man
 245 @bye
 246 @end ifset