better document debug macros

[fantasma13]

As discussed with Ed, please add using debugging macros to the documents.

[mohawk2]

This needs to be in an updated "developer's guide":

To generate a stack-trace to help us debug a problem, please first of all do make realclean, ensure you have the latest released PDL, then if it is still happening, please follow this process:

• Rerun perl Makefile.PL (this will update the timestamps on Makefiles, prompting a full rebuild)
• Edit your generated top-level Makefile to add -g to the OPTIMIZE = line to generate debug symbols (this gets propagated to subdirs by EUMM’s PASTHRU_* mechanism)
• Run: make
• Run: gdb perl -ex 'run -Mblib t/tracking.t'
• In gdb, run: bt
• Copy-paste the backtrace output which should show where the segfault originated

Then please open an issue on whichever repo is relevant (possibly PDL, possibly in this context PDL-OpenCV) with your perl -V output and PDL version, together with the stack-trace created above. When you do paste such output into a GitHub issue, please surround such blocks with ``` on their own lines. You can check out it will render with the "Preview" button above the issue-editing box.

[mohawk2]

Techniques to be discussed should include the new PDL_IF_BAD, and recommend starting any design by thinking about complex values first, together with how to handle badvalues. An example of creative use of badvalues is mentioned in https://perlmonks.org/?node_id=11143676

Also to be discussed: code generation; cf PDL::Slatec, PDL::LinearAlgebra::Complex, and now PDL::OpenCV.

[mohawk2]

Also in design thinking: broadcasting from the start (and pthreading, where relevant).

[mohawk2]

To see how PP processes one operation's pp_def, put before its pp_def:

$::PP_VERBOSE = 1;

and after:

$::PP_VERBOSE = 0;

Also, for "core" modules, the Makefile has e.g.. the coretest target for rapid iteration, which is made up of sub-targets like Basic_Slices_pm_to_blib_dynamic, for finer-grained rapid iteration.

Additionally, it can be useful to inspect e.g. Basic/Slices/pp-rangeb.c to see what is actually generated.

[mohawk2]

Include techniques shown in #457, and the new graphviz stuff as shown in https://sourceforge.net/p/pdl/mailman/message/58730063/

[mohawk2]

Include techniques of Example/address-pseudonymise including -x mode to help spot old vs new behaviour.

[mohawk2]

The fancy loop() and OtherPars stuff in https://www.perlmonks.org/?node_id=11157717 should probably be captured.

[mohawk2]

The discussion of internals and dataflow in moocow-the-bovine/PDL-CCS#5 should be extracted from.

[mohawk2]

See #463 for notes on doc-pp.

[mohawk2]

This is a good example of good array-programming practice (f5ac428), credit to @wlmb and Photonic for the technique including the commenting style.

[mohawk2]

#451 has performance-analysing stuff, cachegrind in particular. #421 discusses other performance/implementation stuff.

[HaraldJoerg]

The recipe to create a stack trace and documentation of $::PP_VERBOSE will be included in the DeveloperGuide as parts of Pull Request #486.

[mohawk2]

On adding badvalue-awareness; I believe fd41378 is a nice demonstration (for matmult) of how to do this, needing the addition of 4 lines.