Manifest

Generating the Manifest

In the tree, every package has a Manifest file. This file lives in the same directory as the ebuilds for the package. The Manifest file contains digests (the current list can be found in metadata/layout.conf as manifest-hashes) and file size data for every distfile used by the package. This is used to verify integrity upon fetching them.

To generate the Manifest, use ebuild foo.ebuild manifest or pkgdev manifest -m. You may want to set GENTOO_MIRRORS= while calling it to fetch distfiles from their original locations immediately.

Thin and thick Manifests

There are two kinds of Manifest files in Gentoo: thin Manifests that are used in the development repositories, and thick Manifests that are distributed via rsync to end users. Thin Manifests are described above.

Thick Manifests add checksums for all files in the repository, and an OpenPGP signature. This provides both for integrity and authenticity checking when the repository is transmitted over insecure channels. Thick Manifests are automatically generated on Gentoo Infrastructure, and require no specific action from developers.

Updating Manifest files

Updating existing entries within a manifest must be done with care. Upstream changing the tarball in-place without a new filename could be an innocent respin of the tarball, or it could indicate either the previous or the new tarball is malicious.

Developers should diff the old and new versions of the distfile, comparing the two, and note the differences in the commit message updating the Manifest to indicate both what happened (if any context is known) and also what differences between the two distfiles have been ascertained.

Please note that if upstream made any changes affecting the built package or it had substantial differences, you need to also bump the ebuild's revision. Finally, remember to remove the ebuilds that are associated with the old distfile, or regenerate their checksums in Manifest, if there are any. This is necessary because these ebuilds will cause checksum mismatch errors as the checksum recorded in the manifest file no longer matches the computed checksum of the fetched distfile.

Special care is also required with regard to mirrors.