Skip to content

Restructure the package FMRIs and Versions section in the manual #534

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hadfl merged 1 commit into from
May 6, 2026
Merged

Restructure the package FMRIs and Versions section in the manual #534

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
201 changes: 104 additions & 97 deletions src/man/pkg.7
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,32 +18,47 @@ actions, defined by a set of key/value pairs and possibly a data payload.
In many cases, actions are files found in a file system, but they also
represent other installable objects, such as drivers, services, and users.
.Sh PACKAGE FMRIS AND VERSIONS
Each package is represented by a fault management resource identifier (FMRI)
Each package is represented by a fault management resource identifier
.Pq FMRI
with the scheme
.Sy pkg\&: .
The full FMRI for a package consists of the scheme, a publisher, the package
name, and a version string in the following format:
.Bd -literal
pkg://omnios/terminal/tmux@3.1.2-151036.0:20201029T171510Z
A fully qualified FMRI consists of the scheme, a publisher, the package
name, and a version string, as shown in the annotated example below:
.Bd -literal -offset indent
pkg://omnios/terminal/tmux@3.1.2,5.11-151036.0:20201029T171510Z
\e_/ \e____/ \e___________/ \e___/ \e__/ \e______/ \e______________/
| | | | | | |
| | | | | | timestamp
| | | | | branch version
| | | | build version
| | | component version
| | package name
| publisher
scheme
.Ed
.Pp
In this example,
.Sy omnios
is the publisher and
.Sy terminal/tmux
is the package name.
Although the namespace is hierarchical and arbitrarily deep, there is no
enforced containment; the name is essentially arbitrary.
The publisher information is optional, but must be preceded by
.Sy pkg://
if present.
An FMRI that includes the publisher is often referred to as being "fully
qualified." If publisher information is not present, then the package name
should generally be preceded by
The publisher and each version part are described in the sections below.
Each version part beyond the component version is optional and is
identified by its leading separator, so any combination may be present.
.Ss Publisher
A publisher name identifies a person, group of persons, or an organisation
as the source of one or more packages.
To avoid name collisions and help identify the publisher, a best practice
is to use a domain name that represents the entity publishing the packages.
.Pp
The publisher is optional, but if present must be preceded by
.Sy pkg:// .
An FMRI that includes the publisher is referred to as being
.Dq fully qualified .
If the publisher is not present, the package name should generally be
preceded by
.Sy pkg:/ .
.Ss Package name
The package name namespace is hierarchical and arbitrarily deep, but
there is no enforced containment; the name is essentially arbitrary.
.Pp
Packaging clients often allow the scheme of an FMRI to be omitted if it does
not contain publisher information.
Packaging clients often allow the scheme of an FMRI to be omitted if it
does not contain publisher information.
For example,
.Sy pkg:/terminal/tmux
can be written as
Expand All @@ -58,87 +73,83 @@ which would then match packages named
.Sy tmux
or package names ending in
.Sy /tmux .
.Pp
A publisher name identifies a person, group of persons, or an organisation as
the source of one or more packages.
To avoid publisher name collisions and help identify the publisher, a best
practice is to use a domain name that represents the entity publishing the
packages as a publisher name.
.Pp
The version follows the package name, separated by an at sign (@).
The version consists of four sequences of numbers, separated by punctuation.
The elements in the first three sequences are separated by dots, and the
sequences are arbitrarily long.
Leading zeros in version components (for example,
.Pq for example, Sy 01.1 No or Sy 1.01
are not permitted.
Trailing zeros
.Pq for example, Sy 1.10
are permitted.
.Pp
The first part of the version is the component version.
For components tightly bound to the operating system, this is usually the value
of
.Ss Version
The version follows the package name, separated by an at sign
.Pq Sy @ ,
and consists of up to four parts:
.Bl -tag -width "component version "
.It Sy component version
For components tightly bound to the operating system, this is usually the
value of
.Ql uname -r
for that version of the operating system.
For a component with its own development lifecycle, this sequence is a dotted
release number, such as 2.4.10.
.Pp
The second part of the version, which if present must follow a comma
.Pq Sy \&, ,
is the build version.
The build version specifies what version of the operating system the contents
of the package were built on, providing a minimum bound on which operating
system version the contents can be expected to run successfully.
.Pp
The third part of the version, which if present must follow a hyphen
.Pq Sy \- ,
is the branch version.
The branch version is a versioning component that provides vendor-specific
information.
The branch version can be incremented when the packaging metadata is changed,
independently of the component version.
The branch version might contain a build number or other information.
.Pp
The fourth part of the version, which if present must follow a colon
.Pq Sy \&: ,
is a timestamp.
The timestamp represents when the package was published.
.Pp
When performing comparisons between versions, no component of the full version
is considered unless the components to its left are the same.
Thus,
For a component with its own development lifecycle, this sequence is a
dotted release number, such as
.Sy 2.4.10 .
.It Sy build version
Introduced by a comma
.Pq Sy \&, .
This specifies the version of the operating system that the contents of
the package were built against, providing a minimum bound on which
operating system version the contents can be expected to run successfully.
.It Sy branch version
Introduced by a hyphen
.Pq Sy \- .
A vendor-specific versioning component that can be incremented when the
packaging metadata is changed, independently of the component version.
The branch version may contain a build number or other information.
.It Sy timestamp
Introduced by a colon
.Pq Sy \&: .
Represents when the package was published.
.El
.Pp
The component, build, and branch versions consist of one or more
non-negative integers separated by dots; there is no limit on the
number of integers.
Each integer must be written in plain decimal with no leading zero
padding, so
.Sy 01.1
and
.Sy 1.01
are not permitted; they should both be written as
.Sy 1.1 .
.Pp
When comparing versions, no part is considered unless the parts to its
left are equal.
For example,
.Sy 4.3-1
is greater than
.Sy 4.2-7
because
.Sy 4.3
is greater than
.Sy 4.2 ,
.Sy 4.2 ;
and
.Sy 4.3-3
is greater than
.Sy 4.3-1
because
because the component versions are equal but
.Sy 3
is greater than
.Sy 1 .
.Pp
.Ss Abbreviated forms
Many parts of the system, when appropriate, abridge FMRIs when displaying
them, and accept input in shorter forms to reduce the volume of
information displayed or required.
Typically, the scheme, publisher, build version, and timestamp can be
elided.
Sometimes all of the versioning information can be omitted.
.Ss Human-readable versions
The
.Sy pkg.human-version
attribute can be used to provide a human-readable version string.
The value of the
.Sy pkg.human-version
attribute can be provided in addition to the package version described above
for the package FMRI but cannot replace the package FMRI version.
The human-readable version string is only used for display purposes.
See "Set Actions" for more information.
.Pp
Many parts of the system, when appropriate, abridge FMRIs when displaying them,
and accept input in shorter forms to reduce the volume of information displayed
or required.
Typically, the scheme, publisher, build version, and timestamp can be elided.
Sometimes all of the versioning information can be omitted.
attribute can be used to provide a human-readable version string in
addition to the package version described above.
It cannot replace the package FMRI version, and is only used for display
purposes.
See
.Sx Set Actions
for more information.
.Sh ACTIONS
Actions represent the installable objects on a system.
Actions are described in the manifest of a package.
Expand Down Expand Up @@ -189,7 +200,7 @@ developments.
Some attributes cause additional operations to be executed outside of the
packaging context.
These attributes are documented in the
.Sx Actuators
.Sx ACTUATORS
section below.
.Pp
Actions that are installed to a path must not deliver content to any of
Expand Down Expand Up @@ -731,7 +742,7 @@ If that directory contains unpackaged file system objects, those items are
moved into
.Sy $IMAGE_META Ns Pa /lost+found .
See the
.Sx Files
.Sx FILES
section for more information about
.Sy $IMAGE_META .
.Bl -tag -width 6n
Expand Down Expand Up @@ -1024,7 +1035,7 @@ concurrently with the package specifying the dependency.
The dependency is optional, but the version of the dependent package is
constrained.
See
.Sx Constraints and Freezing
.Sx CONSTRAINTS AND FREEZING
below.
.It Sy require-any
Any one of the packages specified by multiple
Expand Down Expand Up @@ -1254,17 +1265,13 @@ A detailed description of the contents and functionality of the package,
typically a paragraph or so in length.
.It Sy pkg.fmri
The name and version of the containing package.
See
.Sx Package FMRIs and Versions
in the
.Sx Description
See the
.Sx PACKAGE FMRIS AND VERSIONS
section.
.It Sy pkg.human-version
The version scheme used by IPS is strict.
See
.Sx Package FMRIs and Versions
in the
.Sx Description
See the
.Sx PACKAGE FMRIS AND VERSIONS
section.
A more flexible version can be provided as the value of the
.Sy pkg.human-version
Expand Down Expand Up @@ -1509,7 +1516,7 @@ However, it must do so explicitly with a glob as accepted by
rather than doing so implicitly by not indicating any instances.
.\"
.El
.Sh MEDIATIORS
.Sh MEDIATORS
A mediator is a name that represents a set of related symbolic or hard links.
If two or more link actions have the same path and mediator name, the user or
the package system selects the link target based on version, implementation, or
Expand Down Expand Up @@ -1649,7 +1656,7 @@ A mirror can be created by removing all subdirectories of a repository except
those named
.Sy file
and their parents.
An origin repository can be also be provisioned as a mirror by using the mirror
An origin repository can also be provisioned as a mirror by using the mirror
mode of
.Xr pkg.depotd 8 .
.\"
Expand Down
Loading