Skip to content
Tutorials Center
My learning

Topics

C Reference ยท Concepts and Tools

Compiling and linking C programs

How a C program becomes an executable: compile each file to an object file, link them with libraries, and fix undefined reference and multiple definition errors.

C builds in two main phases. Compiling turns each .c file (a translation unit) into an object file containing machine code and a list of symbols it defines and needs. Linking joins the object files and libraries, matching every needed symbol with exactly one definition, and writes the executable.

This split is why you can call a function after only declaring it: the compiler needs the declaration to check the call; the linker finds the definition later. It also explains the two classic link errors, "undefined reference" (a symbol with no definition) and "multiple definition" (a symbol defined more than once).

TEXT
gcc -c main.c -o main.o        # compile only
gcc -c util.c -o util.o
gcc main.o util.o -o app       # link

Try it

The runner compiles and links a single file, so these examples show the ideas inside one program.

C Declaration versus definition

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

C Internal versus external linkage

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

The steps

  1. Preprocess (gcc -E): expand #include and macros.
  2. Compile (gcc -S): produce assembly.
  3. Assemble (gcc -c): produce the object file .o (.obj with MSVC).
  4. Link: combine objects and libraries into an executable.

Inspect the symbols of an object file with nm main.o: T marks a function defined here, U an undefined symbol the linker must find elsewhere, D or B data.

Libraries

Kind Files Behavior
Static library libname.a (name.lib) Archive of object files. The linker copies the members it needs into your executable.
Shared library libname.so (.dylib, .dll) Loaded at run time and shared by programs. Needs to be found when the program starts.
TEXT
# Build a static library and use it
gcc -c util.c -o util.o
ar rcs libutil.a util.o
gcc main.c -L. -lutil -o app          # -L: search here, -lutil: libutil.a/.so

# Build a shared library
gcc -fPIC -shared util.c -o libutil.so

The C library (libc) is linked automatically. Other libraries need a flag: -lm for some <math.h> functions on many systems (the runner links them without it), -pthread for threads, -lrt or -ldl on older systems. Put libraries after the files that use them.

Message Typical cause
undefined reference to 'f' Declared but never defined, a source file missing from the command line, or a library missing (-l) or in the wrong order.
multiple definition of 'x' Two files define the same global; often a variable defined in a header. Declare it extern in the header and define it in one .c file.
cannot find -lfoo The library is not installed or -L does not point to it.
error while loading shared libraries (at run time) The shared library is not on the loader's search path (LD_LIBRARY_PATH, rpath, or installation).

Usage notes

  • Headers hold declarations, sources hold definitions. Put function prototypes, typedefs, extern declarations and macros in headers, with include guards.
  • Make private things static. static functions and globals have internal linkage and cannot collide with other files' names.
  • inline functions in headers use static inline or an extern definition in one file; see inline.
  • Static initialization order across files is not an issue in C: static objects need constant initializers.
  • Build each file separately so a change recompiles only what it must. A Makefile automates that.
  • Link-time optimization (-flto) lets the optimizer see across files.
  • Loading libraries at run time with dlopen is covered in dlopen; it does not link in the runner.