Better User Guides

[canelhasmateus]

A possible contributor would like to get to speed as fast and easily as possible. That requires information, which we aim to write down in our guides.

However, as someone with better knowledge of the system, there are always implicit assumptions of knowledge, or small information gaps that can always be improved upon.

This issue aims to be a place to jot down specific troubles - to be stored offband and retrievable as a source of possible improvements.

[canelhasmateus]

Is there a simple example of what the AST should look like so I can reference the .nim file syntax and see what it actually correlates to in AST form?

Build the compiler with -d=nimDebugUtils - it is mentioned in the debug.html documentation

{.define(nimCompilerDebug).}

echo "string literals"

Another one would be dumpTree.
If you need a post-sem you can write a macro that accepts typed tree and then prints it using treeRepr.

Inner details of how AST is changed/expected in the compiler might be different in the middle of the sem* processing and there are no exact specs how it is done
you can put debug node from compiler/utils/astrepr if you want to see those parts
and it also shows more details about inner fields like offset, symbols-identifier distinction and so on
debug node, debug sym, debug typ

there are several preset values for the TReprConf like https://nim-works.github.io/nimskull/compiler/utils/astrepr.html#onlyStructureTReprConf

[haxscramper]

discussion around https://matrix.to/#/!tMNPwvArIZqKucTsiS:matrix.org/$mlFRKFIkX60GJDAFtfAdpSD0LC8u-Vlh_rkPCSebh1Q?via=matrix.org&via=envs.net&via=tchncs.de, todo for me: write it down properly and put into docs