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 57gp-archive - Archive the associated application binaries and sources for a 58gprofng 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 82Archive the associated application binaries and source files in a gprofng 83experiment to make it self contained and portable. 84 85By default, the binaries are archived as part of the data collection, but the 86application source files are not archived. Use this tool to change this and 87afterwards archive additional components. 88 89This tool has to be executed on the same system where the profiling data was 90recorded. 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 109Print the version number and exit. 110 111@item --help 112@ifclear man 113@IndexSubentry{Options, @code{--help}} 114@end ifclear 115 116Print 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 123Specify archiving of binaries and other files. In addition to disable this 124feature (@samp{off}), or enable archiving of all loadobjects and sources 125(@samp{on}), the other choices support a more refined selection. 126 127All of these choices enable archiving, but the keyword controls what exactly 128is 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 138The @var{path} is the absolute path to a common archive, which is a 139directory that contains archived files. If the directory does not 140exist, then it will be created. Files are saved in the common archive 141directory, 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 148Force writing, or rewriting of .archive files. All archived files will be 149removed and recreated, except if the @samp{-n} or @samp{-m} option is used, 150or if the experiment is a subexperiment. 151 152@item -m @var{regex} 153@ifclear man 154@IndexSubentry{Options, @code{-m}} 155@end ifclear 156 157Archive only those source, object, and debug info files whose full path name 158matches the given POSIX compliant @var{regex} regular expression. 159 160@item -n 161@ifclear man 162@IndexSubentry{Options, @code{-n}} 163@end ifclear 164 165Archive 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 172Do not write any warnings to @file{stderr}. Warnings are incorporated into 173the .archive file in the experiment directory. They are shown in the output 174of the @command{gprofng display text} command. 175 176@item -r @var{path} 177@ifclear man 178@IndexSubentry{Options, @code{-r}} 179@end ifclear 180 181This option specifies the location of a common archive. The value is the 182relative path to a common archive, which is a directory that contains 183archived files. 184If the directory does not exist, then it will be created. Files are saved 185in the common archive directory, and a symbolic link is created in the 186experiment archive. 187 188@item -s @var{selection} 189@ifclear man 190@IndexSubentry{Options, @code{-s}} 191@end ifclear 192 193Specify archiving of source files. The allowed values for @var{selection} are: 194 195@table @gcctabopt 196 197@item no 198 199Do not archive any source files. 200 201@item all 202 203Archive all source and object files that can be found. 204 205@item used[src] 206 207Archive source and object files for functions against which data was 208recorded in the experiment, and that can be found. 209@end table 210 211By default, application source files are not archived into the experiment. 212If the @samp{-s all}, or @samp{-s used} option is used, sources and object 213files are archived. 214These options also ensure that source files are available in the experiment, 215even if the original source files have been modified, or are inaccessible 216afterwards. 217 218In 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 220location 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 238Archiving of application binaries - 239By default, binaries are archived automatically when an experiment is 240created. However, archiving does not occur in one or more of the 241following circumstances: 242 243@itemize @bullet 244 245@item 246If the profiled application is terminated before it exits normally. 247 248@item 249If a running process is profiled. 250 251@item 252If archiving is explicitly disabled when profiling. For example by using 253the @samp{-a off} option on @command{gprofng collect app}. 254 255@end itemize 256 257In these cases, @command{gprofng archive} must be run manually and on the same 258machine where the profiling data was recorded. 259 260Archiving of experiment data during the data collection process can be quite 261expensive. Especially if the experiment has many descendant processes. 262@ifclear man 263@IndexSubentry{Options, @code{-a}} 264@end ifclear 265In such cases, a more efficient strategy is to use the @samp{-a off} option 266when collecting the data. Once the collection has completed, the data can be 267@ifclear man 268@IndexSubentry{Options, @code{-s}} 269@end ifclear 270archived using the @samp{-s all} option. This saves all executables and 271source files in the experiment. 272 273If during the archiving there is an error message that an executable, or 274@ifclear man 275@IndexSubentry{Commands, @code{addpath}} 276@end ifclear 277source file cannot be found, the @samp{addpath} command to add the path 278to the missing file(s) can be included in the @file{.er.rc} file. 279After this command has been added, archive the experiment again. The 280archiving archiving can be repeated as many times as necessary to archive all 281files. 282 283Archiving should be done on the same system as was used to collect the 284experiment. If some files cannot be accessed from this system (e.g. sources 285or object files), then additional archiving can be done using another system 286that can access them. For example, the system where the application was built. 287 288Some Java applications store shared objects in jar files. By default, such 289shared objects are not automatically archived. To archive shared objects 290contained in jar files, make sure to include the @samp{addpath} command in 291an @file{.er.rc} file. 292The @samp{addpath} command should give the path to the jar file, including 293the jar file itself. The @file{.er.rc} file should be saved in the user home 294directory, or experiment parent directory. 295 296@item 297Archiving of application sources - 298By default, application source files are not archived in the experiment. 299Execute 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 301experiment. 302 303@item 304Automatic archiving of application sources - 305Environment variable @samp{GPROFNG_ARCHIVE} may be set to automatically 306archive sources when the experiment has completed. This environment 307variable can contain @samp{-s} and @samp{-m} arguments, as pairs of 308argument 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 316If more than one @samp{-s} argument appears on the command line, the 317last one prevails. If @samp{-s} is both passed on the command line, and 318set by the environment variable, the option from the environment variable 319prevails. 320 321Note that in case automatic source archiving during data collection has 322been 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 324source files have been correctly resolved by executing the 325@command{gprofng archive -s all}, or @command{gprofng archive -s used} 326command. 327 328@item 329The @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 336When 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 343the common archive. This can be very convenient when using a script to 344profile applications. 345 346@item 347If more than one @samp{-s} option is given on the command line, or 348specified in the environment variable, the specified option for all must 349be the same. If not, @command{gprofng archive} exits with an error. 350 351@item 352This tool does not work on experiments recorded with earlier versions of 353the tools. If invoked on such experiments, a warning is printed. Use the 354version of @command{gprofng archive} from the same release with which the 355experiment 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 369gprofng(1), 370gp-collect-app(1), 371gp-display-gui(1), 372gp-display-html(1), 373gp-display-src(1), 374gp-display-text(1) 375 376@iftex 377@vspace{1} 378@end iftex 379 380The user guide for gprofng is maintained as a Texinfo manual. If the info 381and 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 394Copyright @copyright{} 2022-2024 Free Software Foundation, Inc. 395 396Permission is granted to copy, distribute and/or modify this document 397under the terms of the GNU Free Documentation License, Version 1.3 398or any later version published by the Free Software Foundation; 399with no Invariant Sections, with no Front-Cover Texts, and with no 400Back-Cover Texts. A copy of the license is included in the 401section 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 413