[swift-dev] SR-3423 Starter questions

[Breckin Loggins]

This would make a great contribution to the "how to contribute" documentation; it's excellent advice.

> On Nov 9, 2017, at 8:24 AM, Brent Royal-Gordon via swift-dev <swift-dev at swift.org> wrote:
> 
>> On Nov 7, 2017, at 4:18 AM, Mohammed Ennabah via swift-dev <swift-dev at swift.org> wrote:
>> 
>> Hi all,
>> 
>> This is the first time I work on that deep of the compiler (in SR-3423 Enum with tuple raw value not allowed) and I’m not sure where to start and what do I need to do and what files this issue is related to. It would be great if anyone guided me. Thanks.
> 
> This is *just* the very first step, but here's what I do when I want to debug something that involves a compiler error message:
> 
> 	1. Write some code that triggers the bug and compile it.
> 
> 	For instance, that bug includes a Stack Overflow link—copy that code and paste it into the Swift REPL.
> 
> 	2. Pick some chunk of the error message that doesn't include any identifiers and search the Swift source code for it.
> 
> 	For instance, one of the errors is "raw value for enum case must be a literal", so search for that.
> 
> 	3. Most of the hits will be tests, but one will be in a .def file; that's where the error is defined. Open the file, go to that line, and get the error identifier from it.
> 
> 	In this case, include/swift/AST/DiagnosticsParse.swift has this line in it:
> 
> 		ERROR(nonliteral_enum_case_raw_value,PointsToFirstBadToken, "raw value for enum case must be a literal", ()) 
> 	
> 	The identifier I'm talking about is the first argument to the ERROR macro—here, it's "nonliteral_enum_case_raw_value".
> 
> 	(Before you move on to the next step, look around in this file a little bit and try to get a sense for how error message strings are formatted. It may help you with future error searches.)
> 
> 	4. Search the Swift source code for that error identifier. Each hit (besides the one in the .def file) is one of the places in the compiler that can generate that error message. Read the code around each of those hits (including the name of the functions, types, files, and folders it's in) and try to figure out if it handles the specific case you want to solve, and if so, how you might be able to modify it to suit your needs.
> 
> 	In this example, there is only one hit—in a .cpp file in the parser—and, a couple lines above it, you can see a dyn_cast call that checks if the expression is a literal. (`dyn_cast` is equivalent to an `as?` cast in Swift—it returns `null` if the value doesn't belong to the indicated type.) This is where the compiler is testing whether the raw value assigned to a case is a literal. You'll need to modify the code here so that it also accepts tuples of literals (and presumably, tuples of tuples of literals, and so on). There will be more to do, but that's the first step.
> 
> When you're reading code, don't be discouraged if you don't understand it immediately. The Swift compiler is a large, complicated system, and there's lots of complicated stuff going on. Be patient, don't be afraid to jump over to another function to see what it does, and if you get stuck trying to figure out one part, move on to something else.

Another thing I've learned: don't be afraid to break it. On purpose. 

Think of the Swift repo on your machine as YOUR Swift compiler. You can make it do anything you want! Wanna make Swift look like Pascal just to figure out how the lexer and parser work? Have at it! Just because you never intend to commit a change doesn't mean it isn't valuable. 

When I don't know where to start with something in a complicated codebase, I always start by breaking something on purpose and putting a "DO NOT COMMIT" comment or warning where I do that. Now that I know I won't inadvertently check in a silly change and embarrass myself, I feel much better about exploring the code with abandon and learning about how things work by studying what happens when they don't... and that's where the learning happens for me.

> 
> I'm still very much a beginner, but this has helped me get started on a few different bugs. I hope it can help you too.

If it helps, I still do this on codebases I've been familiar with for years when I'm changing something in an area I don't know fluently. :)

> 
> -- 
> Brent Royal-Gordon
> Architechies
> 
> _______________________________________________
> swift-dev mailing list
> swift-dev at swift.org
> https://lists.swift.org/mailman/listinfo/swift-dev