GCOV-TOOL(1)

📦
version 12-20220222 · 4 versions
, in ubuntu jammy

🎀 gcov-tool 🎀

Okay bestie, welcome to the GCOV-TOOL(1) manual page (GNU, for the nerds 🤓). Let's get into it! 💅

✨ NAME ✨

gcov-tool is an offline gcda profile processing tool 🧚. It works on gcc's gcda profile files without the program needing to be running. Iconic, right? 😭

🦋 SYNOPSIS 🦋

Here are all the ways you can call it. Literally every combo, no cap 💀

gcov-tool [-v|--version] [-h|--help]

gcov-tool merge [merge-options] directory1 directory2
     [-o|--output directory]
     [-v|--verbose]
     [-w|--weight w1,w2]

gcov-tool rewrite [rewrite-options] directory
     [-n|--normalize long_long_value]
     [-o|--output directory]
     [-s|--scale float_or_simple-frac_value]
     [-v|--verbose]

gcov-tool overlap [overlap-options] directory1 directory2
     [-f|--function]
     [-F|--fullname]
     [-h|--hotonly]
     [-o|--object]
     [-t|--hot_threshold] float
     [-v|--verbose]

💖 DESCRIPTION 💖

Okay so gcov-tool is an offline tool for processing gcc's gcda profile files, and it is giving main character energy 👑. Right now it can do two big things:

  • Merge two sets of profiles, with weights 💜
  • Rewrite one set of profile data. You can scale or normalize the count values 🍓

Here's when you'd actually use this, bestie 🫶:

  • Say you collected profiles for different sets of inputs. You can merge them with this tool, and you can set a weight to show how important each input is to you ✨
  • You can rewrite a profile after removing some of the gcda files, and it keeps the summary and the histogram consistent 🌸
  • It can also help you debug or libgcov code, because it shares most of its code with the runtime library 🔥
Heads up, babe: an offline merge might give you slightly different values than an online merged profile. Here's the tea on the typical differences 🙈
  • Histogram difference: This offline tool recomputes the histogram after merging the counters, so the result is precise. Online merging can't do that. It merges two histograms together, so the result is only an approximation 😭
  • Summary checksum difference: The summary checksum uses a CRC32 operation. Its value depends on the link list order of the gcov-info objects. gcov-tool uses a different order than the online merge, so you'll see different summary checksums, and that's expected 🦋. It doesn't really matter though, because the compiler never uses this checksum anywhere 💅
  • Value profile counter values difference: Some value profile counters depend on runtime stuff, like heap addresses. Seeing differences in these counters is totally normal 🌈

🌟 OPTIONS 🌟

Here's everything you can pass in, grouped by vibe 💖

🎀 Global options

  • -h, --help — Shows help about using gcov-tool on the standard output, then exits without doing any further processing 🧚
  • -v, --version — Shows the gcov-tool version number on the standard output, then exits without doing any further processing ✨

🔀 merge

Merges two profile directories 💜

  • -o directory, --output directory — Sets the output profile directory. If you don't set one, it defaults to merged_profile 🍓
  • -v, --verbose — Turns on verbose mode, so you get extra info 📣
  • -w w1,w2, --weight w1,w2 — Sets the merge weights for directory1 and directory2, in that order. Both weights default to 1 🫶

🔁 rewrite

Reads the profile directory you give it and rewrites everything into a new directory 🦋

  • -n long_long_value, --normalize <long_long_value> — Normalizes the profile. The value you pass is the max counter value in the new profile 💅
  • -o directory, --output directory — Sets the output profile directory. If you don't set one, the default output name is rewrite_profile 🌸
  • -s float_or_simple-frac_value, --scale float_or_simple-frac_value — Scales the profile counters. You can use a floating point value or a simple fraction, like 1, 2, 2/3, and 5/3 🔥
  • -v, --verbose — Turns on verbose mode 🌈

🔍 overlap

Computes the overlap score between the two profile directories you specify. The score is based on the arc profiles, and it's defined as the sum of min (p1_counter[i] / p1_sum_all, p2_counter[i] / p2_sum_all) for all arc counters i. Here, p1_counter[i] and p2_counter[i] are the two matched counters, and p1_sum_all and p2_sum_all are the sums of counter values in profile 1 and profile 2, respectively 🧮✨

  • -f, --function — Prints the function-level overlap score 💜
  • -F, --fullname — Prints the full gcda filename 🎀
  • -h, --hotonly — Only prints info for hot objects and functions 🔥
  • -o, --object — Prints the object-level overlap score 🦋
  • -t float, --hot_threshold <float> — Sets the threshold for a hot counter value 👑
  • -v, --verbose — Turns on verbose mode 📣

🔗 SEE ALSO 🔗

Go check these out for more tea 🍵: gpl(7), gfdl(7), fsf-funding(7), gcc(1), gcov(1), and the Info entry for gcc 📚

Copyright (c) 2014-2022 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. The Invariant Sections are "GNU General Public License" and "Funding Free Software". The Front-Cover Texts are (a) (see below), and the Back-Cover Texts are (b) (see below). A copy of the license is included in the gfdl(7) man page 🫶

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.

Okay bestie, that's the whole page, and you're officially gcov-tool literate now 🎀💖 This version came from gcc-12, dated 2022-02-22, and I'm obsessed. Stay iconic! 🦋✨

📦 where this page comes from