build-and-env

name	build-and-env
description	Playbook for environment setup, dependency repair, and build-system tasks on Linux. Pin versions, prefer system package managers, fix pip/venv/docker/make/cmake issues by reading error output carefully.

Build & Environment

Roughly a third of terminal tasks are build/env repair work: broken pip installs, Docker image problems, Makefile issues, CMake misconfigs, language-version mismatches. The playbook below handles ~80% of what you will see.

The first rule: read the actual error

Most "build is broken" failures embed the answer in the stderr. Before trying a fix, run the failing command and read the last 30 lines of output slowly. Signals:

• ModuleNotFoundError: No module named X → install X in the active interpreter (check which python first — often the wrong venv is active).
• error: command 'gcc' failed → a C dep needs system headers; look for the specific header mentioned and install its -dev / -devel package.
• ld: library not found for -lX → apt-get install libX-dev or equivalent.
• No such file or directory: 'cmake' → install it; do not try to work around.
• Permission denied → are you supposed to be running as the agent user? Don't blindly sudo; check the task's intent.

Python environments

Check what you're actually running:

which python python3 pip pip3
python --version
python -c "import sys; print(sys.executable, sys.path)"

When a pip install fails mid-way and leaves a broken state:

pip check                         # list broken deps
pip install --force-reinstall X   # re-pin a specific package
python -m pip install ...         # safer than bare `pip` if PATH is uncertain

For missing system packages, prefer the distro's package manager over pip-from-source:

apt-get update && apt-get install -y <pkg>
# or apk add --no-cache <pkg>
# or yum install -y <pkg>

If a requirements.txt is partially satisfiable, install what works first, then diagnose the rest individually — do not keep re-running the full install expecting different behavior.

Docker

• docker build failures: read the step number, run that exact RUN command interactively inside a base image to reproduce and iterate.
• Dependency conflicts usually live in one layer — pin or change that layer, don't rewrite the whole Dockerfile.
• Use docker run --rm -it <image> /bin/sh to poke at an already-built image.

Make / CMake / autotools

• make failures: read the first failing target (not the last line). make -j1 to serialize output when errors are hard to attribute.
• cmake: delete the build dir and reconfigure fresh if you change options — cached state is a common source of "impossible" errors. Typical flow:

  rm -rf build && cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j
  

• ./configure scripts print what they found and what they didn't — scroll up.

Language versions

Tasks often pin a specific version of gcc, Python, Node, Go, Fortran. If a build fails with "unrecognized flag" or "syntax error" in compiler output, suspect a version mismatch before suspecting the code. Commands that help:

gcc --version
python --version
node --version
update-alternatives --list <tool>   # on Debian

When in doubt

• Minimize the reproduction. Strip the failing step down to the shortest command that still reproduces.
• Pin, don't upgrade. pip install X==1.2.3 beats pip install -U X when the task asks for stability.
• Preserve the task's chosen package manager. If the task uses poetry, don't switch to plain pip; if it uses apt, don't reach for conda.