gcc main.c util.c -o app: compile and link multiple C files

To build a C program from several source files, pass all .c files to the compiler in one command: gcc main.c util.c -o app. Each file is compiled separately and the results are linked into one executable. Shared declarations go in a header (util.h) that both files #include; headers are never passed on the command line. For bigger projects, compile each file to an object file with -c and link the .o files.

One command, or compile and link

The example uses Clang 20 from the ziglang package on PyPI, run through uv; cc below stands for it. Write gcc or clang on your machine:

cc() { uv run -q --no-project --python 3.13 --with ziglang==0.15.1 python -m ziglang cc -fno-color-diagnostics "$@"; }
mkdir -p include src
cat > include/util.h <<'EOF'
#ifndef UTIL_H
#define UTIL_H
int add(int a, int b);
#endif
EOF
cat > src/util.c <<'EOF'
#include "util.h"
int add(int a, int b) { return a + b; }
EOF
cat > src/main.c <<'EOF'
#include <stdio.h>
#include "util.h"
int main(void) {
    printf("2 + 3 = %d\n", add(2, 3));
    return 0;
}
EOF
# 1. everything in one step
cc -Wall -Iinclude src/main.c src/util.c -o app
./app
# 2. compile each file, then link the objects
cc -Wall -Iinclude -c src/util.c -o util.o
cc -Wall -Iinclude -c src/main.c -o main.o
cc main.o util.o -o app2
./app2

2 + 3 = 5
2 + 3 = 5

-Iinclude adds the folder to the search path for #include "util.h". The include guard (#ifndef UTIL_H) keeps the header from being processed twice in one file.

Options

Errors you can meet

• Undefined reference. Forgetting a file at the link step (gcc src/main.c -o app without util.c) compiles main.c fine and then fails at linking: GNU ld reports undefined reference to 'add', LLVM's lld undefined symbol: add. See undefined reference to, which applies to C as well.
• Implicit declaration. Calling add without including util.h gives implicit declaration of function, an error in C99 and later with current compilers.
• No such file. fatal error: util.h: No such file or directory means the header folder is missing from -I.
• Multiple definition. A function body in a header that two .c files include is defined twice; keep only the prototype in the header.

Confirm it worked

The program runs and prints the result of the function from the other file. nm main.o lists add as undefined (U) and nm util.o as defined (T), which is exactly what the linker joins.

FAQ