Improving compiler's knowledge of "hidden" identifiers

[dom96]

Problem

• when defined(foo) introduces branches into code that the compiler doesn't see unless the right define is enabled via a -d:foo flag.
• This means that the compiler's error messages are sometimes less than ideal[1] and it also means that the docgen cannot document these "define flags".

Proposed solution

There are undoubtedly many other ways to solve this (suggestions welcome), but one that came to me yesterday seems like the least difficult to implement:

• userDefined() - a replacement for defined which signifies that the define can be overriden by the user.

The compiler can then parse the code under any when branches with a userDefined call and have better knowledge of what procs are available with what -d flags. The docgen can make use of this information as well to list procs that are available under different -d flags. The compiler can use it for better error messages.

References

1 - I ran into a confusing error message, where compiling Nimble worked just fine, but compiling one of its specific modules failed because -d:ssl wasn't enabled (for Nimble it was enabled in its nim.cfg file which didn't apply to the specific module I was compiling). This lead to an "identifier not found: SslError" message which would have been much nicer as "SslError is not defined without -d:ssl" (or similar): https://irclogs.nim-lang.org/05-02-2021.html#22:41:06

[Clyybber]

See #269

[mratsim]

It's worse when when defined(foo): actually requires when defined(foo) or defined(nimdoc) or defined(nimsuggest): and maybe you also need when defined(nimcheck) or defined(drnim): nowadays.

It's not a hypothetical problem either, I have to deal with that in Arraymancer:

https://github.com/mratsim/Arraymancer/blob/71cf616/src/arraymancer/tensor.nim#L74-L80

[Araq]

When we have better nkError support the compiler could check all when branches, always, improving the tooling situation quite a bit...

[treeform]

This is even worse when you when type(x) == ... and it only checks branches for specific type only if you call the function. Otherwise a compiler error can live dormant in the code.

It would be nice if compiler could error check all when branches but then would it error out when win32 functions don't exist on linux? Is when checking even possible? Maybe platform branches are not done, while other do. Complex...