Building from Source

icestorm-bin is built inside a manylinux_2_34 Docker container so the resulting binaries work on any Linux system with glibc ≥ 2.34.

Prerequisites

• Docker (any recent version)

• git with the repository cloned

Build script

The entire build is driven by scripts/build.sh. The build-local.sh wrapper invokes it inside the correct Docker container:

./scripts/build-local.sh

You can also specify a different manylinux image:

./scripts/build-local.sh manylinux2014_x86_64
./scripts/build-local.sh manylinux_2_28_x86_64
./scripts/build-local.sh manylinux_2_34_x86_64

Or run Docker directly:

docker run --rm \
    --volume "$(pwd):/io" \
    --env image=manylinux_2_34_x86_64 \
    --workdir /io \
    quay.io/pypa/manylinux_2_34_x86_64 \
    /io/scripts/build.sh

The script performs the following steps:

1. System dependencies — installs build tools (gcc, gcc-c++, make, git, python3) via dnf.

2. Clone icestorm — clones YosysHQ/icestorm from the main branch (if not already present).

3. Build — runs make -j$(nproc) ICEPROG=0 PREFIX=<release_dir> (iceprog is excluded as it requires USB hardware access).

4. Install — runs make install into the release staging directory.

5. Tarball — packs the release directory into release/icestorm-<image>-<version>.tar.gz.

Environment variables

Variable	Description
image	manylinux image name used as the platform tag in the release filename (default: linux).
icestorm_version	Override the full release version string. Defaults to 1.1.<BUILD_NUM> when BUILD_NUM is set, or 1.1 otherwise.
BUILD_NUM	GitHub Actions run ID appended to the version for traceability.

CI / GitHub Actions

The workflow in .github/workflows/ci.yml runs automatically on every push and on a weekly schedule (Sunday 12:00 UTC).

Steps:

1. version-check — constructs the release version string as 1.1.<run-id>.

2. build-linux-x86_64 — matrix build across manylinux2014_x86_64, manylinux_2_28_x86_64, and manylinux_2_34_x86_64.

3. publish — creates a GitHub Release and attaches the tarball.

Documentation is built separately and published to GitHub Pages whenever main is updated (see .github/workflows/docs.yml).

Release layout

The unpacked release directory contains:

bin/
  icepack
  icetime
  icemulti
  icepll
  icebram
  icebox_chipdb
  icebox_hlc
  icebox_stat
  icebox_vlog
lib/
  python3/
    site-packages/
      icebox/
share/
  icebox/
    chipdb-*.txt
export.envrc