=encoding UTF-8

=head1 NAME

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

=head1 SYNOPSIS

B<deb-build-artifact-gather> B<collect-into> F</desired/output/directory> [B<from-chroot> F</path/to/chroot>]

=head1 DESCRIPTION

The B<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:

=over 4

=item -

Chroot providers such as B<sbuild> or other build wrapping tools (such as B<debuild>). These are
expected to perform a bit of setup, call B<deb-build-artifact-gather> with the relevant options.
The setup includes setting B<DEB_ARTIFACTS_EXTRACTION_IPC_DIR> such that the build tools and
B<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 B<deb-build-artifact-gather> is called from the host system.

=item -

Standard build tools like B<debhelper> and B<debputy>. These tools can provide hints to
B<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 B<DEB_ARTIFACTS_EXTRACTION_IPC_DIR>.

=back

=head1 EXAMPLES

Minimal example of collection usage in shell for running B<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 B<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, B<setup-chroot-dir> and B<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.

=cut
