Linux › Section P · Compiling software from source › Topic P.3
Applying patches and troubleshooting builds
Sooner or later a source build needs a fix that arrives as a patch, or stops with a wall of error messages. Applying patches correctly and reading build errors from the first real failure, not the last line, turn both situations into routine work.
What a patch is
A patch is a text file describing changes to one or more source files, made by diff and applied by patch. Most projects now share changes through Git branches, but patches still arrive by email, in bug trackers and inside distribution source packages. The usual format is the unified diff, from diff -u, or diff -ruN to compare whole directory trees. For each file it has a header naming the old version after --- and the new one after +++. Hunks follow, each starting with a line such as @@ -1,2 +1,2 @@ (old start and length, new start and length), then lines marked - (removed), + (added) or a space (unchanged context).
Reading the paths: the -p option
Before applying a patch, read its --- and +++ lines, because they decide where you must stand. If they name src/conf.c, run patch from the directory that contains src, not from inside src. Often the paths begin with an extra top directory, such as orig/src/conf.c or package-3.4/src/conf.c, which will not match your tree. The -p option strips that many leading path components: -p0 uses the path as written, -p1 removes the first component, leaving src/conf.c. Patches made with git diff use a/ and b/ prefixes, so they almost always need -p1, which is also git apply's default.
Worked example: applying and reversing a patch
A patch fix.patch changes limit = 10 to limit = 25 in conf.c; its header names orig/src/conf.c and new/src/conf.c. 1. From the top of the source tree, test first: patch -p1 --dry-run < fix.patch printed checking file src/conf.c and changed nothing. 2. Apply it: patch -p1 < fix.patch printed patching file src/conf.c, and the file now read limit = 25. 3. Undo it: patch -p1 -R < fix.patch reversed the change. 4. Run from the wrong place, inside src, the same command printed can't find file to patch at input line 4 and asked Perhaps you used the wrong -p or --strip option? 5. There, -p2 worked instead. Every step was run with GNU patch 2.7.6.
When hunks do not apply
patch tolerates small differences. If the surrounding lines have moved, it reports Hunk #1 succeeded at 42 (offset 3 lines). If context differs slightly, it may succeed with fuzz, which deserves a careful look at the result. If a hunk cannot be placed at all, patch reports Hunk #2 FAILED, saves the rejected hunk in a file ending .rej and may keep a .orig backup. A FAILED hunk usually means the patch was written for a different version of the source. Apply the change by hand from the .rej file, or find the patch made for your version; partly patched code rarely compiles cleanly.
Patches in Git projects
When the source is a Git repository, use Git's own tools, introduced in "Lex, Yacc, scripting languages, and Java". git apply --check fix.patch tests a patch without applying it, and git apply fix.patch applies it to the working tree, refusing anything that does not fit exactly unless told otherwise. Patches produced by git format-patch carry an author and commit message too, and git am applies them as commits. Afterwards, git diff shows precisely what changed, and git restore or git checkout can return files to their committed state, which makes experimenting with patches much safer than in a plain directory.
Reading build output
Most build failures fall into four kinds, and the message tells you which. Compiler errors (error:) stop compilation of one file: syntax, unknown types, undeclared names. Compiler warnings (warning:) let compilation continue; they deserve attention but rarely cause the failure. Linker errors, such as undefined reference to, come after compiling and mean an object file or library is missing, as covered in "The C compiler and linking". Run-time library errors appear only when the program starts. Inside make, distinguish a real failure, make: *** [target] Error 1, from a line ending Error 1 (ignored), which the Makefile expected and you can usually disregard.
Worked example: finding the real error
A large package fails, and the screen ends with a cascade like this (illustrative, trimmed): src/net.c:88:5: error: unknown type name 'time_t', then make[3]: *** [Makefile:410: net.o] Error 1, make[2]: *** [all] Error 2, make[1]: *** [all-recursive] Error 1 and make: *** [all] Error 2. 1. Big projects run make inside make; the number in brackets is the nesting level. 2. Every line after the first make error just reports that a sub-make failed. 3. So scroll up to the first error: line 88 of src/net.c. 4. Rerunning plain make, or make -j1 after a parallel build, keeps the messages from being interleaved.
Fixing a missing declaration
The error above says the compiler met time_t without knowing what it is, so a header is missing. 1. Look at line 88: a declaration such as time_t started;. 2. Search forward for its use, perhaps started = time(NULL);. 3. Look up the function: man 2 time shows a SYNOPSIS beginning #include <time.h>. 4. Add #include <time.h> near the top of net.c and rebuild. The same method fixes implicit declaration of function errors, which GCC 14 and later report as errors rather than warnings by default, so older code fails to build more often than it used to. A conflicting types error means the code declares something differently from a system header.
Missing files and commands
If the preprocessor cannot find a header, such as foo.h: No such file or directory, either a library's development package is missing or its directory needs adding with -I in CPPFLAGS (often with a matching -L in LDFLAGS). apt-file search foo.h or dnf provides '*/foo.h' names the package, as shown in "Installation practice and package managers". If make reports that a program such as cc, bison or pkg-config is not found, typically with Error 127, the build tool is not installed or not on PATH. Rarely, a badly written Makefile builds a helper and then runs it without ./; fix the Makefile rather than adding . to PATH.
Common mistakes to avoid
Applying a patch from the wrong directory or with the wrong -p, then answering patch's file prompt with guesses. Skipping --dry-run on a large patch. Ignoring FAILED hunks and .rej files. Fixing the last error line on screen, which is only a sub-make reporting failure, instead of the first compiler error. Treating an (ignored) error as fatal. Silencing warnings without reading them. Disabling errors with flags such as -fpermissive or downgraded warnings instead of adding the missing #include. Adding . to PATH to work around a broken Makefile.
Key takeaways
Patches are unified diffs: --- and +++ headers name the files, @@ hunks list removed (-), added (+) and context lines. Read the paths, run patch from the right directory with the right -p, test with --dry-run, and reverse with -R; FAILED hunks leave .rej files. In Git trees use git apply or git am. When a build fails, classify the error, find the first real one above the make cascade, look up missing declarations in the man pages, and install missing -dev or -devel packages or tools.
Flashcards
Flashcard
Patch format from diff -u, with ---, +++ and @@ lines
Test your understanding
Question 1 of 5
A patch's header reads --- a/lib/util.c and +++ b/lib/util.c. From the top of the source tree, which command fits?
Question 2 of 5
patch reports can't find file to patch at input line 4. What is the most likely cause?
Question 3 of 5
A build ends with make: *** [all] Error 2 after several make[N] lines. Where is the real cause most likely to be?
Question 4 of 5
Compiling fails with error: unknown type name 'time_t'. What is the best fix?
Question 5 of 5
Applying a patch prints Hunk #2 FAILED and creates conf.c.rej. What does this most likely mean?
