deb-build-artifact-gather(1)

NAME
deb-build-artifact-gather - Extract artifacts from a Debian package build

SYNOPSIS
deb-build-artifact-gather collect-into /desired/output/directory [from-chroot /path/to/chroot]

DESCRIPTION
The deb-build-artifact-gather command provides a standardized way to extract artifacts from a Debian package build. Such artifacts include configure logs, test results, or even Internal Compiler Error (ICE) logs.

The command has the following stakeholders that it interfaces with:

-   Chroot providers such as sbuild or other build wrapping tools (such as debuild). These are expected to perform a bit of setup, call deb-build-artifact-gather with the relevant options. The setup includes setting DEB_ARTIFACTS_EXTRACTION_IPC_DIR such that the build tools and deb-build-artifact-gather has a reliable way to communicate.

    Afterwards, they will be provided with a directory of artifacts to extract. They might also need to perform a bit of clean up when deb-build-artifact-gather is called from the host system.

-   Standard build tools like debhelper and debputy. These tools can provide hints to deb-build-artifact-gather in the form of variable definitions. As an example, they usually know what is the build-dir used.

    They interface via the DEB_ARTIFACTS_EXTRACTION_IPC_DIR.

EXAMPLES
Minimal example of collection usage in shell for running deb-build-artifact-gather inside the chroot:

    # setup chroot, install build depends and enter chroot

    # Any path that is writable to the build process **inside** the chroot. It should either not exist
    # or be an empty directory.
    #
    # "$(mktemp -d)" is a perfectly fine alternative.
    DEB_ARTIFACTS_EXTRACTION_IPC_DIR="../artifact-variable-dir"
    export DEB_ARTIFACTS_EXTRACTION_IPC_DIR

    cd /path/to/unpacked-source-root

    dpkg-buildpackage

    apt-get install -y deb-build-artifact-gather
    if deb-build-artifact-gather collect-into ../artifacts-from-build.tar.xz; then
        # Copy ../artifacts-from-build.tar.xz out of the chroot somehow
        rm -fr ../artifacts-from-build.tar.xz
    fi

    [ -e "${DEB_ARTIFACTS_EXTRACTION_IPC_DIR}"] && rm -fr "${DEB_ARTIFACTS_EXTRACTION_IPC_DIR}"

This example assumes that every command shown is run inside the chroot.

Minimal example of collection usage in shell for running deb-build-artifact-gather outside the chroot:

    # setup-chroot-dir creates the root directory, installs build depends inside it, etc.
    CHROOT_DIR="$(setup-chroot-dir)"

    # Any path that is writable to the build process **inside** the chroot.  It should either not exist
    # or be an empty directory.
    #
    # If you use `mktemp -d` (or similar), then remember to run it **inside** the chroot
    DEB_ARTIFACTS_EXTRACTION_IPC_DIR="../artifact-variable-dir"
    export DEB_ARTIFACTS_EXTRACTION_IPC_DIR

    run-in-chroot "cd /path/to/unpacked-source-root && dpkg-buildpackage"

    cd /host/path/to/unpacked-source-root

    if deb-build-artifact-gather collect-into ../artifacts-from-build from-chroot.tar.xz from-chroot-dir "${CHROOT_DIR} ; then
        # copy ../artifacts-from-build.tar.xz to its desired place as needed.
        rm -fr ../artifacts-from-build.tar.xz
    fi

    [ -e "${DEB_ARTIFACTS_EXTRACTION_IPC_DIR}"] && rm -fr "${DEB_ARTIFACTS_EXTRACTION_IPC_DIR}"

In this example, setup-chroot-dir and run-in-chroot represents the creation of the chroot and explicitly running certain commands inside the chroot. Everything else is run on the host system.