enable VM tracing in user code via {.define(nimVmTrace).}

[timotheecour]

features

This PR allows user code to enable/disable VM tracing in a code section via {.define(nimVmTrace).} and {.undef(nimVmTrace).}.

Unlike -d:nimVMDebug, this doesn't require re-compiling nim and allows user code to control what sections of code should be traced ( -d:nimVMDebug by contrast generates lots of noise and cannot be controlled by user code). The check whether to trace doesn't slow down VM thanks to a caching mechanism.

example

proc main1() =
  var a = 1
  a.inc

proc main2() =
  var a = 1
  a.inc
  a+=2

{.define(nimVmTrace).}
static: main1()
{.undef(nimVmTrace).}
static: main2()

nim r --filenames:canonical -f main

tests/nim/all/t12391.nim(15, 9) [opcLdConst] static: main1()
tests/nim/all/t12391.nim(15, 14) [opcIndCall] static: main1()
tests/nim/all/t12391.nim(6, 11) [opcLdImmInt]   var a = 1
tests/nim/all/t12391.nim(7, 4) [opcAddImmInt]   a.inc
tests/nim/all/t12391.nim(6, 3) [opcRet]   var a = 1
tests/nim/all/t12391.nim(6, 3) [opcJmp]   var a = 1
tests/nim/all/t12391.nim(6, 3) [opcEof]   var a = 1

future work

• if this doesn't result in a performance penalty, consider also moving the when traceCode: into a similar flag that can be set similarly, without recompiling nim
• likewise for VM profiling
• likewise for VM counters (counting the number of times a certain event happens)

[Araq]

But please notice that even after my remarks, the mechanism is most alien. We don't enable features via .define/.undef pragmas in a block scope manner, there are much better mechanisms available.

Like:

static:
  trace: 
     main1()

[timotheecour]

the only reason I used {define}/{undef} was to avoid adding a magic or vmops, but I agree that a magic or vmops is cleaner (and a bit more efficient) here; i'll update this PR with a magic or vmops (TBD), how about adding that API in std/vmutils which can grow more APIs later (eg to control VM profiling via API calls to give more control compared to current --profileVM)

(the existing lib/std/private/vmutils.nim is unrelated and can be renamed for clarity)

[timotheecour]

PTAL, now using a vmops which is more efficient (single bool flag lookup) and flexible (can be set/unset during the course of VM evaluation, unlike define/undef)

see test in PR (nimout is truncated but you can see the full listing by running locally)

[Araq]

The implementation is ok but don't document it and don't make it an "std" module. I mean, you can document it in our "internal documentation". We don't need a "standard library" extension every time you add a debugging aid.

[timotheecour]

seems like all i need is move it stdx/vmutils and remove changelog entry then? (vmops may need some patching to support stdx, not sure yet)

regarding documentation, IMO everything should ideally be documented and docgen'd, including compiler (https://nim-lang.github.io/Nim/compiler/theindex.html), including runnableExamples wherever it makes sense; even for APIs that can change; doesn't mean end users need to see those docs, but those docs should be viewable somewhere.
Better docs for compiler/tools = lower barrier for contributions

stdx can have it's own doc/theindex, just like compiler now has (and listed in https://nim-lang.github.io/Nim/lib.html):

Manual
Standard library
extensions (stdx)
Index
Compiler docs
Fusion docs
devel, stable

[Araq]

Merging it as it is, will move it to lib/dist once we have that.