new repository

1 files changed, 14 insertions, 0 deletions

diff --git a/devdocs/gcc~13/gcov-and-optimization.html b/devdocs/gcc~13/gcov-and-optimization.html
new file mode 100644
index 00000000..13c3dcfd
--- /dev/null
+++ b/devdocs/gcc~13/gcov-and-optimization.html
@@ -0,0 +1,14 @@
+<div class="section-level-extent" id="Gcov-and-Optimization"> <div class="nav-panel"> <p> Next: <a href="gcov-data-files" accesskey="n" rel="next">Brief Description of <code class="command">gcov</code> Data Files</a>, Previous: <a href="invoking-gcov" accesskey="p" rel="prev">Invoking <code class="command">gcov</code></a>, Up: <a href="gcov" accesskey="u" rel="up"><code class="command">gcov</code>—a Test Coverage Program</a> [<a href="index#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="indices" title="Index" rel="index">Index</a>]</p> </div>  <h1 class="section" id="Using-gcov-with-GCC-Optimization"><span>10.3 Using gcov with GCC Optimization<a class="copiable-link" href="#Using-gcov-with-GCC-Optimization"> ¶</a></span></h1> <p>If you plan to use <code class="command">gcov</code> to help optimize your code, you must first compile your program with a special GCC option ‘<samp class="samp">--coverage</samp>’. Aside from that, you can use any other GCC options; but if you want to prove that every single line in your program was executed, you should not compile with optimization at the same time. On some machines the optimizer can eliminate some simple code lines by combining them with other lines. For example, code like this: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">if (a != b)
+  c = 1;
+else
+  c = 0;</pre>
+</div> <p>can be compiled into one instruction on some machines. In this case, there is no way for <code class="command">gcov</code> to calculate separate execution counts for each line because there isn’t separate code for each line. Hence the <code class="command">gcov</code> output looks like this if you compiled the program with optimization: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">100:   12:if (a != b)
+100:   13:  c = 1;
+100:   14:else
+100:   15:  c = 0;</pre>
+</div> <p>The output shows that this block of code, combined by optimization, executed 100 times. In one sense this result is correct, because there was only one instruction representing all four of these lines. However, the output does not indicate how many times the result was 0 and how many times the result was 1. </p> <p>Inlineable functions can create unexpected line counts. Line counts are shown for the source code of the inlineable function, but what is shown depends on where the function is inlined, or if it is not inlined at all. </p> <p>If the function is not inlined, the compiler must emit an out of line copy of the function, in any object file that needs it. If <samp class="file">fileA.o</samp> and <samp class="file">fileB.o</samp> both contain out of line bodies of a particular inlineable function, they will also both contain coverage counts for that function. When <samp class="file">fileA.o</samp> and <samp class="file">fileB.o</samp> are linked together, the linker will, on many systems, select one of those out of line bodies for all calls to that function, and remove or ignore the other. Unfortunately, it will not remove the coverage counters for the unused function body. Hence when instrumented, all but one use of that function will show zero counts. </p> <p>If the function is inlined in several places, the block structure in each location might not be the same. For instance, a condition might now be calculable at compile time in some instances. Because the coverage of all the uses of the inline function will be shown for the same source lines, the line counts themselves might seem inconsistent. </p> <p>Long-running applications can use the <code class="code">__gcov_reset</code> and <code class="code">__gcov_dump</code> facilities to restrict profile collection to the program region of interest. Calling <code class="code">__gcov_reset(void)</code> will clear all run-time profile counters to zero, and calling <code class="code">__gcov_dump(void)</code> will cause the profile information collected at that point to be dumped to <samp class="file">.gcda</samp> output files. Instrumented applications use a static destructor with priority 99 to invoke the <code class="code">__gcov_dump</code> function. Thus <code class="code">__gcov_dump</code> is executed after all user defined static destructors, as well as handlers registered with <code class="code">atexit</code>. </p> <p>If an executable loads a dynamic shared object via dlopen functionality, <samp class="option">-Wl,--dynamic-list-data</samp> is needed to dump all profile data. </p> <p>Profiling run-time library reports various errors related to profile manipulation and profile saving. Errors are printed into standard error output or ‘<samp class="samp">GCOV_ERROR_FILE</samp>’ file, if environment variable is used. In order to terminate immediately after an errors occurs set ‘<samp class="samp">GCOV_EXIT_AT_ERROR</samp>’ environment variable. That can help users to find profile clashing which leads to a misleading profile. </p> </div>  <div class="nav-panel"> <p> Next: <a href="gcov-data-files">Brief Description of <code class="command">gcov</code> Data Files</a>, Previous: <a href="invoking-gcov">Invoking <code class="command">gcov</code></a>, Up: <a href="gcov"><code class="command">gcov</code>—a Test Coverage Program</a> [<a href="index#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="indices" title="Index" rel="index">Index</a>]</p> </div><div class="_attribution">
+  <p class="_attribution-p">
+    &copy; Free Software Foundation<br>Licensed under the GNU Free Documentation License, Version 1.3.<br>
+    <a href="https://gcc.gnu.org/onlinedocs/gcc-13.1.0/gcc/Gcov-and-Optimization.html" class="_attribution-link">https://gcc.gnu.org/onlinedocs/gcc-13.1.0/gcc/Gcov-and-Optimization.html</a>
+  </p>
+</div>