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

Introduction: Why You Might Need to Compile C Programs

If you're not a C or C++ developer, the thought of compiling source code can be intimidating. I've been there: for years my approach was simply “install dependencies, run make, and hope it works.” When that failed, I'd either search for a precompiled binary or give up. This strategy worked fine on Linux, but after switching to a Mac, I found myself needing to compile programs more often — and having to actually understand the process. In this guide, I'll walk through three real-world examples — paperjam, sqlite, and qf (a file-opening pager) — to show you exactly what's involved in compiling a C program.

Step 1: Install a C Compiler

Before you can compile anything, you need a C compiler and the make build tool. On Ubuntu or other Debian-based systems, this is straightforward:

sudo apt-get install build-essential

This installs gcc, g++, and make. On a Mac, install Xcode Command Line Tools by running xcode-select --install in the terminal. (If you use Homebrew, you might also find brew install gcc helpful, but the command line tools are usually sufficient.)

Step 2: Handle Dependencies (Even Without a Package Manager)

Unlike modern languages such as Python or JavaScript, C doesn't have a built-in dependency manager. You must manually install the libraries your program needs. Fortunately, C programmers typically keep dependencies minimal, and most required packages are available through your system's package manager.

Always check the project's README first — it nearly always explains what to install. For paperjam, the README says:

To compile PaperJam, you need the headers for the libqpdf and libpaper libraries (usually available as libqpdf-dev and libpaper-dev packages). You may need a2x (found in AsciiDoc) for building manual pages.

On a Debian-based system, you'd run:

sudo apt install -y libqpdf-dev libpaper-dev

If you're on a Mac with Homebrew, try brew install qpdf (Homebrew usually names packages without the -dev suffix). The exact names vary, so when you see a package like libqpdf-dev, assume it's Debian-specific — on other platforms you'll need to search for the equivalent.

Step 3: Understand the Build Process — ./configure vs. Makefile

Once dependencies are installed, you'll typically find one of two things in the source directory:

• A Makefile (ready to use with make)
• A ./configure script (generates a Makefile based on your system)

For example, sqlite ships with a ./configure script. Running it prints reams of output and either produces a Makefile or fails with a clear error about a missing dependency. The typical workflow is:

./configure
make
sudo make install

The ./configure script checks for libraries, compiler features, and platform specifics, then creates a tailored Makefile. Failures usually mean you missed a dependency — go back to Step 2.

What If There's Just a Makefile?

Other projects, like qf, come with a Makefile directly. In that case you can skip the configure step and jump straight to make. If make fails, check the Makefile for comments about required libraries.

Dealing with Missing Libraries in ./configure

If ./configure complains about a missing header or library, install the appropriate -dev package (Linux) or equivalent (macOS). For sqlite, you might need libreadline-dev or similar. Search for the error message — it's a common problem with a simple fix.

Common Pitfalls and Quick Fixes

• “command not found: make” — You skipped Step 1. Install the build tools.
• “fatal error: something.h: No such file or directory” — Missing -dev package. Install it.
• “./configure: Permission denied” — Run chmod +x configure first.
• On macOS: If a ./configure script assumes a Linux environment, you may need to install libraries via Homebrew or compile with --prefix=/usr/local.

Final Thoughts: Practice Makes Perfect

Compiling C programs from source is a skill that improves with each attempt. Start with simple tools like paperjam or qf, and gradually work your way up to more complex projects like sqlite. Remember that while it can be frustrating, the dependency problem is actually a sign of C's lightweight philosophy — and once you have the right packages, the process is remarkably consistent across projects.

For further reading, check out the GNU Make manual or your distribution's build-essential documentation. Happy compiling!