make it easier to figure out how to debug issues (#14477)

6 files changed, 64 insertions, 10 deletions

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 895b4ba61..9571896d8 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -12,9 +12,14 @@ Function `echo` outputs the wrong string.
 ### Example
 ```nim
 echo "Hello World!"
+# This code should be a minimum reproducible example:
+# try to simplify and minimize as much as possible. If it's a compiler
+# issue, try to minimize further by removing any imports if possible.
 ```
 
 ### Current Output
+please check whether the problem still exists in git head before posting,
+see [rebuilding the compiler](https://nim-lang.github.io/Nim/intern.html#rebuilding-the-compiler).
 ```
 Hola mundo!
 ```
@@ -29,12 +34,18 @@ Hello World!
 * In file xyz there is a call that might be the cause of it.
 
 ### Additional Information
+If it's a regression, you can help us by identifying which version introduced
+the bug, see [Bisecting for regressions](https://nim-lang.github.io/Nim/intern.html#bisecting-for-regressions),
+or at least try known past releases (eg `choosenim 1.2.0`).
+
+If it's a pre-existing compiler bug, see [Debugging the compiler](https://nim-lang.github.io/Nim/intern.html#debugging-the-compiler)
+which should give more context on a compiler crash.
 
-* It was working in version a.b.c
 * Issue #abc is related, but different because of ...
 * This issue is blocking my project xyz
 
 ```
 $ nim -v
 Nim Compiler Version 0.1.2
+# make sure to include the git hash if not using a tagged release
 ```
diff --git a/compiler/lineinfos.nim b/compiler/lineinfos.nim
index e1e0a4bc8..bb47e947f 100644
--- a/compiler/lineinfos.nim
+++ b/compiler/lineinfos.nim
@@ -13,7 +13,17 @@
 import ropes, tables, pathutils
 
 const
-  explanationsBaseUrl* = "https://nim-lang.org/docs"
+  explanationsBaseUrl* = "https://nim-lang.github.io/Nim"
+    # was: "https://nim-lang.org/docs" but we're now usually showing devel docs
+    # instead of latest release docs.
+
+proc createDocLink*(urlSuffix: string): string =
+  # os.`/` is not appropriate for urls.
+  result = explanationsBaseUrl
+  if urlSuffix.len > 0 and urlSuffix[0] == '/':
+    result.add urlSuffix
+  else:
+    result.add "/" & urlSuffix
 
 type
   TMsgKind* = enum
diff --git a/compiler/msgs.nim b/compiler/msgs.nim
index a26aa0a3c..1b7be46b8 100644
--- a/compiler/msgs.nim
+++ b/compiler/msgs.nim
@@ -385,9 +385,10 @@ proc quit(conf: ConfigRef; msg: TMsgKind) {.gcsafe.} =
       if stackTraceAvailable() and isNil(conf.writelnHook):
         writeStackTrace()
       else:
-        styledMsgWriteln(fgRed, "No stack traceback available\n" &
-            "To create a stacktrace, rerun compilation with ./koch temp " &
-            conf.command & " <file>")
+        styledMsgWriteln(fgRed, """
+No stack traceback available
+To create a stacktrace, rerun compilation with './koch temp $1 <file>', see $2 for details""" %
+          [conf.command, "intern.html#debugging-the-compiler".createDocLink])
   quit 1
 
 proc handleError(conf: ConfigRef; msg: TMsgKind, eh: TErrorHandling, s: string) =
diff --git a/compiler/semexprs.nim b/compiler/semexprs.nim
index 43fd1b69c..e29101385 100644
--- a/compiler/semexprs.nim
+++ b/compiler/semexprs.nim
@@ -1572,12 +1572,13 @@ proc takeImplicitAddr(c: PContext, n: PNode; isLent: bool): PNode =
   # return a view into the first argument (if there is one):
   let root = exprRoot(n)
   if root != nil and root.owner == c.p.owner:
+    template url: string = "var_t_return.html".createDocLink
     if root.kind in {skLet, skVar, skTemp} and sfGlobal notin root.flags:
-      localError(c.config, n.info, "'$1' escapes its stack frame; context: '$2'; see $3/var_t_return.html" % [
-        root.name.s, renderTree(n, {renderNoComments}), explanationsBaseUrl])
+      localError(c.config, n.info, "'$1' escapes its stack frame; context: '$2'; see $3" % [
+        root.name.s, renderTree(n, {renderNoComments}), url])
     elif root.kind == skParam and root.position != 0:
-      localError(c.config, n.info, "'$1' is not the first parameter; context: '$2'; see $3/var_t_return.html" % [
-        root.name.s, renderTree(n, {renderNoComments}), explanationsBaseUrl])
+      localError(c.config, n.info, "'$1' is not the first parameter; context: '$2'; see $3" % [
+        root.name.s, renderTree(n, {renderNoComments}), url])
   case n.kind
   of nkHiddenAddr, nkAddr: return n
   of nkDerefExpr: return n[0]
diff --git a/doc/intern.rst b/doc/intern.rst
index e56c699ae..b68067d1b 100644
--- a/doc/intern.rst
+++ b/doc/intern.rst
@@ -113,6 +113,25 @@ We already know the type information as a graph in the compiler.
 Thus we need to serialize this graph as RTTI for C code generation.
 Look at the file ``lib/system/hti.nim`` for more information.
 
+Rebuilding the compiler
+========================
+
+After an initial build via `sh build_all.sh` on posix or `build_all.bat` on windows,
+you can rebuild the compiler as follows:
+* `nim c koch` if you need to rebuild koch
+* `./koch boot -d:release` this ensures the compiler can rebuild itself
+  (use `koch` instead of `./koch` on windows), which builds the compiler 3 times.
+
+A faster approach if you don't need to run the full bootstrapping implied by `koch boot`,
+is the following:
+* `pathto/nim c --lib:lib -d:release -o:bin/nim_temp compiler/nim.nim`
+Where `pathto/nim` is any nim binary sufficiently recent (eg `bin/nim_cources`
+built during bootstrap or `$HOME/.nimble/bin/nim` installed by `choosenim 1.2.0`)
+
+You can pass any additional options such as `-d:leanCompiler` if you don't need
+certain features or `-d:debug --stacktrace:on --excessiveStackTrace --stackTraceMsgs`
+for debugging the compiler. See also
+[Debugging the compiler](intern.html#debugging-the-compiler).
 
 Debugging the compiler
 ======================
@@ -146,7 +165,12 @@ To create a new compiler for each run, use ``koch temp``::
   ./koch temp c /tmp/test.nim
 
 ``koch temp`` creates a debug build of the compiler, which is useful
-to create stacktraces for compiler debugging.
+to create stacktraces for compiler debugging. See also
+[Rebuilding the compiler](intern.html#rebuilding-the-compiler) if you need
+more control.
+
+Bisecting for regressions
+=========================
 
 ``koch temp`` returns 125 as the exit code in case the compiler
 compilation fails. This exit code tells ``git bisect`` to skip the
@@ -155,6 +179,11 @@ current commit.::
   git bisect start bad-commit good-commit
   git bisect run ./koch temp -r c test-source.nim
 
+You can also bisect using custom options to build the compiler, for example if
+you don't need a debug version of the compiler (which runs slower), you can replace
+`./koch temp` by explicit compilation command, see
+[Rebuilding the compiler](intern.html#rebuilding-the-compiler).
+
 The compiler's architecture
 ===========================
 
diff --git a/readme.md b/readme.md
index d34b78548..eb6b68d0d 100644
--- a/readme.md
+++ b/readme.md
@@ -79,6 +79,8 @@ Next run the appropriate build shell script for your platform:
 Finally, once you have finished the build steps (on Windows, Mac or Linux) you
 should add the ``bin`` directory to your PATH.
 
+See also [rebuilding the compiler](intern.html#rebuilding-the-compiler).
+
 ## Koch
 
 ``koch`` is the build tool used to build various parts of Nim and to generate