vasilito
ff4ff35918
Red Bear OS is a full fork. All sources must be available from git clone with zero network access. Removed gitignore rules that excluded fetched source trees under recipes/*/source/, local/recipes/kde/*/source/, local/recipes/qt/*/source/, and vendor source trees. Build artifacts (target/, build/, source.tar, *.o, *.so) remain excluded. 127291 files added — kernel, relibc, base, bootloader, pkgar, all KDE/Qt frameworks, mesa, wayland, DRM drivers, and every other recipe source.
267 lines
10 KiB
Groff
267 lines
10 KiB
Groff
.\" -*- mode: troff; coding: utf-8 -*-
|
|
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45)
|
|
.\"
|
|
.\" 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-08-17 binutils-2.43.0 "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".
|