Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

415 lines (414 sloc) 10.941 kb
.\"
.\" FreeBSD pkg - a next generation package for the installation and maintenance
.\" of non-core utilities.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\"
.\" @(#)pkg.8
.\" $FreeBSD$
.\"
.Dd July 11, 2012
.Dt PKG-SEARCH 8
.Os
.Sh NAME
.Nm "pkg search"
.Nd search package repository catalogues
.Sh SYNOPSIS
.Nm
.Op Fl egxX
.Op Fl r Ar repo
.Op Fl S Ar search
.Op Fl L Ar label
.Op Fl M Ar mod
.Ar pattern
.Nm
.Op Fl cDdefgopqXx
.Op Fl r Ar repo
.Ar pattern
.Sh DESCRIPTION
.Nm
is used for searching package repository catalogues.
Packages available for installation can be matched by name, by name
and version, by origin or by text in the package comments or package
descriptions.
The output defaults to displaying the field matched by the search
term, but any of the searchable fields may be displayed.
The output may be modified to additionally show many other package
data available from the repository catalogues.
.Pp
It is recommended to update the local copies of the repository
catalogues before running
.Nm .
See
.Xr pkg-update 8 .
Package repositories are defined in the
.Fa pkg.conf
file; see
.Xr pkg.conf 5.
.Sh OPTIONS
The following options are supported by
.Nm :
.Bl -tag -width F1
.It Fl c
Search for packages with comment text matching
.Ar pattern .
Equivalent to
.Fl "S comment" .
.It Fl D
Display the list of packages depended on by each matched package.
Equivalent to
.Fl "M depends-on" .
.It Fl d
Search for packages with description text matching
.Ar pattern .
Equivalent to
.Fl "S description" .
.It Fl e
.Ar pattern
should be an exact match against the search field.
.It Fl f
Show ``full'' information about the package.
Equivalent to
.Fl "M full" .
.It Fl g
Treat
.Ar pattern
as a shell globbing expression.
The glob pattern must match the entire field being seached.
.It Fl L Ar label
Select which identifying label is printed for each matched package,
unless
.Fl q
is used.
Several different fields from the repository catalogue database may be
used to search on, or to generate the label, as indicated by the
.Ar label
argument.
See the
.Qq Sx Search and Label Options
section for details.
If unspecified,
.Ar label
is set to the same as the value searched via the
.Fl S Ar search
option.
.It Fl M Ar mod
Modify the output by adding an additional field to the result.
Multiple fields can be added by using additional
.Fl M Ar mod
flags.
See the
.Qq Sx Output Modifier Options
section for details.
.It Fl o
List packages by origin for each package matching
.Ar pattern .
Equivalent to
.Fl "L origin" .
.It Fl p
Display the package installation prefix for each matched package.
Equivalent to
.Fl "M prefix" .
.It Fl q
Be ``quiet''.
Produce less output.
In particular don't show an identifying label field for each package.
.It Fl r Ar repo
In multi-repo mode, select only the repository catalogue from
.Sy repo
to search.
By default all known repository catalogues are searched.
.It Fl S Ar search
Specify the field to search the repository catalogue on.
If unspecified, searches on
.Ar pkg-name
unless the search term contains a
.Sy /
character, when it searches on port
.Ar origin .
Output will be sorted in order of the
.Ar search
field.
See the
.Qq Sx Search and Label Options
sections for more details.
.It Fl s
Display the installed size of matched packages.
Equivalent to
.Fl "M size" .
.It Fl X
Treat
.Ar pattern
as an extended regular expression.
Matches any substring of the search field unless explicit beginning
or ending anchor terms are used.
.It Fl x
Treat
.Ar pattern
as a regular expression.
This is the default.
Matches any substring of the search field unless explicit beginning
or ending anchor terms are used.
.El
.Ss Search and Label Options
The following database fields (or composites of several fields) can
be used both for searching for a match to the given
.Ar pattern
and as identifying labels for the block of output for each package.
.Bl -tag -width 2n
.It Sy comment
The one line comment field describing the port, derived from the
.Cm COMMENT
variable in the port's
.Fa Makefile .
When chosen as a label option, the output format will additionally
include the packge name, equivalent to
.Fl "L pkg-name"
.Fl "M comment" .
When chosen as a search option, only the
.Sy comment
field is used for sorting the output.
.It Sy description
The multi-line package description from the
.Fa pkg-descr
file in the port.
This does include the
.Cm WWW
URL reference, if any, from that file.
When chosen as a label option, the output format will additionally
include the package name, equivalent to
.Fl "L pkg-name"
.Fl "M description" .
When chosen as a search option, only the
.Sy description
field is used for sorting the output.
.It Sy name
The name of the package, derived from the
.Cm PORTNAME
variable in the port's
.Fa Makefile .
.It Sy origin
The port origin, in the format
.Fa category/port ,
that the package was compiled from.
.It Sy pkg-name
The package name in the format
.Sy name Ns - Ns Cm version .
The same as the
.Cm PKGNAME
variable in the port's
.Fa Makefile .
.El
.Pp
Any unambiguous prefix of the label name may be used on the command line.
Thus
.Fl "Sd" ,
.Fl "S descr"
and
.Fl "S description"
are all equivalent.
.Ss Output Modifier Options
Additional data from the repository catalogue to print for each matched
package.
Multiple output modifiers can be combined.
Where more than one output field is required, either because multiple
.Fl M Ar mod
options were given, or one or more
.Fl M Ar mod
option was combined with the
.Fl "L comment"
or
.Fl "L description"
options, then each output field will be tagged with the field name.
.Bl -tag -width 2n
.It Sy arch
The architecture string indicating what OS version and CPU architecture
the package is suitable for.
For example,
.Ar freebsd:9:x86:64
indicates a package suitable for FreeBSD 9.x running on an amd64 processor,
while
.Ar freebsd:*
indicates an architecture independent package suitable for any version of
FreeBSD.
.It Sy categories
All categories, real and virtual, the underlying package belongs to,
derived from the
.Cm CATEGORIES
variable in the port's
.Fa Makefile .
.It Sy comment
The one line comment field describing the port, derived from the
.Cm COMMENT
variable in the port's
.Fa Makefile .
.It Sy depends-on
The list of packages the named package depends on.
Dependency packages are listed in the format
.Sy name Ns - Ns Cm version
one per line.
If the port has no dependencies, nothing will be output for
this field, including suppressing the tag name when multiple
output fields are requested.
.It Sy description
The multi-line package description from the
.Fa pkg-descr
file in the port.
This does include the
.Cm WWW
URL reference, if any, from that file.
.It Sy full
Show a standard set of fields, equivalent to a combination of the
.Sy name ,
.Sy version ,
.Sy origin ,
.Sy prefix ,
.Sy repository ,
.Sy categories ,
.Sy license ,
.Sy maintainer ,
.Sy www ,
.Sy comment ,
.Sy options ,
.Sy shared-libs ,
.Sy size ,
.Sy pkg-size
and
.Sy descr
fields, in that order.
.It Sy licenses
Displays a list of all the licenses the package is relesed under on a
single line.
Where more than one license applies, indicate if the terms of all
licenses should apply
.Sy (&)
or if one or more licenses may be selected out of those available
.Sy (|) .
.It Sy maintainer
Display the maintainer's e-mail address.
.It Sy name
Display the port name, which is derived from the
.Cm PORTNAME
variable in the port's
.Fa Makefile .
.It Sy options
Displays a list of the port options and their state (
.Sy on
or
.Sy off )
when the package was built.
If the package does not have any options to set, nothing will be
output for this field, including suppressing the tag name when
multiple output fields are requested.
.It Sy pkg-size
Display the size of the compressed package tarball, i.e. how much would
need to be downloaded from the repository.
.It Sy prefix
Display the installation prefix for the package, usually
.Fa /usr/local .
.It Sy repository
Displays the repository label and the corresponding base Url for the
repository.
In multi-repo mode, the repository label and URL are one of the pairs
defined in
.Fa pkg.conf .
In normal mode the label is always ``remote'', and the URL is the
value of
.Cm PACKAGESITE .
.It Sy required-by
Displays all of the packages in the repository that require the named
package as a dependency.
Dependency packages are listed in the format
.Sy name Ns - Ns Cm version
one per line.
If the no other packages require the named package, nothing will be
output for this field, including suppressing the tag name when
multiple output fields are requested.
.It Sy shared-libs
If the package contains dynamically linked FreeBSD ELF binaries,
display a list of all of the shared libraries other than those from
the base system required for those binaries to run.
Shared libraries for foreign (e.g. Linux) binaries run
under emulation will not be displayed.
If the package does not require any shared libraries, nothing will be
output for this field including suppressing the tag name when multiple
fields are requested.
.It Sy size
Display the total amount of filesystem space the package files will
take up once unpacked and installed.
.It Sy url
Display the URL that would be used to download the package from the
repository.
.It Sy www
Display the general URL, if any, for the project developing the
software used in the package.
This is extracted from the
.Fa pkg-descr
file in the port.
.El
.Pp
Any unambiguous prefix of the modifier name may be used on the command
line.
Thus
.Fl "Mm" ,
.Fl "M maint"
and
.Fl "M maintainer"
are all equivalent,
but you need to use at least
.Fl "M si"
and
.Fl "M sh"
to distinguish
.Cm size
from
.Cm shared-libs .
.Sh ENVIRONMENT
The following environment variables affect the execution of
.Nm .
See
.Xr pkg.conf 5
for further description.
.Bl -tag -width ".Ev NO_DESCRIPTIONS"
.It Ev PACKAGESITE
.It Ev PKG_DBDIR
.It Ev PKG_MULTIREPOS
.El
.Sh FILES
See
.Xr pkg.conf 5 .
.Sh SEE ALSO
.Xr pkg 8 ,
.Xr pkg-add 8 ,
.Xr pkg-audit 8 ,
.Xr pkg-autoremove 8 ,
.Xr pkg-backup 8 ,
.Xr pkg-check 8 ,
.Xr pkg-clean 8 ,
.Xr pkg-create 8 ,
.Xr pkg-delete 8 ,
.Xr pkg-fetch 8 ,
.Xr pkg-info 8 ,
.Xr pkg-install 8 ,
.Xr pkg-query 8 ,
.Xr pkg-register 8 ,
.Xr pkg-repo 8 ,
.Xr pkg-rquery 8 ,
.Xr pkg-set 8 ,
.Xr pkg-shell 8 ,
.Xr pkg-shlib 8 ,
.Xr pkg-stats 8 ,
.Xr pkg-update 8 ,
.Xr pkg-updating 8 ,
.Xr pkg-upgrade 8 ,
.Xr pkg-version 8 ,
.Xr pkg-which 8 ,
.Xr pkg.conf 5
Jump to Line
Something went wrong with that request. Please try again.