Build / port / repair protocol
Long builds fail when the agent thrashes — retrying the same command or guessing at an error. Follow this order.
Read the build docs first. Find
HACKING.*,README*,INSTALL*,Makefiletargets, and CI config. Identify the exact configure / build / test commands and required toolchain versions.Install dependencies once, non-interactively.
DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y <pkgs>. Confirm tools are on PATH before building.Configure → build → test, one stage at a time, capturing the FIRST error. Use
make -j$(nproc). Tee the log:<cmd> 2>&1 | tee /tmp/build.log. The first error is the real one; later lines are fallout.Watch memory on parallel builds.
-j$(nproc)can exhaust RAM and get the buildKilledwith no compiler error (common with Coq/OCaml/LLVM builds). If the build dies without an error message, re-run at-j4and monitorfree -h. A slower build that finishes beats a fast build that OOMs.Cross-compiling to another target/architecture: install the matching toolchain (e.g.
apt-get install -y gcc-mips-linux-gnu) and make the build use it — setCC/CXX/LD, or the project's--host/--target/CROSS_COMPILEvariables — instead of silently producing a host binary. Verify the output withfile(it must report the target architecture, e.g.ELF 32-bit … MIPS).Reproduce the stated failure with the exact command before changing anything, so you have a baseline to compare against.
Change one thing at a time, rebuild, check. If a fix does not change the error, revert it — do not stack guesses.
Verify with the task's stated acceptance command (the specific test target or binary invocation), not a proxy.
Checkpoint long builds — write a small script so a re-run resumes from the last successful stage instead of restarting from zero.