Re-implementing `printf` is one of those C projects that forces you to get serious about parsing, variadic functions, formatting rules, and memory discipline. But before any of that, the real foundation is the project structure—because good structure makes your code easier to extend, test, and ship as a reusable library.

Here’s the layout we’ll use:

├── build

├── examples

├── include

├── Makefile

├── printf.pdf

├── README.md

├── src

│ └── printfn.c

└── tests

Each directory has a job that supports two goals:

Produce a library that other C projects can link against
Keep the implementation testable and maintainable.

Below is an elaboration on the role of each file in the root directory:

`include/` — the public interface

This directory contains the header files that use preprocessor directives for the project. One crucial file is the printfn.h. This file contains declarations of important functions provided by the project, such as printfn, along with other auxiliary functions. Some helper functions might be declared separately in different header files within the current folder, but they will be included in printfn.h. header file to link everything in one place.

A consumer of this project should be able to do something like:

#include "printfn.h"

…and never need to know how formatting is implemented internally.

Typical contents:

printfn.h.(the public header)
function prototype(s): int printfn(const char *format, ...);
shared public types (if any)
macros/constants that are safe for users
optionally: internal headers

`src/` — implementation

This is where function definitions exist. The files in this directory define the functions declared in the include folder. For example, printfn is declared in src/printfn.c. For a simple implementation of printf, a single file will suffice; however, since the project is composed of stepwise implementations of most of printf's functionalities, we'll break this into small modules to avoid a single mega-file. As the project grows, new files will be created with names matching the functionalities defined in them, for example, the folder could entail filenames like:

parse.c — parses flags/width/precision/specifiers
format_int.c, format_hex.c, format_str.c, etc.
write_utils.c — safe output helpers, buffering, length tracking
itoa_base.c — integer → string conversions

NOTE: src/ should compile into a static or shared library, not an executable.

Makefile

A Makefile is a file we use to organize how we compile our program or run commands in the terminal. Instead of writing a long, complex command every time we need it, which is error-prone since we need to master all the options for each command, we organize the commands in a Makefile and use the make command-line utility to run each command via the tags defined in the Makefile. Our Makefile is comprised of five commands as described below:

help:

@echo "Available targets:"

@echo " all - Build example and test programs (default)"

@echo " run - Build and run the example program"

@echo " test - Build and run the test program"

@echo " clean - Remove all build artifacts"

@echo " help - Show this help message"

`build/`— compiled artifacts

This directory contains the results of compiling the source (src) files. It typically stores:

object files (.o)
dependency files (.d)
Library files (.lib, .dll, .a, .so)

`tests/` — correctness, regressions, and confidence

A printf implementation is easy to get mostly right and still be wrong in dozens of edge cases. Testing isn’t optional here, though; for this project, it might be limited. Our testing will revolve around:

Testing format specifiers output:
integers: %d, %i, %u
hex: %x, %X
pointers: %p
chars/strings: %c, %s
percent: %%
flags: -, 0, +, space, #
width/precision interactions
tricky cases: NULL, empty strings, negative numbers, INT_MIN, precision = 0, etc.
Return Value: printf returns the number of bytes printed (excluding the null byte used to end output to strings). We ensure the number of return values for printfn and the system printf with the same inputs have a difference of one, since printfn prints an extra newline except for null input.
Output Format: Ensure that both functions print the results in the same format for the same input values.
Regression tests
Whenever a bug is fixed, a test is added that will catch it. Over time, the test suite becomes a “shield” against old bugs returning.
We compile the tests and run them to ensure:
headers are correct
library exports are correct
inking works
the behavior is correct

README.md

These files provide an overview of the project setup and its organization.

printf.pdf

This file is basically the “truth source” for what one must support (especially in school-style projects). It is at the project root, so it’s always visible.