buildtools/binutils/gprofng/doc/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 2023-07-30 binutils-2.41 "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
gprofng 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, but the application source files
are not archived.  Use this tool to change this and afterwards archive
additional components.
.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|usedsrc}\fR" 4
.IX Item "-a {off|on|ldobjects|src|usedldobjects|usedsrc}"
Specify archiving of binaries and other files.  In addition to disable this
feature (off), or enable archiving off all loadobjects and sources (on),
the  other  op tions support a more refined selection.
.Sp
All of these options enable archiving, but the keyword controls what exactly
is selected: all load objects (ldobjects), all source files (src), the
loadobjects asscoiated with a program counter (usedldobjects), or the source
files associated with a program counter (usedsrc).
The default is \fB\-a ldobjects\fR.
.IP \fB\-n\fR 4
.IX Item "-n"
Archive the named experiment only, not any of its descendants.
.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\-q\fR 4
.IX Item "-q"
Do not write any warnings to stderr.  Warnings are incorporated into the
\&.archive file in the experiment directory.  They are shown in the output 
of \fBgprofng display text\fR.
.IP \fB\-F\fR 4
.IX Item "-F"
Force writing or rewriting of the archive.  This is ignored with the 
\&\fB\-n\fR or \fB\-m\fR option, or if this is a subexperiment.
.IP "\fB\-d\fR \fIpath\fR" 4
.IX Item "-d path"
The \fIpath\fR is the absolute path 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.
.SH NOTES
.IX Header "NOTES"
Default archiving does not occur in case the application profiled terminates
prematurely, or if archiving is disabled when collecting the performance data.
In such cases, this tool can be used to afterwards archive the information,
but it has to be run on the same system where the profiling data was recorded.
.PP
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, the addpath directive in an .er.rc file. The addpath
directive should give the path to the jar file, including the jar file itself.
The .er.rc file should be saved in the user home directory or parent of the
experiment directory.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBgprofng\fR\|(1), \fBgp\-collect\-app\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\-2023 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".