Skip to content
Get packs

Guide · Open source

How to use chibicc: clone, build and study a small C compiler

Updated · written with AI from the project's own documentation and checked against our catalogue data

chibicc is a small C compiler that implements most of C11 and is written to be read. This guide explains what it is, who it suits, and how to clone and build it so you can start studying how a C compiler works. By the end you will know where to start reading the source and which limits to expect.

chibiccrui314/chibicc · ★ 12k · MIT

Quick start

  1. 1Clone the repo. Run git clone https://github.com/rui314/chibicc to get the source.
  2. 2Check prerequisites. Make sure you have a C compiler and make installed. You are on the author's tested platform if you use Linux on x86-64.
  3. 3Read the build files. The README excerpt gives no build command, so look in the cloned repository for its build instructions.
  4. 4Read the stages. Start with the tokenizer, then the preprocessor, parser and code generator, following the four stages in order.
  5. 5Follow the commit history. Read the linked commits for a feature such as while, then move on to the first commit to see the project grow.

What chibicc is and who it is for

chibicc is a small C compiler that implements most C11 features. The README describes it as a toy-class compiler that can still compile real programs such as Git, SQLite, libpng and chibicc itself without modifying them.

It is also the reference implementation for the author's book on compilers, and each commit corresponds to a book section so you can study one feature at a time.

  • Developers who want to learn how a C compiler works internally
  • Students following a compiler-construction course or the author's book
  • Readers who want to see how a feature such as while loops or thread-local variables is implemented in a few commits
  • People who value readable compiler source over speed

Clone the repository and build it

The README's install step is to clone the repository from GitHub. The source does not give a full build command, so check the repository files for build instructions. You will need a C compiler and make, which the README excerpt does not specify.

The author's tested platform is Linux on x86-64, specifically Ubuntu 20.04. The README says it may or may not work on other systems.

  • Prerequisites: a C compiler and make (not specified in the README excerpt)
  • Tested platform: Linux on x86-64
git clone https://github.com/rui314/chibicc

Understand the four compiler stages

chibicc is split into stages that you can read separately. Following them in order is a good way to learn how source text becomes assembly.

  • Tokenize: breaks an input string into a list of tokens
  • Preprocess: expands macros and interprets preprocessor directives, producing a new token list
  • Parse: a recursive descendent parser builds abstract syntax trees and adds a type to each node
  • Codegen: emits assembly text for the AST nodes

Study one C feature using the commit history

Each commit is written to be readable on its own, so you can learn how a feature is implemented by reading one or a few commits. The README links commits for while loops, the ?: operator, compound literals and thread-local variables.

If you have time, the README suggests reading from the first commit onward, which shows the compiler growing one feature at a time.

  • Start with the first commit to see the minimal compiler
  • Pick a single feature such as while or thread-local variables and read its linked commit

Know the limits before you rely on it

chibicc has no optimization pass. The README says its output is probably twice or more slower than GCC's, and it plans to add an optimizer after the frontend is finished.

It does not support complex numbers, K&R-style function prototypes or GCC-style inline assembly. Digraphs and trigraphs are intentionally left out.

  • Not for fast or optimized output
  • Not for portability beyond x86-64 Linux
  • Not for submitting pull requests directly: the author rewrites history to fix bugs and does not take PRs directly

What people use it for

  • Learning how a tokenizer and recursive descent parser turn C source into an AST
  • Following a compiler-construction course or the author's book alongside the commits
  • Seeing how a single feature such as the ?: operator or compound literals is added
  • Reading the source of a compiler that can build Git, SQLite and libpng

Frequently asked questions

Is chibicc free to use?

chibicc is released under the MIT licence, according to the repository listing. The author says he publishes the source to give early access, and he plans to charge for the book, not the code.

What do I need to install chibicc?

The README says you clone the repository from GitHub. You need a C compiler and make, though the README excerpt does not list specific versions. The author's tested platform is Linux on x86-64.

Does chibicc work on Windows or macOS?

The README does not say. It states the author develops on Ubuntu 20.04 for x86-64, and that chibicc may or may not work on other systems. Portability is not the goal.

Can chibicc compile real programs?

Yes, according to the README. It says chibicc can compile Git, SQLite, libpng and chibicc itself without modifying them, and that the generated programs pass their test suites.

How does chibicc compare to tcc?

The README says tcc is a one-pass compiler, while chibicc is designed differently. Other comparable projects listed are 8cc, SubC and lacc. The source does not offer a benchmark between them.

Is chibicc fast?

No. The README says there is no optimization pass and the output is probably twice or more slower than GCC's. Choose a different compiler if you need optimized code.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

chibicc suits developers and students who want to learn how a C compiler works by reading small, feature-by-feature commits. It is a poor choice if you need fast output, portability beyond x86-64 Linux, or a compiler to ship code with. If you need a production compiler, use GCC or Clang instead.

Install options & downloads