Merge and Rewrite Cross-Compiled gcda Profiles with gcov-tool

aarch64-linux-gnu-gcov-tool-13 merges two coverage profiles offline without touching either original directory. Allow about fifteen minutes if you already have matching .gcda files; you can also apply weights, rewrite counters into a fresh directory, and compare overlap.

This guide uses aarch64-linux-gnu-gcov-tool-13 from package gcc-13-aarch64-linux-gnu, version 13.3.0-6ubuntu2~24.04.1cross1. The unnumbered aarch64-linux-gnu-gcov-tool name points to the same GCC 13 tool on this machine. You need a shell, readable profile directories, and enough free space for each output directory. No example needs elevated privileges unless your profile files are not readable by your account.

1. Confirm the installed tool

Check the binary and version before interpreting its output. These are ordinary read-only commands:

$ command -v aarch64-linux-gnu-gcov-tool-13
/usr/bin/aarch64-linux-gnu-gcov-tool-13
$ aarch64-linux-gnu-gcov-tool-13 --version
aarch64-linux-gnu-gcov-tool-13 (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0

The command processes GCC coverage data files offline. It is not the compiler, and it does not run the instrumented program. The profile directories must contain compatible data produced by the relevant instrumented builds; a successful invocation is not proof that profiles from unrelated binaries are meaningful to combine.

For a quick syntax check, ask for help:

$ aarch64-linux-gnu-gcov-tool-13 --help

The installed manual documents four subcommands:

• merge: combine two profile directories.
• merge-stream: merge a gcfn/gcda data stream with profiles on disk.
• rewrite: scale or normalise counters into a new directory.
• overlap: compare two profile directories.

The examples below use explicit output paths so that the files created by the command are obvious.

2. Inspect the two input directories

Before merging, confirm that both paths exist and contain profile data. This does not alter them:

$ PROFILE_A=/path/to/profile-a
$ PROFILE_B=/path/to/profile-b
$ test -d "$PROFILE_A" && test -d "$PROFILE_B"
$ find "$PROFILE_A" "$PROFILE_B" -type f -name '*.gcda' -print

Replace the placeholder paths with real directories. Keep the build identity in mind: .gcda files are associated with the instrumented objects that created them. If one directory is empty, points at the wrong build, or contains files from a different executable, stop and resolve that first rather than relying on the tool to detect a semantic mismatch.

3. Merge two profiles into a new directory

Use merge with two input directories and an output directory that does not contain valuable data:

$ MERGED=/path/to/merged-profile
$ aarch64-linux-gnu-gcov-tool-13 merge "$PROFILE_A" "$PROFILE_B" \
    --output "$MERGED" \
    --verbose

Without --output, the documented default output name is merged_profile. The default weights are 1 for both inputs. Set them explicitly when one run represents more or less traffic:

$ WEIGHTED=/path/to/weighted-profile
$ aarch64-linux-gnu-gcov-tool-13 merge "$PROFILE_A" "$PROFILE_B" \
    --output "$WEIGHTED" \
    --weight 2,1

The first value weights PROFILE_A and the second weights PROFILE_B. These weights are profile-processing inputs, not a replacement for collecting representative test runs. Verify that the output was created and contains profile files:

$ find "$MERGED" -type f -name '*.gcda' -print

Offline merging can differ slightly from online runtime merging. The tool recomputes the histogram, while online merging combines histogram data approximately. Summary checksums can also differ because object ordering differs, and some value-profile counters are runtime-dependent. Do not reject a usable offline result merely because those fields are not byte-for-byte identical.

4. Rewrite counters without replacing the input

rewrite reads one profile directory and writes a new one. Scaling accepts a floating-point value or a simple fraction such as 2/3:

$ REWRITTEN=/path/to/rewrite-profile
$ aarch64-linux-gnu-gcov-tool-13 rewrite "$MERGED" \
    --scale 2/3 \
    --output "$REWRITTEN" \
    --verbose

Use --normalize VALUE instead when the new profile's maximum counter should be a specified integer:

$ NORMALISED=/path/to/normalised-profile
$ aarch64-linux-gnu-gcov-tool-13 rewrite "$MERGED" \
    --normalize 100000 \
    --output "$NORMALISED"

5. Measure profile overlap

Use overlap to compare two profile directories. It calculates a score from matched arc counters, using each profile's counter totals:

$ aarch64-linux-gnu-gcov-tool-13 overlap "$PROFILE_A" "$PROFILE_B" \
    --object \
    --fullname

--object prints object-level information and --function requests function-level information. Add --hotonly to restrict output to hot objects or functions, and use --hot_threshold FLOAT to set the hot-counter threshold. The command reports comparison data; it does not merge or rewrite either input.

There is no universal score that makes two profiles suitable for merging. Use the overlap result alongside the build identity, test workload, and the files present in each directory. If you need to see complete profile filenames, keep --fullname in the command rather than inferring paths from abbreviated output.

6. Handle streams and failures safely

merge-stream is for a gcfn and gcda data stream, often collected from a target without a normal filesystem. It reads from a named file or standard input and merges the stream with associated profiles in the host filesystem:

$ aarch64-linux-gnu-gcov-tool-13 merge-stream /path/to/profile-stream.bin \
    --weight 1,1 \
    --verbose

The installed manual points to __gcov_filename_to_gcfn() and __gcov_info_to_gcda() in gcov.h for generating that stream. Do not pass an arbitrary binary file and expect it to be recognised. If the file is omitted, the command reads standard input, so check pipelines carefully before sending a stream into it.

Capture the exit status immediately after a real operation:

$ aarch64-linux-gnu-gcov-tool-13 overlap "$PROFILE_A" "$PROFILE_B"
$ status=$?
$ printf 'gcov-tool status: %s\n' "$status"
gcov-tool status: 0

A non-zero status means the operation needs investigation. Check directory permissions, available space, profile compatibility, and whether an output path is writable. Avoid using sudo as a first response: it can hide ownership problems and does not make incompatible profile data valid.