deb-build-artifact-gather
=========================

The `deb-build-artifact-gather` is a tool for gathering build time artifacts
from Debian builds.

Most Debian builds are performed inside a chroot or container to segregate the
build and its dependencies from the host system. This is desirable to ensure
that the build cannot taint the host and vice versa. In many cases it also acts
as a security boundary between the two. However, there are a multitude of
different methods for creating this context boundary, and they all have different
behaviors, which has made it non-trivial for gather arbitrary build artifacts
from the builder side.

This is where `deb-build-artifact-gather` comes in. It provides a standardized way
to request artifacts to be extracted. The build orchestration tooling is responsible
for invoking `deb-build-artifact-gather` at the right time with parameters. The
`deb-build-artifact-gather` will then collect relevant artifacts and provide them
to the build orchestration tooling, so they can be published.

Prerequisites
-------------

On a (modern) Debian system, you can install prerequisites via the following apt command.

     apt build-deps -y .

This includes the minimal development stack used to build the `deb-build-artifact-gather`
package.  Have a look at `debian/control` if you want the minimal dependencies for
running `deb-build-artifact-gather` directly.


Running deb-build-artifact-gather from source
---------------------------------------------

While developing, it is useful to run `deb-build-artifact-gather` directly from the source tree
without having to build first.  This can be done by invoking the `deb-build-artifact-gather.sh`
command in the source root on any system that has `#!/bin/sh`.

Which only relies on the `PYTHONPATH` environment variable being set correctly and having `python3`
in `PATH`.

How to use / example run:
-------------------------

With `sbuild/0.91.6` or later:

```shell
sbuild \
   --post-build-commands='unshare --map-auto --map-root-user --wd %SBUILD_CHROOT_DIR/%SBUILD_PKGBUILD_DIR deb-build-artifact-gather collect-into /tmp/foo.tar.gz --exit-code-on-empty-collection 0 from-chroot-dir %SBUILD_CHROOT_DIR' \
   --post-build-failed-commands='unshare --map-auto --map-root-user --wd %SBUILD_CHROOT_DIR/%SBUILD_PKGBUILD_DIR deb-build-artifact-gather collect-into /tmp/foo.tar.gz --exit-code-on-empty-collection 0 from-chroot-dir %SBUILD_CHROOT_DIR' \
   ...
```

The `...` is a placeholder for your regular options. The example runs `deb-build-artifact-gather`
on both success and failure on the assumption collection is always desired. If collection is
only relevant on failure, use only the `--post-build-failed-commands`.

Assuming no chroot boundry:

```shell
    # "$(mktemp -d)" is a perfectly fine alternative to DEB_ARTIFACTS_EXTRACTION_IPC_DIR 
    DEB_ARTIFACTS_EXTRACTION_IPC_DIR="../artifact-variable-dir"
    export DEB_ARTIFACTS_EXTRACTION_IPC_DIR

    cd /path/to/unpacked-source-root
    dpkg-buildpackage

    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 -f ../artifacts-from-build.tar.xz
    fi

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

# What is collected and how to control what is collected?

The `deb-build-artifact-gather` has some built-in patterns and can add patterns from the package
itself (see `X-Build-Time-Aux-Artifacts` in [INTERFACE-PACKAGE-MAINTAINER.md]). It will gather
anything matching those patterns if anything matches them at all. It is possible to choose
which rules apply via the `--tags` option.

The collection does not factor in whether the build was successful. Partly because it is not
trivially available in all cases. As an example, `sbuild` has distinct hooks for successful
vs. failed builds, so the caller has to do two command lines either way. The other reason is
that there is no obvious way to map success / failure to selected patterns as some use-cases
still need certain artifacts on success.

In summary:

 * Everything is collected by default.
 * There are options to choose what is being collected via `--tags`
 * Success vs. failure is for the invoker to deal with.

# Interface docs

If you are looking for how to interface with **deb-build-artifact-gather**, then please review:

 * [INTERFACE-CHROOT-PROVIDER.md](docs/INTERFACE-CHROOT-PROVIDER.md) if you are maintaining a build
   wrapping tool like **sbuild**, **pbuilder**, or **debuild**
 * [INTERFACE-PACKAGE-HELPER.md](docs/INTERFACE-PACKAGE-HELPER.md) if you are maintaining a package
   helper like **debhelper** or **debputy**.
 * [INTERFACE-PACKAGE-MAINTAINER.md] if you are a maintainer of a package.

# Communication channels:

The following communication channels are available:

 * Using the <https://salsa.debian.org/debian/deb-build-artifact-gather> features, such as issues.
   Generally, these will be available to the public. While confidential issues can be filed, please
   note that all Debian Developers can read them.
 * Filing bugs via `reportbug deb-build-artifact-gather` to Debian's Bug Tracking System. Note all
   such bugs will have public archives.
 * Mail to Debian Build Artifact Gather Maintainers <deb-build-artifact-gather@packages.debian.org>.
   Please note that no public archive is available but anyone can subscribe via tracker.debian.org.

## Security policy and issues

Please see [SECURITY.md](SECURITY.md) for details on that matter.


[INTERFACE-PACKAGE-MAINTAINER.md]: docs/INTERFACE-PACKAGE-MAINTAINER.md
