Rung 1 — Toolchain & Debugging Journal

Headline. A public GitHub repo that documents your first month of C by showing your tools working on real bugs — five annotated gdb sessions, five sanitizer catches, an annotated Makefile, and green CI on day 30.

Month target. M1 (July 2026). Publish by the last day of M1. No slippage — Rung 1 is the momentum flywheel for the entire year.

What You Build

Repo name: c-toolchain-journal (or a name you’ll be proud of on LinkedIn — this URL becomes public).

Contents at minimum:

  • Makefile — annotated line-by-line in comments: what -Wall -Wextra -Wpedantic -Werror -fsanitize=address,undefined -g3 -O0 each buy you, why -MMD -MP for dependency tracking, how the sanitize, release, and debug targets differ.

  • gdb/ — five subdirectories, each containing:

    • bug.c (the reproducer, 20-80 LOC, deliberately buggy)

    • session.log (the actual gdb transcript — bt, frame, print, watch, info locals, x/16xw)

    • WRITEUP.md (root cause in one paragraph; the fix as a diff; the gdb command that revealed the bug named explicitly)

  • sanitizers/ — five subdirectories, each with an ASan or UBSan catch (heap-buffer-overflow, use-after-free, stack-buffer-overflow, signed-integer-overflow, misaligned-load) with the raw sanitizer output, an explanation, and the fix.

  • notes/ — your personal notes: week1.md through week4.md. Rough is fine; readable is required.

  • .github/workflows/ci.yml — Ubuntu-latest job that runs make, make test, make asan.

  • README.md — one-line pitch, what’s in the repo, “how to reproduce any bug in this repo in under 60 seconds.”

Target size: 500-800 LOC of C, 1500-2500 words of prose.

Why This Rung, Why Now

Month 1 is when 80% of self-taught C learners quietly give up. They give up not because C is hard but because they cannot see what their program is doing — pointers feel like guesswork, segfaults feel like verdicts from a hostile god, and the toolchain is a hairball of Makefile incantations. Rung 1 exists to convert those three fears into three habits before you touch a data structure.

You publish Rung 1 in M1 because a portfolio piece shipped in month 1 does one thing no future rung can do: it proves you ship. A recruiter looking at your GitHub in M6 sees eleven months of committed work leading up to that day. That timeline is worth more than the code inside it.

Acceptance Criteria

  • 5 gdb writeups, each pointing at a different class of bug (dangling pointer, off-by-one, uninitialized read, wrong printf format specifier, aliased pointer)

  • 5 sanitizer catches, at least one UBSan (not all ASan)

  • Annotated Makefile with debug, release, asan, ubsan, test, clean targets — all working

  • GitHub Actions CI green on main

  • README executable in ≤ 5 minutes on a fresh Ubuntu 22.04 VM

  • LinkedIn post published announcing “Month 1 of 13” with repo link

  • Commit history spans ≥ 15 distinct days in M1 (proves cadence, not a one-weekend cram)

Where to Publish

  • GitHub: github.com/<you>/c-toolchain-journal, pinned on your profile.

  • LinkedIn: one post titled “I’m spending 13 months learning to write production C. Month 1 shipped.” Link the repo. Tag no one. Keep it short — 4 sentences plus the link.

  • Reddit: r/C_Programming — post the annotated Makefile as its own thread with title “Annotated my beginner Makefile — feedback welcome” (do not spam-post the repo; ask for feedback on one artifact).

  • Personal blog: optional at this rung, but if you already have one, cross-post the “5 sanitizer catches” as a single article.

Signal to Recruiter / Employer

“This person reasons about tools, not just code. They shipped from week 1. They know that reading a segfault report is a skill and they invested in it early.”

This rung by itself does not make you hireable. What it does is inoculate your GitHub against the “started but never finished” pattern that recruiters see 100 times a week. It is the first vote your future self casts for your credibility.

Common Failure Modes

  1. The “polished tutorial” trap. You copy debugging examples from Beej or a blog post, dress them up, and pretend they are your bugs. A reviewer can smell this in 30 seconds — the writeups have no confusion, no wrong turns, no “I thought it was X but it turned out to be Y.” Detection: every writeup must include one wrong hypothesis you disproved.

  2. The single-weekend cram. All 15 commits land in the last three days of M1. Detection: GitHub’s contribution graph shows a solid bar on M1 day 28-30 and blanks before. A recruiter’s eye catches this instantly.

  3. Sanitizer catches that don’t compile. You paste ASan output without checking that the bug reproducer still builds. Detection: CI must run each sanitizers/*/bug.c and confirm the sanitizer fires.

  4. README that assumes context. You use make without saying sudo apt install build-essential first. Detection: run your own README from a fresh Docker container ubuntu:22.04 — if it fails, the reader also fails.

Estimated Hours

  • gdb writeups: ~8h (5 × ~1.5h each including finding a reproducer)

  • Sanitizer catches: ~6h

  • Makefile annotation + CI setup: ~4h

  • README + LinkedIn post + polish: ~4h

  • Buffer for the “why isn’t this working” hours: ~8h

Total: ~30 hours across M1. That fits in 10-12h/week for 3 weeks with a week of buffer. If you exceed 40h, stop and simplify — Rung 1 must not eat Rung 2.

Prior-Art / Inspirations to Study First

  • Julia Evans’ zines and blog posts (jvns.ca) — the tone you want for the writeups: curious, precise, unafraid to say “I was wrong at first.”

  • crash-course-cpp and crash-course-c READMEs on GitHub — study three or four to see what a well-organized beginner repo looks like.

  • abseil/abseil-cpp .github/workflows/ — for CI structure; overkill for Rung 1 but a good north star.

  • The sanitizers Google project wiki on GitHub — read the ASan and UBSan pages once before you start hunting bugs.

Return to README.md · Next: 02_rung_2_libprep_containers.md