GCOV-TOOL(1)

💖 GCOV-TOOL 💖 — the offline gcda profile processing tool, bestie edition

okay so. you opened the manual for gcov-tool, which lives in section 1 of the GNU manuals. she's a command-line girlie and she is so useful, let me tell you everything 🫶

---

✨ NAME ✨

gcov-tool — offline gcda profile processing tool

---

🌸 SYNOPSIS 🌸

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 🦋

so gcov-tool is an offline tool that processes gcc's gcda profile files. no cap, that's the whole vibe.

rn, gcov-tool supports these functionalities, and honestly? she ate:

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

and here's when you'd actually reach for her, like the use cases:

• collect the profiles for different sets of inputs, then use this tool to merge them. you can specify the weight to factor in the relative importance of each input 👑
• rewrite the profile after removing a subset of the gcda files, while maintaining the consistency of the summary and the histogram.
• she can also be used to debug or libgcov code, because the tool shares the majority code as the runtime library. iykyk.

⚠️ heads up bestie: for the merging operation, this profile generated offline may contain slight different values from the online merged profile. here's the list of typical differences, no surprises allowed:

• histogram difference: this offline tool recomputes the histogram after merging the counters. the resulting histogram, therefore, is precise. the online merging does not have this capability — the histogram is merged from two histograms and the result is an approximation.
• summary checksum difference: summary checksum uses a CRC32 operation. the value depends on the link list order of gcov-info objects. this order is different in gcov-tool from that in the online merge. it's expected to have different summary checksums. it does not really matter as the compiler does not use this checksum anywhere 🙈
• value profile counter values difference: some counter values for value profile are runtime dependent, like heap addresses. it's normal to see some difference in these kind of counters.

---

💅 OPTIONS 💅

• -h, --help — display help about using gcov-tool (on the standard output), and exit without doing any further processing. bye bestie 👋
• -v, --version — display the gcov-tool version number (on the standard output), and exit without doing any further processing.

🌈 merge

merge two profile directories. iconic behaviour.

• -o directory, --output directory — set the output profile directory. default output directory name is merged_profile.
• -v, --verbose — set the verbose mode.
• -w w1,w2, --weight w1,w2 — set the merge weights of the directory1 and directory2, respectively. the default weights are 1 for both.

🌈 rewrite

read the specified profile directory and rewrite to a new directory. glow up arc ✨

• -n long_long_value, --normalize <long_long_value> — normalize the profile. the specified value is the max counter value in the new profile.
• -o directory, --output directory — set the output profile directory. default output name is rewrite_profile.
• -s float_or_simple-frac_value, --scale float_or_simple-frac_value — scale the profile counters. the specified value can be in floating point value, or simple fraction value form, such 1, 2, 2/3, and 5/3.
• -v, --verbose — set the verbose mode.

🌈 overlap

compute the overlap score between the two specified profile directories. the overlap score is computed based on the arc profiles. it is defined as the sum of min (p1_counter[i] / p1_sum_all, p2_counter[i] / p2_sum_all), for all arc counter i, where p1_counter[i] and p2_counter[i] are two matched counters and p1_sum_all and p2_sum_all are the sum of counter values in profile 1 and profile 2, respectively. math girlie rights 💜

• -f, --function — print function level overlap score.
• -F, --fullname — print full gcda filename.
• -h, --hotonly — only print info for hot objects/functions.
• -o, --object — print object level overlap score.
• -t float, --hot_threshold <float> — set the threshold for hot counter value.
• -v, --verbose — set the verbose mode.

---

🎀 SEE ALSO 🎀

gpl(7), gfdl(7), fsf-funding(7), gcc(1), gcov(1) and the Info entry for gcc.

---

👑 COPYRIGHT 👑

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; with the Invariant Sections being "GNU General Public License" and "Funding Free Software", the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (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 that's the whole page, you're fully caught up 💖 this one shipped as gcc-12.5.0, dated 2025-07-11, and honestly? she's giving main character energy. go merge something, bestie 🌸🦋✨