pkgdev

From Gentoo Wiki
Jump to:navigation Jump to:search

pkgdev is a collection of tools for Gentoo development.

Installation

USE flags

USE flags for dev-util/pkgdev Collection of tools for Gentoo development

doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
Data provided by the Gentoo Package Database · Last update: 2024-04-14 17:23 More information about USE flags

Emerge

root #emerge --ask dev-util/pkgdev

Configuration

Upstream's documentation describes the config file format and locations.

The DEFAULT section in the config will apply to all repositories unless overridden by a later section.

For example, a configuration file for the current user:

FILE ~/.config/pkgdev/pkgdev.conf
[DEFAULT]
# Always run 'pkgcheck scan --commits' at the point of commit
# The default is not to do this (for performance) and instead runs on 'pkgdev push'
commit.scan = true

# Add a 'Signed-off-by' tag to all commits, regardless of repository
commit.signoff = true

# Ask before creating a commit with detected serious QA issues
push.ask = true

To enable adding a signoff (not the same as PGP signing) automatically only for the gentoo repository:

FILE ~/.config/pkgdev/pkgdev.conf
[gentoo]
commit.signoff = true

Usage

The upstream repository covers usage briefly.

pkgdev has the following subcommands:

  • pkgdev commit - uses to commit the staged changes in the current directory, generates a smart commit message, ensures the Manifest is regenerated, and runs pkgcheck scan if configured to do so (not by default, see above)
    • pkgdev commit -e - same as above but opens $EDITOR to edit the generated commit message
    • pkgdev commit ... - any unknown arguments are passed directly to git, so check git(1).
  • pkgdev manifest - regenerates the Manifest for ebuilds in the current directory.
  • pkgdev push - makes final QA checks (runs pkgcheck scan and aborts on fatal errors) before running git push automatically
  • pkgdev mask - used for last-riting (removing) packages

Examples

The most common pattern is to enter a repository, navigate to a package (using app-misc/scrub as an example), make some changes, and run pkgdev commit, like so (example here is to bump/update a version of an ebuild):

user $cd ~/git/gentoo/app-misc/scrub
user $sudo emerge -av1o --with-test-deps app-misc/scrub
user $cp scrub-2.6.0.ebuild scrub-2.6.1.ebuild
user $pkgdev manifest
user $$EDITOR scrub-2.6.1.ebuild
user $ebuild scrub-2.6.1.ebuild clean test install merge
user $git add scrub-2.6.1.ebuild && pkgdev commit 
app-misc/scrub
  DeprecatedEapi: version 2.6.0: uses deprecated EAPI 6
  RedundantVersion: version 2.6.0: slot(0) keywords are overshadowed by version: 2.6.1
  DeprecatedEapi: version 2.6.1: uses deprecated EAPI 6
[master 65b81235dc06d] app-misc/scrub: add 2.6.1
 2 files changed, 17 insertions(+)
 create mode 100644 app-misc/scrub/scrub-2.6.1.ebuild

Troubleshooting

pkgdev tries to use an invalid commit hash

If you get an error similar to this one, e.g. when using the commit sub-command

user $pkgdev commit 
pkgdev commit: error: failed running git log: fatal: Invalid revision range 7d50e72c9ce20d1dfdd730d26e9695989c2f9ca2..origin/HEAD

It's probably related to caching issues (e.g. [1]). One way to workaround it is to clear the cache while within the affected repository:

user $pkgcheck cache -R

pkgdev doesn't sign-off my commits

pkgdev does not sign-off ('Signed-off-by' trailer) commits by default for any repo, following git upstream behavior, to encourage a conscious decision to sign off.

To enable automatic sign-offs per repository or globally, see Pkgdev#Configuration. pkgdev only uses what git is configured to use.

pkgdev uses new /var/cache/distfiles directory unexpectedly

See also the pkgcheck article.

For systems not migrated to the modern repository data locations, pkgdev manifest may try write to /var/cache/distfiles unexpectedly. This is because pkgcore doesn't read /usr/share/portage (which is where Portage's defaults reside).

There are three solutions:

  1. Set manifest.distdir = /usr/portage/distfiles in ~/.config/pkgdev/pkgdev.conf, or
  2. Set DISTDIR=/usr/portage/distfiles in /etc/portage/make.conf, or
  3. Migrate the repository locations.

git signing errors

When committing in a repository (like ::gentoo) with 'sign-commits = true' in metadata/layout.conf, pkgdev will ask git to sign commits. This requires a GPG key.

There are two options:

  1. Generate a key and configure git to use it
  2. non-developers committing to Gentoo via pull requests or patches don't actually need a key and can disable signing, as only the person pushing to the repository needs a key at present. They can locally set sign-commits = false in metadata/layout.conf but of course this change should not be committed. This will prevent pkgdev from trying to sign commits.

See Gentoo git workflow#GPG configuration for details on how to generate a key and debug GPG errors. pkgdev only uses what git is configured to use.

If errors persist, run GIT_TRACE=1 pkgdev commit ... and run the gpg ... command mentioned in its output manually to further debug.

See also

  • Standard git workflow — describing a modern git workflow for contributing to Gentoo, with pkgcheck and pkgdev
  • Gentoo git workflow — outlines some rules and best-practices regarding the typical workflow for ebuild developers using git.
  • pkgcheck — a pkgcore-based QA utility for ebuild repos.

External resources

Retrieved from "https://wiki.gentoo.org/index.php?title=Pkgdev&oldid=1268942"