Multi-file projects & linking
10 min lesson
- A multi-file project splits a program into several .c files, each compiled separately and joined by the linker into one executable.
- This matters because large programs are easier to read, test and reuse when each file has one clear job.
- Think of a multi-file project as a team of cooks: each cook prepares one dish in their own kitchen, and the waiter (the linker) brings all the dishes together on one table.
- Each .c file is compiled into an object file (.o) containing machine code and a list of symbols it defines and needs.
- The linker matches undefined symbols in one object with definitions in another and produces the final executable.
- A header declares what a module offers; the .c file defines it; other files include the header and call the functions.
- The computer compiles each file independently and then links them, which is why a change in one file only requires recompiling that file.
- The syntax is: gcc -c main.c math_utils.c then gcc main.o math_utils.o -o app, or simply gcc main.c math_utils.c -o app.
- A realistic use: a main.c that handles user interaction, a math_utils.c that does calculations, and a math_utils.h shared between them.
- A surprising detail: a missing definition shows up as a linker error like 'undefined reference to add', not a compiler error.
- The example program shows a small multi-file project with main.c, math_utils.c and math_utils.h.
- Split code into modules with clear responsibilities and matching headers.
- Compile each .c file separately with -c, then link the object files.
- Undefined reference errors come from the linker and mean a definition is missing.
- Use headers to share declarations, not to share code.
- You are structuring real projects now. Excellent progress!
// ---- math_utils.h ----
#ifndef MATH_UTILS_H
#define MATH_UTILS_H
int add(int a, int b);
#endif
// ---- math_utils.c ----
#include "math_utils.h"
int add(int a, int b) {
return a + b;
}
// ---- main.c ----
#include <stdio.h>
#include "math_utils.h"
int main(void) {
printf("2 + 3 = %d\n", add(2, 3));
return 0;
}What happens: 2 + 3 = 5
Breaking it down
Header
int add(int a, int b);Declares add so any file that includes the header can call it. No body is present.
Source file
int add(int a, int b) { return a + b; }Defines the function once. The compiler turns this into machine code in math_utils.o.
Calling file
#include "math_utils.h"main.c includes the header to learn about add, then calls it in main.
Compile step
gcc -c main.cCompiles main.c to main.o. The call to add is left as an undefined symbol for the linker.
Link step
gcc main.o math_utils.o -o appThe linker matches the undefined add in main.o with the definition in math_utils.o and produces app.
Multi-file build steps
| Step | Command | Output |
|---|---|---|
| Compile main | gcc -c main.c | main.o |
| Compile utils | gcc -c math_utils.c | math_utils.o |
| Link | gcc main.o math_utils.o -o app | app |
| Run | ./app | 2 + 3 = 5 |
A helpful analogy
A multi-file project is like a team of cooks preparing one meal. Each cook (each .c file) works in their own kitchen on one dish. The waiter (the linker) brings all the finished dishes together on one table (the executable). The menu (the header) tells everyone what is being served.
Nesting rules
- 1.Each .c file is compiled independently; it must include the headers for the functions it calls.
- 2.Declarations go in headers; definitions go in exactly one .c file.
- 3.Use -c to compile without linking, then link all .o files together.
- 4.If a symbol is undefined, check that the .c file defining it is included in the link command.
Common mistakes
Forgetting to link a source file
Avoid
gcc main.c -o app // missing math_utils.cUse instead
gcc main.c math_utils.c -o appThe linker cannot find add, so it reports 'undefined reference to add'. Include every source file that defines needed symbols.
Defining the same function in two files
Avoid
int add(...) in both main.c and math_utils.cUse instead
Define add once in math_utils.cThe linker sees two definitions of add and reports a multiple-definition error.
Forgetting to include the header
Avoid
// main.c calls add without including math_utils.hUse instead
#include "math_utils.h"Without the declaration, the compiler assumes an old-style signature and may warn or error, and the call may misbehave.
Quick tips
- •Name files after their module, like math_utils.c and math_utils.h.
- •Compile with -Wall -Wextra on every file to catch problems early.
- •Use make (next lesson) to automate the compile and link steps.
- •Try removing math_utils.c from the link command to see the linker error.
- •Keep main.c focused on orchestration; put logic in other modules.