add debugging instructions

[timotheecour]

/cc @Araq I was trying to debug https://github.com/nim-lang/nimsuggest/issues/93 but ran into a number of issues; it turns out debugging nimsuggest is tricky, we should add instructions in doc/nimsuggest.rst

• compiling nimsuggest in debug mode: one gotcha is that -o:/tmp/nimsuggest_dbg won't work, see https://github.com/nim-lang/nimsuggest/issues/91#issuecomment-435548683 this works:

$nimc_D/bin/nim c -o:bin/nimsuggest_dbg --noNimblePath -p:compiler --debugger:native nimsuggest/nimsuggest.nim

at least with that we get proper stacktraces (eg https://github.com/nim-lang/nimsuggest/issues/93#issuecomment-435546865 instead of just SIGSEGV: Illegal storage access)

• using gdb currently doesn't work for OSX on latest OS (mojave), see https://stackoverflow.com/questions/52529838/gdb-8-2-cant-recognized-executable-file-on-macos-mojave-10-14 I got BFD "unknown load command 0x32" which led me there; it has nothing to do with Nim but affects all programs if you're not affected by this issue, you may try your luck with:

gdb --args $nimc_D/bin/nimsuggest_dbg3 --stdin --debug bugs/nimsuggest/t01.nim 

although the caveat below (stdin) may apply

• using lldb doesn't work with --stdin

this will block forever:

lldb -- $nimc_D/bin/nimsuggest_dbg3 --stdin bugs/nimsuggest/t01.nim
usage: sug|con|def|use|dus|chk|mod|highlight|outline|known file.nim[;dirtyfile.nim]:line:col
type 'quit' to quit
type 'debug' to toggle debug mode on/off
type 'terse' to toggle terse mode on/off
> sug bugs/nimsuggest/t01.nim:5:3

• here's what worked for me:

$nimc_D/bin/nimsuggest_dbg3 --stdin bugs/nimsuggest/t01.nim

in another terminal, get pid:

pgrep nimsuggest_dbg3
48944
lldb -p 48944
c # press this to continue

now you can type commands in 1st terminal and it'll break in 2nd terminal if an error happens:

> sug bugs/nimsuggest/t01.nim:5:3

with the bug in https://github.com/nim-lang/nimsuggest/issues/93 I'm finally getting a proper lldb debug session, see example output here: https://github.com/nim-lang/nimsuggest/issues/93#issuecomment-435551093

[saem]

For future reference, one can use the Microsoft provided C++ Debug extension to debug nimsuggest:

Below is a snippet showing me launching nimsuggest against the vscode extension, feel free to adjust it to your needs. Either in .vscode/launch.json or workspace settings under "launch" (depends upon whethe you're using a workspace) and ensure the following configuration is present:

"configurations": [
  {
    "name": "(gdb) nimsuggest",
    "type": "cppdbg",
    "request": "launch",
    "program": "${workspaceFolder}/bin/nimsuggest",
    "args": ["--stdin", "--find", "--debug", "--backend:js", "~/Development/nim/vscode-nim/src/nimvscode.nim"],
    "stopAtEntry": false,
    "cwd": "${workspaceFolder}",
    "environment": [],
    "externalConsole": false,
    "MIMode": "gdb",
    "miDebuggerPath": "nim-gdb",
    "setupCommands": [
      {
        "description": "Enable pretty-printing for gdb",
        "text": "-enable-pretty-printing",
        "ignoreFailures": true
      }
    ]
  }
]

A few notes:

1. I'm using choosenim so nim-gdb is broken
2. workaround: create a dir tools and symlink under ~/.nimble
3. symlink tools/nim-gdb.py to ~/.nimble/tools/nim-gdb.py
4. I compiled nimsuggest with: ./koch nimsuggest --debuginfo --linedir:on -u:release -u:danger -d:debug --debugger:native, but the temp one is a better idea

Breakpoints work and most variable value formatting works. There are cases where nim-gdb.py formatters don't seem to handle things well, in my case after a while ConfigRef breaks (no longer displays children). I'm new to gdb, lldb, and co so I haven't had really dug in, but for the curious you can see full details of what's being sent back and forth by adding the following to the configuration above (it should be a sibling to name, type, request, program, ...):

{
  "name": "(gdb) nimsuggest",
  "...": "... all the previous config ...",

  "logging": {
    "engineLogging": true,
    "trace": true,
    "traceResponse": true
  }
}