GP-ARCHIVE.1(1)

📦
version 2.42 · 6 versions
, in ubuntu noble

💖 GP-ARCHIVE — the manual page, but make it make sense 💖

okay bestie, welcome to the gp-archive page from the User Commands section of the manual — she's here to help you archive your gprofng experiment data and honestly? she's iconic for it. let's get into it 🫶

✨ NAME ✨

gp-archive — Archive gprofng experiment data 💅

🎀 SYNOPSIS 🎀

gprofng archive [option(s)] experiment

🌸 DESCRIPTION 🌸

so basically: you take all the application binaries and source files that go with a gprofng experiment and you archive them right into the experiment itself, so the whole thing becomes self contained and portable. that's the whole vibe. it's giving "everything in one place, no cap" ✨

by default, the binaries get archived as part of the data collection — but the application source files do not get archived. so use this tool to change that, and afterwards to archive even more components. lowkey flexible. 🦋

⚠️ real talk: this tool has to be run on the same system where the profiling data was recorded. no exceptions, no shortcuts, periodt.

💅 OPTIONS 💅

  • --version — prints the version number and dips. bye! 👋
  • --help — prints the usage info and exits. classic.
  • -a {off | on | ldobjects | src | usedldobjects | used[src]} — tells it what to archive — binaries and other files. besides fully disabling the feature (off) or archiving literally everything, all loadobjects and sources (on), the other choices give you a more ✨refined✨ selection.

all of these choices turn archiving on, but the keyword decides what actually gets picked:

  • all load objects → ldobjects
  • all source files → src
  • the loadobjects tied to a program counter → usedldobjects
  • the source files tied to a program counter → used[src]

the default is -a ldobjects. 🎀

  • -d path — path is the absolute path to a common archive, which is a directory that holds archived files. if the directory doesn't exist, it gets created. files get saved in the common archive directory, and a symbolic link gets created in the experiment archive. cute little shortcut, honestly. 🔗
  • -F — force writing, or rewriting, of .archive files. every archived file gets removed and recreated — except if the -n or -m option is used, or if the experiment is a subexperiment. 💀
  • -m regex — archive only those source, object, and debug info files whose full path name matches the given POSIX compliant regex regular expression. filter queen. 🧚
  • -n — archive the named experiment only, not any of its descendants. minding your own business, love that for you. 🙈
  • -q — do not write any warnings to stderr. the warnings get incorporated into the .archive file in the experiment directory instead, and they show up in the output of the gprofng display text command. quiet but not forgotten. 🤫
  • -r path — this one sets 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 doesn't exist, it gets created. files get saved in the common archive directory, and a symbolic link gets created in the experiment archive. (yes, sibling energy with -d, but relative not absolute, iykyk 💜)
  • -s selection — specifies archiving of source files. the allowed values for selection are:
    • no — do not archive any source files. nope, none, zero. 🚫
    • all — archive all source and object files that can be found. everything. the whole wardrobe. 👑
    • used[src] — archive source and object files for functions against which data was recorded in the experiment, and that can be found. only the ones that actually showed up to the party. ✨

by default, application source files are not archived into the experiment. if you use -s all or -s used, sources and object files get archived. these options also make sure the source files are available in the experiment, even if the original source files have been modified, or are inaccessible afterwards. glow up + insurance policy 💚

if archive files can't be found, use the addpath or pathmap command, or both, in an .er.rc file to specify where the missing file(s) live. 🗺️

📝 NOTES 📝

  • Archiving of application binaries — by default, binaries are archived automatically when an experiment is created. but archiving does not happen in one or more of these situations:
    • if the profiled application is terminated before it exits normally. 😭
    • if a running process is profiled.
    • if archiving is explicitly disabled when profiling — for example, by using the -a off option on gprofng collect app.

in those cases, gprofng archive must be run manually, and on the same machine where the profiling data was recorded. no teleporting, bestie. 🛑

archiving of experiment data during the data collection process can be quite expensive — especially if the experiment has many descendant processes. in those cases, a more efficient strategy is to use the -a off option when collecting the data. once the collection is done, the data can be archived using the -s all option. this saves all executables and source files in the experiment. 🧠✨

if during the archiving there's an error message saying an executable or source file can't be found, the addpath command to add the path to the missing file(s) can be included in the .er.rc file. after that command has been added, archive the experiment again. the archiving can be repeated as many times as necessary to archive all files. (yes, the original says "the archiving archiving" — we're keeping that typo, she's part of the family now 💀)

archiving should be done on the same system that was used to collect the experiment. if some files can't 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. 🏗️

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 addpath command in an .er.rc file. the addpath command 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 the experiment parent directory. 🫙

  • Archiving of application sources — by default, application source files are not archived in the experiment. run the gprofng archive command with the -s all or -s used option on each experiment to store source files in the experiment. 📁
  • Automatic archiving of application sources — the environment variable GPROFNG_ARCHIVE may be set to automatically archive sources when the experiment has completed. this environment variable can contain -s and -m arguments, as pairs of argument and options, separated by one or more blanks. 🤖

if more than one -s argument appears on the command line, the last one prevails. if -s is both passed on the command line and set by the environment variable, the option from the environment variable prevails. environment variable stays winning, periodt. 👑

note that if automatic source archiving during data collection has been enabled using either the GPROFNG_ARCHIVE variable, or the -a src or -a usedsrc option, it's recommended to confirm that source files have been correctly resolved by executing the gprofng archive -s all or gprofng archive -s used command. ✅

  • the -d and -r options are mutually exclusive. pick a lane, babe. 🚦
  • when using the -d or -r option, the environment variable GPROFNG_ARCHIVE_COMMON_DIR can be used to specify the location of the common archive. this can be super convenient when using a script to profile applications. 🐚✨
  • if more than one -s option is given on the command line, or specified in the environment variable, the specified option for all must be the same. if not, gprofng archive exits with an error. 💀 consistency is key!
  • this tool does not work on experiments recorded with earlier versions of the tools. if you invoke it on such experiments, a warning is printed. use the version of gprofng archive from the same release with which the experiment was recorded. match made in heaven or nothing at all. 💔

👀 SEE ALSO 👀

the user guide for gprofng is maintained as a Texinfo manual. if the info and gprofng programs are correctly installed, the command info gprofng should give you access to this document. 📖💜

Copyright (c) 2022-2024 Free Software Foundation, Inc.

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".

and that's the whole page, bestie!! 🎀 this edition came from binutils-2.42, dated 2025-12-03, and it lives in the GP-ARCHIVE.1(1) corner of the manual. go archive something gorgeous 💖✨🦋🌸💅

📦 where this page comes from