ranlib: Usage, Options & Common CI Errors

ranlib adds or refreshes the symbol table inside a .a archive.

ranlib exists to fix one thing: a static library whose symbol index is missing or stale. Modern ar rcs does this for you, but legacy Makefiles still call ranlib as a separate step.

What it does

ranlib generates an index of the symbols defined by the object members of an archive and stores it in the archive. It is functionally equivalent to ar s. The linker uses this index to pull only the members it needs.

Common usage

Terminal

ranlib libfoo.a                   # add/refresh the symbol index
ar rc libfoo.a *.o && ranlib libfoo.a   # legacy two-step
ranlib -t libfoo.a                # just update the timestamp
ar rcs libfoo.a *.o               # modern one-step alternative

Options

Flag	What it does
(archive)	Build/update the symbol index in place
-t	Only update the archive timestamp
-D	Deterministic mode (zero mtime/uid/gid)
-U	Use real timestamps/uids (non-deterministic)

Common errors in CI

If linking a static archive reports undefined references for symbols you know are inside it, the index is missing or stale - run ranlib libfoo.a (or rebuild with ar rcs). After cross-compiling, the host ranlib may not understand the target object format; use the target-prefixed tool (e.g. aarch64-linux-gnu-ranlib). For byte-identical CI artifacts, pass -D so timestamps do not leak into the archive.

Related guides

ar: Usage, Options & Common CI Errorsar creates and manages static library (.a) archives. Reference for rcs, t, x, and the "archive has no index"… nm: Usage, Options & Common CI Errorsnm lists the symbols in object files and libraries. Reference for -C, -D, -g, -u, and using it to debug "unde… ld: Usage, Options & Common CI Errorsld is the GNU linker. Reference for -o, -l, -L, -rpath, --start-group, and the "undefined reference" and "can… strip: Usage, Options & Common CI Errorsstrip removes symbols and debug info to shrink binaries. Reference for -s, -g, --strip-unneeded, and the "los…