Skip to content

apt.md

Latest commit

 

History

History
117 lines (81 loc) · 4.84 KB

apt.md

File metadata and controls

117 lines (81 loc) · 4.84 KB

apt extensions

apt

apt = use_extension("@rules_distroless//apt:extensions.bzl", "apt")
apt.install(lock, manifest, mergedusr, nolock, package_template, resolve_transitive)

TAG CLASSES

install

Module extension to create Debian repositories.

Create Debian repositories with packages "installed" in them and available to use in Bazel.

Here's an example how to create a Debian repo:

apt = use_extension("@rules_distroless//apt:extensions.bzl", "apt")
apt.install(
    name = "bullseye",
    lock = "//examples/apt:bullseye.lock.json",
    manifest = "//examples/apt:bullseye.yaml",
)
use_repo(apt, "bullseye")

Note that, for the initial setup (or if we want to run without a lock) the lockfile attribute can be omitted. All you need is a YAML manifest:

version: 1

sources:
  - channel: bullseye main
    url: https://snapshot-cloudflare.debian.org/archive/debian/20240210T223313Z

archs:
  - amd64

packages:
  - perl

apt.install will parse the manifest and will fetch and install the packages for the given architectures in the Bazel repo @<NAME>.

Each <PACKAGE>/<ARCH> has two targets that match the usual structure of a Debian package: data and control.

You can use the package like so: @<REPO>//<PACKAGE>/<ARCH>:<TARGET>.

E.g. for the previous example, you could use @bullseye//perl/amd64:data.

Lockfiles

As mentioned, the macro can be used without a lock because the lock will be generated internally on-demand. However, this comes with the cost of performing a new package resolution on repository cache misses.

The lockfile can be generated by running bazel run @bullseye//:lock. This will generate a .lock.json file of the same name and in the same path as the YAML manifest file.

If you explicitly want to run without a lock and avoid the warning messages set the nolock argument to True.

Best Practice: use snapshot archive URLs

While we strongly encourage users to check in the generated lockfile, it's not always possible because Debian repositories are rolling by default. Therefore, a lockfile generated today might not work later if the upstream repository removes or publishes a new version of a package.

To avoid this problems and increase the reproducibility it's recommended to avoid using normal Debian mirrors and use snapshot archives instead.

Snapshot archives provide a way to access Debian package mirrors at a point in time. Basically, it's a "wayback machine" that allows access to (almost) all past and current packages based on dates and version numbers.

Debian has had snapshot archives for 10+ years. Ubuntu began providing a similar service recently and has packages available since March 1st 2023.

To use this services simply use a snapshot URL in the manifest. Here's two examples showing how to do this for Debian and Ubuntu:

For more infomation, please check https://snapshot.debian.org and/or https://snapshot.ubuntu.com.

Attributes

Name Description Type Mandatory Default
lock The lock file to use for the index. Label optional None
manifest The file used to generate the lock file Label required
mergedusr Whether packges should be normalized following mergedusr conventions. Turning this on might fix the following error thrown by docker for ambigious paths: duplicate of paths are supported. For more context please see https://salsa.debian.org/md/usrmerge/-/raw/master/debian/README.Debian?ref_type=heads Boolean optional False
nolock If you explicitly want to run without a lock, set it to True to avoid the DEBUG messages. Boolean optional False
package_template (EXPERIMENTAL!) a template file for generated BUILD files. Label optional None
resolve_transitive Whether dependencies of dependencies should be resolved and added to the lockfile. Boolean optional True