]>
Commit | Line | Data |
---|---|---|
7a515757 | 1 | @c ---------------------------------------------------------------------------- |
46c56757 | 2 | @c This is the Texinfo source file for the gp-archive man page. |
7a515757 VM |
3 | @c |
4 | @c Author: Ruud van der Pas | |
5 | @c ---------------------------------------------------------------------------- | |
6 | @ifset man | |
7 | \input texinfo @c -*-texinfo-*- | |
46c56757 | 8 | @setfilename gp-archive |
7a515757 VM |
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 | ||
46c56757 VM |
57 | gp-archive - Archive the associated application binaries and sources for a |
58 | gprofng experiment | |
7a515757 VM |
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 | ||
46c56757 VM |
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. | |
7a515757 VM |
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 | ||
46c56757 | 118 | @item -a @{off | on | ldobjects | src | usedldobjects | used[src]@} |
7a515757 VM |
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 | |
46c56757 VM |
124 | feature (@samp{off}), or enable archiving of all loadobjects and sources |
125 | (@samp{on}), the other choices support a more refined selection. | |
7a515757 | 126 | |
46c56757 VM |
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}. | |
7a515757 | 132 | |
46c56757 | 133 | @item -d @var{path} |
7a515757 | 134 | @ifclear man |
46c56757 | 135 | @IndexSubentry{Options, @code{-d}} |
7a515757 VM |
136 | @end ifclear |
137 | ||
46c56757 VM |
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. | |
7a515757 VM |
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 | ||
46c56757 VM |
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 | ||
7a515757 VM |
167 | @item -q |
168 | @ifclear man | |
169 | @IndexSubentry{Options, @code{-q}} | |
170 | @end ifclear | |
171 | ||
46c56757 VM |
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. | |
7a515757 | 175 | |
46c56757 | 176 | @item -r @var{path} |
7a515757 | 177 | @ifclear man |
46c56757 | 178 | @IndexSubentry{Options, @code{-r}} |
7a515757 VM |
179 | @end ifclear |
180 | ||
46c56757 VM |
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. | |
7a515757 | 187 | |
46c56757 | 188 | @item -s @var{selection} |
7a515757 | 189 | @ifclear man |
46c56757 | 190 | @IndexSubentry{Options, @code{-s}} |
7a515757 VM |
191 | @end ifclear |
192 | ||
46c56757 VM |
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). | |
7a515757 VM |
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 | ||
46c56757 VM |
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. | |
7a515757 VM |
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 | |
46c56757 VM |
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 | |
7a515757 VM |
358 | |
359 | @c man end | |
360 | @ManPageEnd{} | |
361 | ||
362 | @c ---------------------------------------------------------------------------- | |
363 | @c SEEALSO section | |
364 | @c ---------------------------------------------------------------------------- | |
365 | ||
46c56757 | 366 | @ManPageStart{SEE ALSO} |
7a515757 VM |
367 | @c man begin SEEALSO |
368 | ||
46c56757 VM |
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 | |
7a515757 VM |
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 | ||
fd67aa11 | 394 | Copyright @copyright{} 2022-2024 Free Software Foundation, Inc. |
7a515757 VM |
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 |