path: root/upstream/archlinux/man1/gp-archive.1

.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "GP-ARCHIVE.1 1"
.TH GP-ARCHIVE.1 1 2024-02-01 binutils-2.42 "User Commands"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
gp\-archive \- Archive gprofng experiment data
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\&\fBgprofng archive\fR [\fIoption(s)\fR] \fIexperiment\fR
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Archive the associated application binaries and source files in a gprofng
experiment to make it self contained and portable.
.PP
By default, the binaries are archived as part of the data collection, but the
application source files are not archived.  Use this tool to change this and
afterwards archive additional components.
.PP
This tool has to be executed on the same system where the profiling data was
recorded.
.SH OPTIONS
.IX Header "OPTIONS"
.IP \fB\-\-version\fR 4
.IX Item "--version"
Print the version number and exit.
.IP \fB\-\-help\fR 4
.IX Item "--help"
Print usage information and exit.
.IP "\fB\-a {off | on | ldobjects | src | usedldobjects | used[src]}\fR" 4
.IX Item "-a {off | on | ldobjects | src | usedldobjects | used[src]}"
Specify archiving of binaries and other files.  In addition to disable this
feature (\fBoff\fR), or enable archiving of all loadobjects and sources
(\fBon\fR), the other choices support a more refined selection.
.Sp
All of these choices enable archiving, but the keyword controls what exactly
is selected: all load objects (\fBldobjects\fR), all source files
(\fBsrc\fR), the loadobjects associated with a program counter
(\fBusedldobjects\fR), or the source files associated with a program counter
(\fBused[src]\fR).  The default is \fB\-a ldobjects\fR.
.IP "\fB\-d\fR \fIpath\fR" 4
.IX Item "-d path"
The \fIpath\fR is the absolute path to a common archive, which is a
directory that contains archived files.  If the directory does not
exist, then it will be created.  Files are saved in the common archive
directory, and a symbolic link is created in the experiment archive.
.IP \fB\-F\fR 4
.IX Item "-F"
Force writing, or rewriting of .archive files.  All archived files will be
removed and recreated, except if the \fB\-n\fR or \fB\-m\fR option is used,
or if the experiment is a subexperiment.
.IP "\fB\-m\fR \fIregex\fR" 4
.IX Item "-m regex"
Archive only those source, object, and debug info files whose full path name
matches the given POSIX compliant \fIregex\fR regular expression.
.IP \fB\-n\fR 4
.IX Item "-n"
Archive the named experiment only, not any of its descendants.
.IP \fB\-q\fR 4
.IX Item "-q"
Do not write any warnings to \fIstderr\fR.  Warnings are incorporated into
the .archive file in the experiment directory.  They are shown in the output
of the \fBgprofng display text\fR command.
.IP "\fB\-r\fR \fIpath\fR" 4
.IX Item "-r path"
This option specifies the location of a common archive.  The value is the
relative path to a common archive, which is a directory that contains
archived files.
If the directory does not exist, then it will be created.  Files are saved
in the common archive directory, and a symbolic link is created in the
experiment archive.
.IP "\fB\-s\fR \fIselection\fR" 4
.IX Item "-s selection"
Specify archiving of source files.  The allowed values for \fIselection\fR are:
.RS 4
.IP \fBno\fR 4
.IX Item "no"
Do not archive any source files.
.IP \fBall\fR 4
.IX Item "all"
Archive all source and object files that can be found.
.IP \fBused[src]\fR 4
.IX Item "used[src]"
Archive source and object files for functions against which data was
recorded in the experiment, and that can be found.
.RE
.RS 4
.Sp
By default, application source files are not archived into the experiment.
If the \fB\-s all\fR, or \fB\-s used\fR option is used, sources and object
files are archived.
These options also ensure that source files are available in the experiment,
even if the original source files have been modified, or are inaccessible
afterwards.
.Sp
In case archive files cannot be found, use the \fBaddpath\fR, or
\&\fBpathmap\fR command, or both, in an \fI.er.rc\fR file to specify the
location of the missing file(s).
.RE
.SH NOTES
.IX Header "NOTES"
.IP \- 4
Archiving of application binaries \-
By default, binaries are archived automatically when an experiment is
created.  However, archiving does not occur in one or more of the
following circumstances:
.RS 4
.IP \(bu 4
If the profiled application is terminated before it exits normally.
.IP \(bu 4
If a running process is profiled.
.IP \(bu 4
If archiving is explicitly disabled when profiling.  For example by using
the \fB\-a off\fR option on \fBgprofng collect app\fR.
.RE
.RS 4
.Sp
In these cases, \fBgprofng archive\fR must be run manually and on the same
machine where the profiling data was recorded.
.Sp
Archiving of experiment data during the data collection process can be quite
expensive.  Especially if the experiment has many descendant processes.
In such cases, a more efficient strategy is to use the \fB\-a off\fR option
when collecting the data.  Once the collection has completed, the data can be
archived using the \fB\-s all\fR option.  This saves all executables and
source files in the experiment.
.Sp
If during the archiving there is an error message that an executable, or
source file cannot be found, the \fBaddpath\fR command to add the path
to the missing file(s) can be included in the \fI.er.rc\fR file.
After this command has been added, archive the experiment again.  The
archiving archiving can be repeated as many times as necessary to archive all
files.
.Sp
Archiving should be done on the same system as was used to collect the
experiment.  If some files cannot be accessed from this system (e.g.  sources
or object files), then additional archiving can be done using another system
that can access them.  For example, the system where the application was built.
.Sp
Some Java applications store shared objects in jar files.  By default, such
shared objects are not automatically archived.  To archive shared objects
contained in jar files, make sure to include the \fBaddpath\fR command in
an \fI.er.rc\fR file.
The \fBaddpath\fR command should give the path to the jar file, including
the jar file itself.  The \fI.er.rc\fR file should be saved in the user home
directory, or experiment parent directory.
.RE
.IP \- 4
Archiving of application sources \-
By default, application source files are not archived in the experiment.
Execute the \fBgprofng archive\fR command with the \fB\-s all\fR, or
\&\fB\-s used\fR option on each experiment to store source files in the
experiment.
.IP \- 4
Automatic archiving of application sources \-
Environment variable \fBGPROFNG_ARCHIVE\fR may be set to automatically
archive sources when the experiment has completed.  This environment
variable can contain \fB\-s\fR and \fB\-m\fR arguments, as pairs of
argument and options, separated by one or more blanks.
.Sp
If more than one \fB\-s\fR argument appears on the command line, the
last one prevails.  If \fB\-s\fR is both passed on the command line, and
set by the environment variable, the option from the environment variable
prevails.
.Sp
Note that in case automatic source archiving during data collection has
been enabled using either the \fBGPROFNG_ARCHIVE\fR variable, or the
\&\fB\-a src\fR, or \fB\-a usedsrc\fR option, it is recommended to confirm that
source files have been correctly resolved by executing the
\&\fBgprofng archive \-s all\fR, or \fBgprofng archive \-s used\fR
command.
.IP \- 4
The \fB\-d\fR and \fB\-r\fR options are mutually exclusive.
.IP \- 4
When using the \fB\-d\fR or \fB\-r\fR option, environment variable
\&\fBGPROFNG_ARCHIVE_COMMON_DIR\fR can be used to specify the location of
the common archive.  This can be very convenient when using a script to
profile applications.
.IP \- 4
If more than one \fB\-s\fR option is given on the command line, or
specified in the environment variable, the specified option for all must
be the same.  If not, \fBgprofng archive\fR exits with an error.
.IP \- 4
This tool does not work on experiments recorded with earlier versions of
the tools.  If invoked on such experiments, a warning is printed.  Use the
version of \fBgprofng archive\fR from the same release with which the
experiment was recorded.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBgprofng\fR\|(1),
\&\fBgp\-collect\-app\fR\|(1),
\&\fBgp\-display\-gui\fR\|(1),
\&\fBgp\-display\-html\fR\|(1),
\&\fBgp\-display\-src\fR\|(1),
\&\fBgp\-display\-text\fR\|(1)
.PP
The user guide for gprofng is maintained as a Texinfo manual.  If the info
and gprofng programs are correctly installed, the command
\&\fBinfo gprofng\fR should give access to this document.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 2022\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts.  A copy of the license is included in the
section entitled "GNU Free Documentation License".