GCOV-TOOL(1)

✨ GCOV-TOOL(1) ✨

Okay bestie, this is the manual page for gcov-tool, the GNU tool for poking at gcc's gcda profile files 🧚💖. It's a manual page, which means it's the official docs, so buckle up 💅.

🎀 NAME

gcov-tool is an offline gcda profile processing tool. It works on the files after the fact, no running program needed 🦋.

🌸 SYNOPSIS

Here's every way you can call it, 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 🔥. Right now it can do two main things:

• merge two sets of profiles, with weights ⚖️.
• read one set of profile and rewrite the profile contents. You can scale or normalize the count values 🍓.

The use cases are lowkey iconic 😭:

• Collect profiles for different sets of inputs and merge them together. You can set a weight to show how much each input matters ✨.
• Rewrite the profile after dropping a subset of the gcda files, while keeping the summary and the histogram consistent 🫶.
• It can also help you debug libgcov code, since the tool shares most of its code with the runtime library 🧚.

Heads up, bestie: an offline merge might not match the online merged profile exactly. Here are the usual suspects 👀:

• Histogram difference: The offline tool recalculates the histogram after merging the counters, so the result is precise 💅. Online merging doesn't have that power. It merges two histograms into one, and the result is just an approximation 🙈.
• Summary checksum difference: The summary checksum uses a CRC32 operation, and its value depends on the link list order of gcov-info objects. gcov-tool orders them differently than the online merge does, so you'll see different checksums. Honestly it doesn't really matter, because the compiler never uses this checksum anywhere 💀✨.
• Value profile counter difference: Some value profile counters depend on the runtime, like heap addresses. Seeing differences in these is totally normal 🌈.

🦋 OPTIONS

• -h, --help — Shows you the help text on stdout, then exits without doing anything else 🙋.
• -v, --version — Shows the gcov-tool version number on stdout, then exits without doing anything else 🔢.

🍓 merge

Merges two profile directories together 💖.

• -o directory, --output directory — Sets the output profile directory. If you don't pick one, it defaults to merged_profile 📁.
• -v, --verbose — Turns on verbose mode 📢.
• -w w1,w2, --weight w1,w2 — Sets the merge weights for directory1 and directory2, in that order. Both default to 1 ⚖️.

🌷 rewrite

Reads the profile directory you specify and rewrites it into a new one 🔁.

• -n long_long_value, --normalize <long_long_value> — Normalizes the profile. The number you give is the max counter value in the new profile 📏.
• -o directory, --output directory — Sets the output profile directory. If you don't pick 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

Check these out for more tea ☕: gpl(7), gfdl(7), fsf-funding(7), gcc(1), gcov(1), and the Info entry for gcc 📚.

🌈 COPYRIGHT

Copyright (c) 2014-2020 Free Software Foundation, Inc. 💜

You can 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 Text is (a) (see below), and the Back-Cover Text is (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.

---

Bestie, that's the whole page, and it's from gcc-10.5.0 dated 2023-07-07 💖✨ You're officially gcov-tool literate now 🫶💅