From fe7a2d60f90ac48b296b637401da2724dd160954 Mon Sep 17 00:00:00 2001 From: Timothee Cour Date: Thu, 28 May 2020 01:19:12 -0700 Subject: make it easier to figure out how to debug issues (#14477) --- .github/ISSUE_TEMPLATE/bug_report.md | 13 ++++++++++++- compiler/lineinfos.nim | 12 +++++++++++- compiler/msgs.nim | 7 ++++--- compiler/semexprs.nim | 9 +++++---- doc/intern.rst | 31 ++++++++++++++++++++++++++++++- readme.md | 2 ++ 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 & " ") + styledMsgWriteln(fgRed, """ +No stack traceback available +To create a stacktrace, rerun compilation with './koch temp $1 ', 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 -- cgit 1.4.1-2-gfad0