PACKAGES-SPECS(7)

📦 in nixpkgs unstable

💅 packages-specs(7) — like, the whole guide to binary package name specs

okay bestie so this is from the Miscellaneous Information Manual (packages-specs(7)), and it's literally the entire tea on how package names work. grab a drink, we're getting into it 🍓

✨ NAME ✨

packages-specs — binary package names specifications 🎀

💖 DESCRIPTION 💖

so every package has a name, right? and that name is made of at most three parts, periodt:

stem-version[-flavors]

🌸 the stem

The stem part is the whole identity of the package. It can have some dashes in it, but ngl its form is mostly conventional, like there's a vibe everyone follows. For instance, japanese packages usually start with a ja prefix, e.g. "ja-kterm-6.2.0" 🦋

🌈 the version

The version part starts at the first digit that follows a -, and goes on up to the following -, or to the end of the package name — whichever comes first, no cap.

Then it's followed by the (possibly empty) [-flavors] part.

So like, the way that this works out: version numbers should always start with a digit and cannot contain a -, whereas flavors should never start with a digit. iykyk 👑

🎀 version numbers: the rules

All packages must have a version number, fr fr. Normally the version number directly matches the original software distribution version number, or the release date. But if there are substantial changes in the OpenBSD package, a patch level marker should be appended, e.g. p0, p1 ...

Example time bestie: say the screen package for release 2.8 was named "screen-2.9.8", and then an important security patch led to a newer package. That new package would be called "screen-2.9.8p0". 💀 Obviously these specific markers are reserved for OpenBSD purposes. See REVISION in bsd.port.mk(5).

🧚 version comparison (dewey notation)

Version comparison is done using the dewey notation with a few specific rules:

  • The version number is cut into separate parts on each dot .. Therefore, replace other upstream separators such as _ or - with dots.
  • Comparison checks each part in turn, and the first part that differs yields a comparison result.
  • If parts are numbers, they are compared numerically.
  • Parts can also be numbers with an optional letter appended. The numbers are compared numerically, and in case of equality, the letter makes the difference.
  • Other parts are compared alphabetically.
  • The last part may contain an extra suffix matching rc[N], alpha[N], beta[N], pre[N], or pl[N], with N an optional number. These correspond to traditional notations for ‘release candidate’, ‘alpha version’, ‘beta version’, ‘pre-release’, ‘patch-level’, and are ordered accordingly, e.g. alpha is oldest, then beta, rc and pre are next (and non-comparable to one another), then normal version, and finally pl.
    • "foo-1.01" is equal to "foo-1.1", which can lead to surprises.. 😭
    • "foo-1.001" is older than "foo-1.002", which in turns is older than "foo-1.0010"
    • "foo-1.0rc2" is not comparable to "foo-1.0pre3"
    • "bar-1.0alpha5" is older than "bar-1.0beta3"
    • "bar-1.0beta3" is older than "bar-1.0rc1"
    • "baz-1.0" is older than "baz-1.0pl1"

🫶 the v0 / v1 version style marker

In some rare cases, a change to a port would cause the version number to compare as older than the previous version. 💀 This happens if an update is reverted, if upstream's numbering scheme changes completely, or if their usual scheme does not align with the one used by OpenBSD.

So a version style marker, of the form v0, v1 ... can be appended to the version number (after the patch level) to denote the new numbering scheme. This marker is added by setting EPOCH in the port Makefile, and it takes precedence over the regular package version. See bsd.port.mk(5).

🦋 flavors

Flavored packages will also contain a list of flavors after the version identifier, in a canonical order determined by FLAVORS in the corresponding port's Makefile. For instance, kterm has an xaw3d flavor: "ja-kterm-xaw3d" ✨

Note that, to uniquely identify the version part, no flavor shall ever start with a digit. 🙈

Usually, flavored packages are slightly different versions of the same package that offer very similar functionalities. Same energy, different fit.

Also note that user commands have short-hands for installing new packages that are substantially different from formal packages-specs (branch specifications and explicit flavoring). The special character % is explicitly forbidden in formal package names and specs. 🚫

pkg_check-version(1) can be used to verify the ordering of package names. love that for us 💅

💀 CONFLICTS 💀

Most conflicts between packages are handled on a package name basis. Unless the packages have been specially prepared, it is normally not possible to install two packages with the same stem. it's giving "there can only be one" 👑

Note that the stem ends at the version part. So, for instance, "kdelibs-1.1.2" and "kdelibs-2.1.1" conflict. But "openldap-2.0.7" and "openldap-client-2.0.7" don't. Neither do "qt-1.45" and "qt2-3.0". see? different stems, different main characters 🌈

🌟 DEPENDENCIES 🌟

Packages may depend on other packages, as specified by their port's Makefile, in a BUILD_DEPENDS, LIB_DEPENDS, TEST_DEPENDS or RUN_DEPENDS. All those conform to

[pkgspec:]pkgpath

The pkgpath(7) part of the dependency is always used to obtain the default dependency for the given package (the package that will be built and installed if no package is found). The corresponding package name is also used as a package specification, after removing any version and flavor requirements.

Without a pkgspec: part, by default, any package with the right stem will do: in effect, the pkgspec used is stem-*. slay, low effort 💅

In OpenBSD 4.9, the dependent port may override this default, and set PKGSPEC to achieve a more restrictive default. For instance, databases/db/v3 sets the default to "PKGSPEC = db->=3,<4" to avoid collision with databases/db/v4.

Be extra cautious with this functionality: this tweaks the depends line for any including package, thus usually requiring a version bump, and is in general only required for very messy cases where several incompatible versions of the same software coexist as packages with the same stem. 😭

An explicit specification such as "png-1.0.7" may be used to ask for a more specific version number. Version numbers may also include ranges, separated by commas — so for instance, "foo->=1.3" would match any foo with version at least 1.3, and "foo->=1.3,<=1.5" would match any version of foo between 1.3 and 1.5, inclusive. 🎯

As a convenience, the ports tree recognizes a specification that starts with STEM, and will replace this with the correct stem, which can be useful for embarrassingly long package names. (embarrassingly long 😭 we've all been there)

As another convenience, the ports tree recognizes constructs like "graphics/png>=1.2.0" and transforms it into "STEM->=1.2.0:graphics/png". More specifically, package paths never contain <, >, or =, and those characters trigger the transform. iconic behavior honestly ✨

🎀 flavors in dependencies

If the flavor specification is left blank, any flavor will do. Note that most default package names don't contain flavor specification, which means that any flavor will do. For instance, in

LIB_DEPENDS = graphics/aalib

both "aalib-1.2" and "aalib-1.2-no_x11" will do. 🫶

  • To restrict the specification to packages that match flavor f, append -f.
  • To restrict the specification to packages that do not match flavor f, append -!f.

In the preceding case, one may use

LIB_DEPENDS = aalib-*-!no_x11:graphics/aalib

to ensure the no_x11 flavor is not picked. 🚫🖥️

🧚 DEPENDENCIES RESOLUTION 🧚

Several packages may be specified for a dependency: "foo-*|bar-*" will match either any version of package foo, or any version of package bar. In the general case, each package holds a tree of dependencies. Resolution occurs at pkg_add(1) time, and all dependencies are tracked only as far as needed. no overthinking, main character energy only 💅

For instance, if package "foo-1.0" depends on either "bar-*" or "fuzz-*", and "bar-2.0" depends on "toughluck-*", pkg_add(1) will first check whether "bar-*" or "fuzz-*" is installed. If either is there, the "toughluck-*" dependency will never be examined. It would only be used in the case where neither "bar-*" nor "fuzz-*" are present, thus pkg_add(1) would decide to bring in "bar-2.0", and so would check on "toughluck-*". 🦋

👀 SEE ALSO 👀

pkg_add(1), pkg_check-version(1), bsd.port.mk(5), library-specs(7), packages(7), pkgpath(7), ports(7)

go read them, bestie, they're all part of the lore 📚

⭐ HISTORY ⭐

Support for a more complex form of those package specifications first appeared in OpenBSD 2.9. The current simplified form was introduced in OpenBSD 4.9. glow-up era 🎀

okay that's the whole page!! this one's from Debian, dated October 9, 2024, and the page is PACKAGES-SPECS(7) — and yeah, that's the vibe check, you ate it, periodt 💅✨🫶

📦 where this page comes from