How Do I Organize Multi-File C Projects?

After this lesson, you will be able to:

• Split a project into header and source files appropriately
• Write include guards to prevent duplicate definitions
• Write a Makefile with separate compilation and header dependencies
• Identify and fix common multi-file errors (undefined reference, multiple definition)

The Problem: One File Isn’t Cutting It

Your lab programs are growing — struct definitions, sort functions, file I/O, menu logic. When everything lives in one file, finding anything means scrolling through hundreds of lines. And changing one function recompiles the entire file.

In Lesson 2.11, you learned the basics of headers and Makefiles. Now let’s apply those patterns to a real multi-file project with structs, multiple source files, and a production-style Makefile.

Building a Multi-File Project

Project Layout

A well-organized project separates concerns:

project/
├── student.h          ← Struct definition + function prototypes
├── student.c          ← Implementation of student functions
├── io.c               ← File I/O and display functions
├── main.c             ← Driver (main, menu logic)
└── Makefile           ← Build automation

The Header File (Interface)

student.h declares what the module provides:

#ifndef STUDENT_H
#define STUDENT_H

#include <stdio.h>

typedef struct
{
    char name[50];
    int id;
    double gpa;
} Student;

/* Function prototypes */
void print_student(const Student *s);
void sort_by_name(Student roster[], int size);
void sort_by_gpa(Student roster[], int size);
int read_roster(const char *filename, Student roster[], int max);

#endif

The Implementation Files

student.c implements the prototypes from student.h:

#include "student.h"
#include <string.h>

void print_student(const Student *s)
{
    printf("%-20s %5d  %.2f\n", s->name, s->id, s->gpa);
}

void sort_by_name(Student roster[], int size)
{
    // Selection sort using strcmp on name field
    // ... (implementation from Lesson 4.4)
}

io.c handles file reading:

#include "student.h"
#include <string.h>

int read_roster(const char *filename, Student roster[], int max)
{
    FILE *fp = fopen(filename, "r");
    if (fp == NULL) return -1;
    // ... read students ...
    fclose(fp);
    return count;
}

main.c is the driver:

#include "student.h"

int main(void)
{
    Student roster[100];
    int count = read_roster("students.txt", roster, 100);
    // ... menu logic ...
    return 0;
}

The Makefile

CC = gcc
CFLAGS = -Wall -Wextra -std=c17 -g

program: main.o student.o io.o
	$(CC) $(CFLAGS) -o program main.o student.o io.o

main.o: main.c student.h
	$(CC) $(CFLAGS) -c main.c

student.o: student.c student.h
	$(CC) $(CFLAGS) -c student.c

io.o: io.c student.h
	$(CC) $(CFLAGS) -c io.c

clean:
	rm -f program *.o

Key Insight: Each .o target lists its header file dependencies. If you change student.h, make knows to recompile everything that includes it. If you only change main.c, only main.o is recompiled — the other object files are reused.

Step 1: Compile each .c file to a .o (object) file
  gcc -c main.c     → main.o      (machine code, unlinked)
  gcc -c student.c   → student.o
  gcc -c io.c        → io.o

Step 2: Link all .o files into one executable
  gcc -o program main.o student.o io.o

%.o: %.c student.h
	$(CC) $(CFLAGS) -c $<

.PHONY: clean all

all: program

clean:
	rm -f program *.o

valgrind: program
	valgrind --leak-check=full ./program input.txt

Reading Provided Code

In labs, you’ll receive header files that define the interface. Your job is to implement the functions declared there. This is a critical skill:

1. Read the .h file to understand the struct and function signatures
2. Look at how main.c calls the functions
3. Implement each function in the .c file
4. Test incrementally — implement one function, compile, test, repeat

The Trick: When given a lab with provided code, start by reading the header file and understanding the struct. Then implement the simplest function first (usually print). Get it compiling and tested before moving to harder functions. Building incrementally prevents being stuck with 10 errors at once.

Big Picture: Separating interface from implementation is one of the most important ideas in software engineering. It’s why you can use printf without reading glibc source code, and why teams of hundreds can work on the same codebase. Headers define contracts; source files fulfill them. This pattern scales from two-file lab assignments to million-line projects.

What’s Next

Your projects are organized. Your structs are defined. Your sort functions work. But those sort functions are nearly identical — the only difference is the comparison. In the next lesson, you’ll learn function pointers, which let you write one sort function that accepts any comparison.