Introduction: Why Compiling C Programs Can Be Daunting
If you’re not a C developer, the prospect of compiling a C or C++ program from source can feel intimidating. For years, my approach was simple: install the dependencies, run make, and hope it works. If it didn’t, I’d search for a precompiled binary or give up. This strategy worked well on Linux, where binaries were common, but after switching to macOS, I found myself needing to compile programs more often. This article breaks down the process step by step, using real-world examples like paperjam, sqlite, and qf (a pager that opens files from search results with rg -n THING | qf).
Step 1: Install a C Compiler
Before you can compile anything, you need a C compiler and the make tool. On Ubuntu or other Debian-based systems, install the build-essential package:
sudo apt-get install build-essentialThis installs gcc, g++, and make. On macOS, you’ll need the Xcode Command Line Tools, which you can install via Terminal:
xcode-select --installIf you use Homebrew, you can also install gcc directly, but the Command Line Tools are the standard route.
Step 2: Install the Program’s Dependencies
Unlike modern languages with built-in package managers, C programs require you to manually fetch dependencies. Thankfully, C projects tend to keep dependencies minimal, and most are available through your system’s package manager. The README file of a project usually explains what you need. For example, paperjam‘s 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 Debian-based systems, you’d run:
sudo apt install -y libqpdf-dev libpaper-devBut be careful: package names given in READMEs often assume a Debian context. On macOS with Homebrew, use brew install qpdf (the -dev suffix isn’t used). For other distros, adapt accordingly.
Step 3: Run ./configure (If Needed)
Some C projects come with a Makefile directly, while others provide a ./configure script. For instance, sqlite‘s source includes a ./configure script. When you run it, it checks for dependencies and generates a Makefile tailored to your system. If the script fails, it usually tells you what’s missing. The output can be verbose and cryptic, but the key is to look for error messages about missing headers or libraries.
If the project already has a Makefile, you can skip this step and go directly to make. But if you see a configure script, run it first:
./configure
makeStep 4: Compile with make
Once dependencies are installed and a Makefile exists (either provided or generated by ./configure), running make is typically straightforward. This command reads the Makefile and builds the program. If the build fails, common issues include missing libraries, incorrect compiler flags, or version mismatches. For example, when compiling qf, ensure you have ncurses and pkg-config. If errors appear, check the output for clues—sometimes you’ll need to install additional development packages.
Step 5: Install the Program (Optional)
After successful compilation, the binary is usually in the source directory. To install it system-wide, run sudo make install. This copies the executable to a directory like /usr/local/bin. However, you may prefer to keep the binary in your home directory or add the source folder to your PATH—especially if you’re just testing.
Common Pitfalls and Tips
Missing Dependencies
The most frequent problem is a missing -dev package for a library. Search for the library name plus -dev on Debian, or use brew search on macOS.
Compiler Errors
If the compiler throws errors, they often point to specific missing functions or headers. Google the error—chances are someone else has solved it.
macOS-Specific Issues
On macOS, gcc is often an alias for clang. If a program expects GNU extensions, you may need to install gcc via Homebrew and set CC=gcc before running make.
Conclusion
Compiling C programs doesn’t have to be a black art. With a clear process—install a compiler, resolve dependencies, run ./configure if present, then make—you can build most open-source tools from source. The examples of paperjam, sqlite, and qf show that the steps are similar across projects. Once you’ve done it a few times, the whole flow becomes second nature, and you’ll no longer have to rely on “hope someone else has compiled it.”