Lesson plan

Multi-file C: headers, macros and builds lesson plan

What happens between Run and the chip: one compile per file, a linker that joins them, headers with guards, macros and their traps, #if, extern and static, and build flags. Ends with one codebase that builds for an Uno and an ESP32-C3.

4 chapters, 7 lessons, about 5 hours, on the Arduino Uno R3. Every lesson runs in the browser, with nothing to install.

The unit

Objectives and materials

By the end, students can

  • Compile, link, and the headers that hold the promises.
  • Macros, their traps, and #if.
  • extern, static, and the switches every build passes.
  • One codebase, two boards.

Materials for the whole unit

  • Arduino Uno R3
  • ESP32-C3-DevKitM-1
  • Full-size breadboard
  • LED x 3
  • Pushbutton
  • Resistor x 3

Every part is already on the simulator’s bench, so there is nothing to buy or hand out. The counts are the most any one lesson uses, if you build it on real breadboards too.

Chapter 1. About 1 h 20 min

Split it up

Compile, link, and the headers that hold the promises.

LessonTimeWhat students do
Many files, one programWhat Run really does: preprocess, compile each file on its own, link them into one program. A declaration is a promise, a definition keeps it, and a second file joins the build.40 min
  1. Run it: a launch in one file
  2. A promise and a body
  3. A second file
  4. Each file sees only what it is told
  5. Say it back
Headers and guardsA rover on a grid, split into rover.h and rover.cpp. What #include really pastes, a header read twice and the guard that stops it, and why a function body in a header needs inline.40 min
  1. Run it: a rover on a grid
  2. Split it: rover.h and rover.cpp
  3. Read twice: the include guard
  4. A body in a header needs inline
  5. The header rules

Materials

  • Arduino Uno R3
  • Full-size breadboard
  • LED x 3
  • Pushbutton
  • Resistor x 3

Check for understanding

Each student finishes "Headers and guards" on their own, without opening the hints. The simulator checks 5 of its 5 steps as they go.

Then ask each one to explain, in a sentence or two, the last thing it asked of them: "The header rules".

Chapter 2. About 1 h 30 min

The preprocessor

Macros, their traps, and #if.

LessonTimeWhat students do
Macros and their trapsThe preprocessor swaps text and knows nothing about C. A square that forgets its brackets, a maximum that reads a sensor twice, # and do-while(0), and when a function or constexpr does the job better.45 min
  1. Run it: a name for a number
  2. Trap one: the missing brackets
  3. Trap two: read twice
  4. Text tricks: # and do-while(0)
  5. Fix the square
  6. Use a function instead
Conditional compilationOne sketch, many builds: #if picks which lines the compiler ever sees. Debug lines that cost nothing when off, a version gate, the chip it was built for, and a default you can override.45 min
  1. Run it: a versioned build
  2. Which chip am I?
  3. Debug lines on a switch
  4. Ship it: debug off
  5. A version gate
  6. A default you can override

Materials

  • Arduino Uno R3
  • Full-size breadboard
  • LED x 2
  • Resistor x 2

Check for understanding

Each student finishes "Conditional compilation" on their own, without opening the hints. The simulator checks 6 of its 6 steps as they go.

Then ask each one to explain, in a sentence or two, the last thing it asked of them: "A default you can override".

Chapter 3. About 1 h 20 min

Linking and flags

extern, static, and the switches every build passes.

LessonTimeWhat students do
extern and staticWho can see a name and how long it lives. A global another file reaches with extern, static at file scope that keeps a name private, and a static local that remembers between calls.40 min
  1. Run it: a launch button
  2. A local that remembers
  3. extern: reach into another file
  4. static: two files, two packets
  5. The linkage table
Build flagsEvery Run hands the compiler a list of switches. Read their fingerprints from inside a sketch: the C++ standard, the chip, the optimizer, exceptions. Then a config header, and the linker throwing away code you never call.40 min
  1. Run it: a sketch that reads its own build
  2. The chip and its clock
  3. The optimizer and the rules
  4. A config header
  5. Code nobody calls costs nothing

Materials

  • Arduino Uno R3
  • Full-size breadboard
  • LED x 2
  • Pushbutton
  • Resistor x 2

Check for understanding

Each student finishes "Build flags" on their own, without opening the hints. The simulator checks 5 of its 5 steps as they go.

Then ask each one to explain, in a sentence or two, the last thing it asked of them: "Code nobody calls costs nothing".

Chapter 4. About 55 min

Project

One codebase, two boards.

LessonTimeWhat students do
Project: one codebase for two boardsA beacon that builds unchanged for the Uno and the ESP32-C3. #if on the chip picks the pins, the sizes and a sum show what really differs, and a board.h keeps every difference in one place.55 min
  1. Run it on the ESP32-C3
  2. Same code, different sizes
  3. A sum that depends on the chip
  4. Press for fast
  5. Make the sum portable
  6. Move the board into board.h
  7. Your version

Materials

  • ESP32-C3-DevKitM-1
  • Full-size breadboard
  • LED
  • Pushbutton
  • Resistor

Check for understanding

Each student finishes "Project: one codebase for two boards" on their own, without opening the hints. The simulator checks 7 of its 7 steps as they go.

Then ask each one to explain, in a sentence or two, the last thing it asked of them: "Your version".

Your class

Teach this unit as a class

Start a class from this course and its 7 lessons are assigned in one go, in order. Students join with a six-character code or printed login cards, and each one’s work comes back to you.

The class tools are free for 30 days for one class of up to 20 students, with no card. The lessons themselves are free either way.