The lessons

Ninety six lessons in eleven parts. This page is generated from the lessons themselves, so a lesson that exists is on it and a lesson that does not is not.

Every one is a notebook with a Colab badge, so there is nothing to install. Part I runs on the recorded dumps in corpora/, which are real output from a real GCC 16.2 and are committed, so a reader with a browser and no compiler sees what the lesson saw. Colab does have a GCC and it is not this one, which is why the setup cell picks a backend that matches and the banner says which one it picked.

	Lesson	What you come away with	Milestone	Run it
Z01	C++ for people who will only ever read it	The seventeen constructs that make GCC's source look unreadable, each one in real code from the pinned tree, and forty lines of a real pass read line by line with every one of them marked	M1
Z02	How to be lost in four and a half million lines, productively	What every directory in the GCC tree is for, which files are written by the build rather than by a person, and the four routes from something a compiler printed back to the line of source that printed it	M1
T01	What does gcc actually run?	That gcc compiles nothing and runs the programs that do, how to make it show you the list without running any of it, why cc1 is not on your PATH, and where the flags you typed actually end up	M1
T02	The five faces of one function	That there are four representations of your code inside GCC and not one, what each of them is for, how to line them up against the source, and why the line a statement came from is not always the line its instructions end up on	M1
T03	GIMPLE is C with the fun removed	Why the middle IR looks so plain, the one rule that makes it that way, where the temporaries come from and how many of them to expect, and why the two operators that cannot survive the trip are the two that were never really operators	M1
T04	Three hundred and ninety-five passes	What sits between GIMPLE and assembly, how long the list really is, why the ON and OFF that GCC prints next to each pass is not the same question as whether the pass ran, and what happens to one small function as all of it goes past	M1
T05	SSA in one lesson	Reading s_1, s_3 and s_8 as three versions of one variable rather than three variables, what a PHI is and where it has to go, what the (D) on n_5(D) is telling you, and watching SSA get taken apart again on the way to machine code	M0
T06	What -O2 actually turns on	An optimization level is four integers and a table of a hundred and fourteen entries, why counting the switches that flipped gives the wrong answer, why -Os and -Oz look identical from outside and are not, and how few of the fifty five differences between -O1 and -O2 any one function notices	M1
T07	Where GIMPLE becomes RTL	The one node type the whole back end is built from, how to read an RTL expression out loud, why most of a function after expand is not instructions, the fiction of unlimited registers, and the same program on four machines disagreeing about every single thing you can measure	M1
T08	Registers are a lie until they are not	The pass that makes good on the expander's promise, what an allocno is and why it is not a pseudo, live ranges and interference, the one number that decides everything, and the same five functions coming out differently on two machines because one of them has half as many registers	M1
T09	The last mile	The pass that writes the assembly file, the annotation that says which machine description pattern emitted each line, why one pattern can emit five different instructions, and the thirty four lines of a forty six line file that are not instructions at all	M1
T10	The whole map	One program through the whole compiler, with the pass tape and the IR ladder side by side, the fourteen stages you would draw from memory and which five of them are not passes, and one expression traced from the source line to the instruction	M1
B01	A compiler of your own, in five minutes or four hours	The three ways to have a GCC 16 and what each one costs, what the seven flags on a real configure line actually decided, which four of the fourteen front ends you get when you ask for none, and the empty file that decides whether your compiler is fast or careful	M2
B02	Building it three times, and the one thing that proves	Why a compiler is built three times and compared twice, what that comparison can and cannot catch, the six files it is told to ignore, and a real stage comparison failure induced on purpose so you can see what it looks like before it happens to you	M2
B03	A debugger on the compiler, and the counter for when you cannot have one	A real gdb session against a real cc1, recorded command by command: what the compiler's own gdbinit did before you typed anything, how to stop on one pass out of several hundred, how to read a function from a breakpoint, and how to find the exact transformation that broke your code by bisecting a debug counter instead	M2
B04	Forty thousand tests, and how to run one of them	The GCC test suite taken apart: what a directive is, why the command line is not what the file says, the subtractive rule that makes a test fail for output nobody asked about, the six compilations every torture test costs, how to run one file without running the other thirty five thousand, and the one question worth asking of a .sum	M2
B05	Sixty lines of C++, and you are inside the compiler	GCC's plugin mechanism from the outside in: the three things a plugin has to have, the three ways it is refused, what an event actually is, a GIMPLE pass of your own inserted after ssa with its own dump file, switching one of GCC's passes off from outside and watching the assembly move, and why the thing you are writing against is not an API	M2
F01	The driver is an interpreter	That gcc -dumpspecs prints a program, in a language with conditionals and function calls, which the driver interprets to decide what to run; how to read it; and four text files that change what your compiler does without patching or rebuilding it	M3
F02	The preprocessor is not a text editor	That the preprocessor lexes your file into tokens before it does anything else, and that its printed output is a rendering of those tokens rather than the tokens themselves; the space GCC inserts that is in no input file; the four hundred macros you did not write; and why one #include of stdio.h opens thirty eight files	M3
F03	The C parser can see four tokens	That GCC's C parser is hand written recursive descent whose whole memory is four token slots and the symbol table; why one missing semicolon produces eight different messages; why the caret is on the line above the mistake; why three mistakes come out as two errors; and why A * b; needs a symbol table to read	M3

20 of 96 written.