===================================================================
@@ -1,5 +1,12 @@
2014-12-09 David Malcolm <dmalcolm@redhat.com>
+ PR jit/63854
+ * docs/internals/index.rst (Running under valgrind): New
+ subsection.
+ (docs/_build/texinfo/libgccjit.texi): Regenerate.
+
+2014-12-09 David Malcolm <dmalcolm@redhat.com>
+
PR jit/64206
* Make-lang.in (jit_OBJS): Add jit/jit-tempdir.o.
* jit-common.h (gcc::jit::tempdir): New forward decl.
===================================================================
@@ -118,6 +118,51 @@
gdb --args \
testsuite/jit/test-factorial.exe
+Running under valgrind
+**********************
+
+The jit testsuite detects if RUN_UNDER_VALGRIND is present in the
+environment (with any value). If it is present, it runs the test client
+code under `valgrind <http://valgrind.org>`_,
+specifcally, the default
+`memcheck <http://valgrind.org/docs/manual/mc-manual.html>`_
+tool with
+`--leak-check=full
+<http://valgrind.org/docs/manual/mc-manual.html#opt.leak-check>`_.
+
+It automatically parses the output from valgrind, injecting XFAIL results if
+any issues are found, or PASS results if the output is clean. The output
+is saved to ``TESTNAME.exe.valgrind.txt``.
+
+For example, the following invocation verbosely runs the testcase
+``test-sum-of-squares.c`` under valgrind, showing an issue:
+
+.. code-block:: console
+
+ $ RUN_UNDER_VALGRIND= \
+ make check-jit \
+ RUNTESTFLAGS="-v -v -v jit.exp=test-sum-of-squares.c"
+
+ (...verbose log contains detailed valgrind errors, if any...)
+
+ === jit Summary ===
+
+ # of expected passes 28
+ # of expected failures 2
+
+ $ less testsuite/jit/jit.sum
+ (...other results...)
+ XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.exe.valgrind.txt: definitely lost: 8 bytes in 1 blocks
+ XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.exe.valgrind.txt: unsuppressed errors: 1
+ (...other results...)
+
+ $ less testsuite/jit/test-sum-of-squares.exe.valgrind.txt
+ (...shows full valgrind report for this test case...)
+
+When running under valgrind, it's best to have configured gcc with
+:option:`--enable-valgrind-annotations`, which automatically suppresses
+various known false positives.
+
Environment variables
---------------------
When running client code against a locally-built libgccjit, three
===================================================================
@@ -197,6 +197,10 @@
* Environment variables::
* Overview of code structure::
+Running the test suite
+
+* Running under valgrind::
+
@end detailmenu
@end menu
@@ -6548,8 +6552,61 @@
@noindent
+@menu
+* Running under valgrind::
+
+@end menu
+
+@node Running under valgrind,,,Running the test suite
+@anchor{internals/index running-under-valgrind}@anchor{c9}
+@subsection Running under valgrind
+
+
+The jit testsuite detects if RUN_UNDER_VALGRIND is present in the
+environment (with any value). If it is present, it runs the test client
+code under valgrind@footnote{http://valgrind.org},
+specifcally, the default
+memcheck@footnote{http://valgrind.org/docs/manual/mc-manual.html}
+tool with
+--leak-check=full@footnote{http://valgrind.org/docs/manual/mc-manual.html#opt.leak-check}.
+
+It automatically parses the output from valgrind, injecting XFAIL results if
+any issues are found, or PASS results if the output is clean. The output
+is saved to @code{TESTNAME.exe.valgrind.txt}.
+
+For example, the following invocation verbosely runs the testcase
+@code{test-sum-of-squares.c} under valgrind, showing an issue:
+
+@example
+$ RUN_UNDER_VALGRIND= \
+ make check-jit \
+ RUNTESTFLAGS="-v -v -v jit.exp=test-sum-of-squares.c"
+
+(...verbose log contains detailed valgrind errors, if any...)
+
+ === jit Summary ===
+
+# of expected passes 28
+# of expected failures 2
+
+$ less testsuite/jit/jit.sum
+(...other results...)
+XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.exe.valgrind.txt: definitely lost: 8 bytes in 1 blocks
+XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.exe.valgrind.txt: unsuppressed errors: 1
+(...other results...)
+
+$ less testsuite/jit/test-sum-of-squares.exe.valgrind.txt
+(...shows full valgrind report for this test case...)
+@end example
+
+@noindent
+
+When running under valgrind, it's best to have configured gcc with
+@code{--enable-valgrind-annotations}, which automatically suppresses
+various known false positives.
+
@node Environment variables,Overview of code structure,Running the test suite,Internals
-@anchor{internals/index environment-variables}@anchor{c9}
+@anchor{internals/index environment-variables}@anchor{ca}
@section Environment variables
@@ -6557,7 +6614,7 @@
environment variables need to be set up:
@geindex environment variable; LD_LIBRARY_PATH
-@anchor{internals/index envvar-LD_LIBRARY_PATH}@anchor{ca}
+@anchor{internals/index envvar-LD_LIBRARY_PATH}@anchor{cb}
@deffn {Environment Variable} LD_LIBRARY_PATH
@quotation
@@ -6579,7 +6636,7 @@
@end deffn
@geindex environment variable; PATH
-@anchor{internals/index envvar-PATH}@anchor{cb}
+@anchor{internals/index envvar-PATH}@anchor{cc}
@deffn {Environment Variable} PATH
The library uses a driver executable for converting from .s assembler
@@ -6598,7 +6655,7 @@
@end deffn
@geindex environment variable; LIBRARY_PATH
-@anchor{internals/index envvar-LIBRARY_PATH}@anchor{cc}
+@anchor{internals/index envvar-LIBRARY_PATH}@anchor{cd}
@deffn {Environment Variable} LIBRARY_PATH
The driver executable invokes the linker, and the latter needs to locate
@@ -6634,7 +6691,7 @@
@noindent
@node Overview of code structure,,Environment variables,Internals
-@anchor{internals/index overview-of-code-structure}@anchor{cd}
+@anchor{internals/index overview-of-code-structure}@anchor{ce}
@section Overview of code structure
@@ -6733,11 +6790,11 @@
──────────────────────────> . .
. . │ start of recording::context::compile ()
. . │ . .
- . . │ ACQUIRE MUTEX .
- . . │ . .
. . │ start of playback::context::compile ()
. . │ (create tempdir) .
. . │ . .
+ . . │ ACQUIRE MUTEX .
+ . . │ . .
. . V───────────────────────> toplev::main (for now)
. . . . │
. . . . (various code)
@@ -6791,6 +6848,8 @@
. . │ . .
. . │ Load DSO (dlopen "fake.so")
. . │ . .
+ . . │ RELEASE MUTEX .
+ . . │ . .
. . │ end of playback::context::compile ()
. . │ . .
. . │ playback::context dtor
@@ -6800,8 +6859,6 @@
. . │ filesystem at this point)
. . <── . .
. . │ . .
- . . │ RELEASE MUTEX .
- . . │ . .
. . │ end of recording::context::compile ()
<─────────────────────────── . .
│ . . . .
@@ -6905,7 +6962,7 @@
production yet.
@node Indices and tables,Index,Internals,Top
-@anchor{index indices-and-tables}@anchor{ce}
+@anchor{index indices-and-tables}@anchor{cf}
@unnumbered Indices and tables