Dockerfile.deb

# Copyright 2025-     FlagOS Contributors
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

# Dockerfile to build the FlagTree wheel, then assemble a Debian package.
#
# Two-stage:
#   1. wheel-builder: heavy stage with CMake/Ninja/LLVM that compiles the
#      flagtree wheel from source. Produces /wheels/flagtree-*.whl.
#   2. deb-assembler: light stage that runs dpkg-buildpackage to wrap the
#      pre-built wheel into a .deb. The deb stage does NOT recompile.
#
# Build:
#   docker build -f packaging/debian/build-helpers/Dockerfile.deb \
#     --target deb-output \
#     -t flagtree-deb-nvidia .
#
# COPY-narrowing: the wheel-builder COPYs only the paths the build
# needs (python/, third_party/, include/, lib/, cmake/, bin/,
# CMakeLists.txt, *.toml, LICENSE, README*). It deliberately does NOT
# copy packaging/, docs/, .github/, dockerfiles/, etc. — that way edits
# to debian/control or rpm/specs/ don't invalidate the 36-min wheel
# build cache. The deb-assembler stage gets packaging/debian via its
# own narrow COPY.
#
# FLAGTREE_BACKEND notes: FlagTree's "default" backend IS nvidia (no
# nvidia.py module exists in setup_tools/utils/). Setting
# FLAGTREE_BACKEND=nvidia would make setup_helper.py try to import a
# missing module and silently produce an empty stub. We unset the env
# var explicitly in the wheel-build RUN.

ARG DEB_BASE_IMAGE=ubuntu:24.04

# ---------- Stage 1: build the wheel ----------
FROM ${DEB_BASE_IMAGE} AS wheel-builder
SHELL ["/bin/bash", "-o", "pipefail", "-c"]

ENV DEBIAN_FRONTEND=noninteractive
ENV VIRTUAL_ENV=/opt/flagtree-build-venv
ENV PATH="${VIRTUAL_ENV}/bin:${PATH}"
ENV PIP_ROOT_USER_ACTION=ignore

RUN apt-get update && apt-get install -y --no-install-recommends \
        python3 python3-pip python3-dev python3-venv \
        build-essential cmake ninja-build git \
        zlib1g zlib1g-dev libxml2 libxml2-dev nlohmann-json3-dev \
        wget curl ca-certificates \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

# Ubuntu 24.04 marks /usr Python as externally managed (PEP 668). Keep all
# wheel-builder pip installs inside a venv instead of mutating system Python.
RUN python3 -m venv "${VIRTUAL_ENV}" && \
    python -m pip install --no-cache-dir --upgrade pip setuptools wheel build

WORKDIR /src
# Dependency layer first so source edits don't invalidate it.
COPY python/requirements.txt /src/python/requirements.txt
RUN python -m pip install --no-cache-dir -r python/requirements.txt

# Narrow COPY: only the paths the wheel build needs, so packaging-only
# edits (specs, debian/, helpers) do NOT invalidate the ~50 min wheel
# layer. setup.py / pyproject.toml / MANIFEST.in live at the repo root
# since the post-#607 restructure.
COPY python /src/python
COPY third_party /src/third_party
COPY include /src/include
COPY lib /src/lib
COPY cmake /src/cmake
COPY bin /src/bin
COPY test /src/test
COPY unittest /src/unittest
COPY CMakeLists.txt pyproject.toml setup.py MANIFEST.in LICENSE README.md /src/

# Build wheel with MAX_JOBS capped to reduce peak RAM. Spike timing on a
# 4-core builder: ~36 min wall.
# FLAGTREE_DEFAULT_BACKENDS=nvidia,amd matches the historical package
# contents and keeps the tileir backend (GCC >= 13 + cuda-tile
# submodule) out of the distro build.
# The trailing rm keeps only /wheels in this layer: the CMake build
# tree and the LLVM tarball cache (~/.triton) would otherwise add
# several GB and push CI runners into ENOSPC.
RUN unset FLAGTREE_BACKEND && \
    JSON_SYSPATH=/usr \
    FLAGTREE_DEFAULT_BACKENDS=nvidia,amd \
    MAX_JOBS=4 python -m pip wheel . --no-build-isolation --no-deps -w /wheels -v && \
    ls -lh /wheels/ && \
    test -n "$(ls /wheels/flagtree-*.whl 2>/dev/null)" && \
    rm -rf /src/build /root/.triton

# ---------- Stage 2: assemble the .deb ----------
FROM ${DEB_BASE_IMAGE} AS deb-assembler
SHELL ["/bin/bash", "-o", "pipefail", "-c"]

ENV DEBIAN_FRONTEND=noninteractive
ENV PIP_ROOT_USER_ACTION=ignore

RUN apt-get update && apt-get install -y --no-install-recommends \
        build-essential \
        debhelper dh-python python3-all python3-pip python3-setuptools \
        python3-wheel devscripts fakeroot lintian \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

WORKDIR /build
COPY packaging/debian /build/debian
COPY --from=wheel-builder /wheels /build/dist

# debian/source/format = "3.0 (native)" -> no orig.tar.gz needed.
ENV WHEEL_DIR=/build/dist

RUN dpkg-buildpackage -us -uc -b && \
    ls -lh /python3-flagtree-*.deb

# Run lintian against the produced .deb — surface packaging warnings
# (unused-license-paragraph, no-manual-page, missing-build-dependency, etc.)
# in the build log without failing the build.
RUN lintian --info --display-info /python3-flagtree-*.deb || true

# Smoke test: install the freshly built deb and import the package.
# Catches the "installs fine, fails at import" class (missing libs,
# bad rpath, glibc mismatch) that dpkg-buildpackage alone cannot see.
RUN apt-get update && \
    apt-get install -y --no-install-recommends /python3-flagtree-*.deb && \
    python3 -c "import triton; print(getattr(triton, '__version__', 'import ok'))" && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

# ---------- Stage 3: just the .deb output ----------
FROM scratch AS deb-output
COPY --from=deb-assembler /python3-flagtree-*.deb /output/
COPY --from=deb-assembler /flagtree_*.changes /output/