kicad-developers team mailing list archive

[John Beard <john.j.beard@xxxxxxxxx>]

Hi,

Here's a quick patch to add some documentation about print-debugging
and trace. It's a follow-up to the fuzz tool, as there would be a
conflict in the MD file, as one section follows the other, so it needs
to go in afterwards, or otherwise be manually resolved.

Also includes a handy list of WXTRACE masks, as they aren't easily
found (you have to grep for wxLogTrace, then grep for the mask
variable to find the actual string to use). I didn't document the
functions, as they're pretty self-explanatory ("KICAD_FIND_ITEM: info
about the "Find Item" tool" is not that helpful!).

Cheers,

John
On Tue, Oct 9, 2018 at 2:53 PM John Beard <john.j.beard@xxxxxxxxx> wrote:
>
> Hi,
>
> Here is an update patch that rebases over the commenting out of
> pcb_test_window, polygon_triangulation and polygon_generator and fixes
> a link error to do with base_screen.cpp.
>
> Cheers,
>
> John
> On Mon, Oct 8, 2018 at 5:27 PM John Beard <john.j.beard@xxxxxxxxx> wrote:
> >
> > Sorry,
> >
> > I wrote "ms", I meant "us" - the times are in the handful-of-millsecond range.
> >
> > Cheers,
> >
> > John
> > On Mon, Oct 8, 2018 at 5:24 PM John Beard <john.j.beard@xxxxxxxxx> wrote:
> > >
> > > Hi,
> > >
> > > This is a patch to add a test program that allows to parse a Pcbnew
> > > file from command line params or stdin. This means you can use it for
> > > fuzz testing.
> > >
> > > I have done a little bit of fuzz testing so far (8 million execs,
> > > about 70% of a cycle), and have not found any crashes, but I can make
> > > it hang in a few ways. These all seem to be in streams which contain
> > > nul's. This is actually not reachable from the UI due to reading files
> > > into wxStrings first (nut quite sure why), whereas this program uses
> > > the parser directly. Thus, the bug is probably not very critical.
> > > Example hanging input attached (note there's a nul in it, so your
> > > editor may or may not like that).
> > >
> > > This program can also be fed a number of files, which means it could
> > > be used for automated testing that all files in a batch can be parsed
> > > successfully, and also provides a handy way to put GDB on a program
> > > when debugging the parser against specific input.
> > >
> > > There is timing on the parsing too, mostly for interest (use the -v
> > > flag). It takes about 150-3000ms per FP on my machine for the FPs in
> > > Connector_PinSocket_2.54mm.pretty.
> > >
> > > There's also some centralisation of some QA-related utils into a
> > > qa_utils library.
> > >
> > > Cheers,
> > >
> > > John

From e70f1d6e86b4d0ebb5605d742a423e5b18f447af Mon Sep 17 00:00:00 2001
From: John Beard <john.j.beard@xxxxxxxxx>
Date: Wed, 10 Oct 2018 17:53:00 +0100
Subject: [PATCH] Docs: printing and trace

Add a quick outline of some of the ways you can dump debug during
debugging. Also include a list of known trace mask strings.
---
 Documentation/development/testing.md | 70 ++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/Documentation/development/testing.md b/Documentation/development/testing.md
index cf0d4c129..ae3bac342 100644
--- a/Documentation/development/testing.md
+++ b/Documentation/development/testing.md
@@ -147,6 +147,76 @@ where:
 The AFL TUI will then display the fuzzing progress, and you can use the hang- or
 crash-provoking inputs to debug code as needed.
 
+# Run-time debugging #
+
+KiCad can be debugged at run-time, either under a full debugger
+such as GDB, or using simple methods like logging debug to the
+console.
+
+## Printing debug ##
+
+If you are compiling KiCad yourself, you can simply add debugging statements to
+relevant places in the code, for example:
+
+    wxLogDebug( "Value of variable: %d", my_int );
+
+This produces debug output that can only be seen when compiling
+in Debug mode.
+
+You can also use `std::cout` and `printf`.
+
+Ensure you do not leave this kind of debugging in place when
+submitting code.
+
+## Printing trace ##
+
+Some parts of the code have "trace" that can be enabled selectively according to
+a "mask", for example:
+
+    wxLogTrace( "TRACEMASK", "My trace, value: %d", my_int );
+
+This will not be printed by default. To show it, set the `WXTRACE` environment
+variable when you run KiCad to include the masks you wish to enable:
+
+    $ WXTRACE="TRACEKEY,OTHERKEY" kicad
+
+When printed, the debug will be prefixed with a timestamp and the trace mask:
+
+    11:22:33: Trace: (KICAD_FIND_ITEM)   item Symbol GNDPWR, #PWR020
+
+Some available masks:
+
+* Core KiCad functions:
+    * `KICAD_KEY_EVENTS`
+    * `KicadScrollSettings`
+    * `KICAD_FIND_ITEM`
+    * `KICAD_FIND_REPLACE`
+    * `KICAD_NGSPICE`
+    * `KICAD_PLUGINLOADER`
+    * `GAL_PROFILE`
+    * `GAL_CACHED_CONTAINER`
+    * `PNS`
+    * `CN`
+* Plugin-specific (including "standard" KiCad formats):
+    * `3D_CACHE`
+    * `3D_SG`
+    * `3D_RESOLVER`
+    * `3D_PLUGIN_MANAGER`
+    * `KI_TRACE_CCAMERA`
+    * `PLUGIN_IDF`
+    * `PLUGIN_VRML`
+    * `KICAD_SCH_LEGACY_PLUGIN`
+    * `KICAD_GEDA_PLUGIN`
+    * `KICAD_PCB_PLUGIN`
+
+
+
+
+
+
+
+
+
 [CTest]: https://cmake.org/cmake/help/latest/module/CTest.html
 [Boost Unit Test framework]: https://www.boost.org/doc/libs/1_68_0/libs/test/doc/html/index.html
 [boost-test-functions]: https://www.boost.org/doc/libs/1_68_0/libs/test/doc/html/boost_test/utf_reference/testing_tool_ref.html
-- 
2.18.0