A Non-Programmer's Guide to Compiling C Programs from Source

If you're not a C developer but occasionally need to compile C or C++ programs from source, you've probably faced frustration. This guide answers common questions about compiling C programs, from installing a compiler to handling dependencies and using make or ./configure. Whether you're on Linux or macOS, these steps will help you turn source code into a working binary—no C expertise required.

Why would a non-C programmer ever need to compile C programs?

You might not write C code, but many essential tools are distributed as source code—especially on macOS or when a precompiled binary isn't available. For example, programs like paperjam, sqlite, or qf (a fast file pager) often require compilation. On Linux, package managers usually provide binaries, but on macOS you may have to build from source. It's also common when you need the latest version or a custom build. Learning the basics of compiling saves you from hunting for binaries or giving up.

What do I need to get started compiling C programs?

The essentials are a C compiler (gcc or clang), the make build tool, and the program's dependencies. On Linux, you'll often use gcc and make from the build-essential package. On macOS, install Xcode Command Line Tools to get clang and make. Many C programs also rely on libraries (like libqpdf or libpaper) that you must install separately. The program's README usually lists these dependencies, often with package names for Debian‐based distributions.

How do I install a C compiler on Linux and macOS?

On Ubuntu or other Debian‐based systems, run sudo apt-get install build-essential. This installs gcc, g++, and make. For macOS, the recommended way is to install the Xcode Command Line Tools—either via xcode-select --install or by installing Xcode from the App Store (then the command line tools are included). Homebrew users can also get them with brew install gcc but the Xcode tools are more standard. Once installed, verify with gcc --version or make --version.

How do I handle dependencies for a C program?

C programs usually have minimal dependencies, but they must be installed manually. Check the README—it often lists required packages, e.g., “libqpdf-dev and libpaper-dev”. On Debian/Ubuntu, install them with sudo apt install libqpdf-dev libpaper-dev. On macOS, you'll need to find equivalent Homebrew packages (e.g., brew install qpdf). Sometimes dependencies are development headers (ending in -dev or -devel). If the program uses pkg-config, you can verify libraries are present. If a dependency is missing, the build will fail with a clear error message—install the missing package and try again.

What is the ./configure script and how do I use it?

Some C programs (like sqlite) come with a ./configure script instead of a prebuilt Makefile. When you run ./configure, it checks your system for required libraries and tools, then generates a Makefile tailored to your environment. The output is often verbose and cryptic, but if it succeeds, you'll see a message like “config.status: creating Makefile”. If it fails, it tells you what's missing. After that, simply run make to compile. Many configure scripts also accept options (e.g., --prefix=/usr/local to set installation path). Always run ./configure before make if the script exists.

What do I do if there is no ./configure script but just a Makefile?

If the source code includes a Makefile directly (like paperjam or qf), you can skip configure and jump straight to make. However, you still need all dependencies installed—otherwise make will fail. Sometimes the Makefile expects certain variables to be set (like CC=gcc), but often it works out of the box. If make fails, check for missing headers or libraries, then install them. After a successful make, run sudo make install to copy the binary to system directories (like /usr/local/bin). If you just want to test it, you can run the binary directly from the build directory.

What are common pitfalls when compiling C programs on macOS?

macOS uses clang instead of gcc (though gcc aliases to clang). Dependency names differ from Linux; packages like libqpdf-dev don't exist in Homebrew—you need to search for the library name (e.g., qpdf). Also, sometimes make expects GNU tools not preinstalled on macOS (like gsed). In that case, install them via brew install gnu-sed. Another issue is the Xcode Command Line Tools version—older macOS may need updates. Finally, the ./configure script may have macOS‐specific flags or failures (e.g., missing libtool). Always check the program's issue tracker or README for macOS tips.