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: 2023-09-22 20:25 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 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.

Note that pkgdev does not use the legacy repoman /etc/portage/make.conf variable SIGNED_OFF_BY (or DCO_SIGNED_OFF_BY) to choose the name. It 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.

Note that pkgdev does not use the legacy repoman /etc/portage/make.conf variable PORTAGE_GPG_KEY to choose the key. It 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.
  • Repoman — a Python program used to enforce a minimal level of quality assurance in ebuilds and related metadata added to ebuild repositories.

External resources

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