Loading...

C essentialsModular C

Multi-file projects & linking

10 min lesson

Next
  • 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.
Keep in mind
  • 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!
main.c
// ---- 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.c

Compiles 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 app

The linker matches the undefined add in main.o with the definition in math_utils.o and produces app.

Multi-file build steps

StepCommandOutput
Compile maingcc -c main.cmain.o
Compile utilsgcc -c math_utils.cmath_utils.o
Linkgcc main.o math_utils.o -o appapp
Run./app2 + 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.c

Use instead

gcc main.c math_utils.c -o app

The 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.c

Use instead

Define add once in math_utils.c

The 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.h

Use 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.
Previous
Next