kichipoe/learn-c-core

Purpose and Scope

This is a documentation-first C learning repository. Its implemented scope is currently Level 0: compiler toolchain, compilation behavior, debugging, command-line arguments, and a small modular calculator. The repository is not a unified application; each directory contains independently compiled learning exercises.

Entry Points and Execution Model

Most examples are standalone C executables entered through main. Primary executable sources include:

• Level-0-Toolchain/1-dev-env/main.c

• Level-0-Toolchain/7-cli-program/main.c

• Level-0-Toolchain/8-mycalc/src/main.c

Programs are compiled externally with a C compiler; no build system, runtime service, deployment target, or infrastructure definition is present.

Curriculum as the Top-Level Architecture

The root documentation defines a staged progression from toolchain fundamentals through production-quality C. The current implemented stage is represented by:

• ROADMAP.md

• Level-0-Toolchain/LEARNING.md

• Level-0-Toolchain/PROJECT.md

Level 0 is organized as numbered, isolated stages. This makes experimentation and intentional failures first-class learning artifacts rather than shared production modules.

Toolchain and Compilation Stages

The early directories establish the C development lifecycle:

• Environment and return-value behavior: Level-0-Toolchain/1-dev-env/main.c, Level-0-Toolchain/1-dev-env/no-main-return.c

• Minimal program structure and required headers/entry point: Level-0-Toolchain/2-my-first-program/main.c, Level-0-Toolchain/2-my-first-program/without-main.c

• Compilation pipeline and compiler flags: Level-0-Toolchain/3-compilation-pipeline/main.c, Level-0-Toolchain/4-compiler-flags/main.c

Control flow is source file → compiler/preprocessor/assembler/linker workflow → native executable. Compiler diagnostics are part of the expected output of several stages.

Failure and Debugging Boundary

Deliberately invalid programs isolate major compiler/linker failure classes:

• Level-0-Toolchain/5-complier-errors/syntax-error.c

• Level-0-Toolchain/5-complier-errors/unknown-func.c

• Level-0-Toolchain/5-complier-errors/linker-error.c

Debugging is then treated as a separate workflow around a runnable program in Level-0-Toolchain/6-Debuging/main.c. These examples should remain independently compiled because their intended behavior includes compile or link failure.

Command-Line Interface Exercise

Level-0-Toolchain/7-cli-program/main.c is the explicit CLI boundary. Its input arrives through the conventional C process arguments (argc/argv), and its output is terminal-oriented. It has no persistence, network, or external API integration.

Modular Calculator Project

The calculator is the most application-like component and demonstrates C module boundaries:

• Public interface: Level-0-Toolchain/8-mycalc/include/calculator.h

• Arithmetic implementation: Level-0-Toolchain/8-mycalc/src/calculator.c

• CLI/application orchestration: Level-0-Toolchain/8-mycalc/src/main.c

Its primary flow is user/process input → main parses or dispatches operation requests → calculator API calls → arithmetic result or error handling → terminal output. The header separates declaration/API contract from implementation, and linking must combine main.c with calculator.c.

Documentation and Learning Feedback Loop

Repository-wide planning and retrospective records provide the non-code control layer:

• README.md

• NOTES.md

• MISTAKES.md

The intended workflow is learn a concept, run an experiment or small program, record findings and mistakes, then expand into a project. No external services or nonstandard runtime dependencies are evidenced; the material runtime is a native C executable plus a local C compiler/debugger toolchain.