compile-compcert

name	compile-compcert
description	Guide for building CompCert, the formally verified C compiler, from source. This skill should be used when compiling, building, or installing CompCert, or when working with Coq-based software that has strict dependency version requirements. Covers OCaml/opam setup, Coq version compatibility, memory management, and common build pitfalls.

Compile CompCert

Overview

CompCert is a formally verified C compiler built with Coq proof assistant. Building it from source requires careful attention to dependency versions, particularly Coq compatibility, and resource constraints in containerized environments.

Pre-Build Investigation (Critical First Step)

Before installing any dependencies, download and examine CompCert's requirements:

1. Download CompCert source first

   • Obtain the source tarball or clone the repository
   • Check the configure script for version requirements: grep -i "coq" configure
   • Review README or INSTALL files for dependency specifications

2. Identify exact Coq version requirements

   • CompCert has strict Coq version bounds (e.g., CompCert 3.13.1 requires Coq ≤ 8.16.1)
   • Installing an incompatible Coq version wastes significant time and resources
   • Check both minimum and maximum supported versions

3. Assess system environment

   • Check architecture: uname -m (typically x86_64)
   • Check available memory: free -h
   • Determine if running in container (affects swap, permissions)
   • Verify privileged operations availability (swap creation usually fails in containers)

Dependency Chain

Install dependencies in this order, with version awareness:

1. System Packages

Install all system dependencies in a single command:

apt-get update && apt-get install -y opam gcc g++ make libgmp-dev pkg-config

2. OCaml/opam Setup

opam init -y --disable-sandboxing
eval $(opam env)

Memory optimization: Set job limit immediately after init to prevent OOM:

opam config set-global jobs 1

3. Coq Installation (Version Critical)

• Do NOT install latest Coq - check CompCert's requirements first
• Install the correct version: opam install coq.X.Y.Z menhir
• Common compatible versions:
  • CompCert 3.13.x: Coq 8.16.1 or earlier
  • CompCert 3.12.x: Coq 8.15.x or earlier

4. CompCert Build

./configure <target-arch>   # e.g., x86_64-linux
make
make install PREFIX=<path>

Memory Management in Constrained Environments

Coq and CompCert compilation are memory-intensive:

1. Limit parallel jobs: opam config set-global jobs 1 before any opam install
2. Do NOT attempt swap creation in containers - swapon fails with "Operation not permitted"
3. Monitor memory usage during compilation: watch free -h
4. If OOM occurs: Kill stuck processes and retry with lower parallelism

Verification Strategy

After build completion, verify:

1. Binary exists and is executable

   test -x /path/to/ccomp && echo "exists"
   

2. Compiler functions correctly

   echo 'int main() { return 0; }' > /tmp/test.c
   ccomp -o /tmp/test /tmp/test.c
   /tmp/test && echo "success"
   

3. Expected behavior for unsupported features

   • CompCert should reject certain C features (e.g., some GNU extensions)
   • Test with known unsupported constructs to verify proper rejection

Common Pitfalls

Version Mismatch (Most Common)

• Symptom: Build fails with Coq compatibility errors
• Cause: Installed Coq version outside CompCert's supported range
• Prevention: Always check configure script before installing Coq

OOM During Coq Installation

• Symptom: Process killed, system becomes unresponsive
• Cause: Parallel compilation exceeds available memory
• Prevention: Set jobs 1 immediately after opam init

Missing System Dependencies

• Symptom: Configure or build fails with missing library errors
• Cause: Incremental dependency installation
• Prevention: Install all system packages upfront (libgmp-dev, pkg-config, etc.)

Binary Path Confusion

• Symptom: make install places binary in unexpected location
• Cause: Default PREFIX vs expected installation path differ
• Prevention: Specify exact paths during configure, or create symlinks post-install

Swap Creation Failure in Containers

• Symptom: swapon failed: Operation not permitted
• Cause: Container lacks privileges for swap operations
• Prevention: Do not attempt swap creation; rely on job limiting instead

Efficient Build Workflow Summary

1. Download CompCert source
2. Check version requirements in configure script
3. Assess system resources and environment
4. Install ALL system packages in one command
5. Initialize opam with job limit set to 1
6. Install correct Coq version (not latest)
7. Configure and build CompCert
8. Verify binary location and create symlinks if needed
9. Run verification tests