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.