You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 

501 lines
13 KiB

  1. .\"
  2. .\" FreeBSD pkg - a next generation package for the installation and
  3. .\" maintenance of non-core utilities.
  4. .\"
  5. .\" Redistribution and use in source and binary forms, with or without
  6. .\" modification, are permitted provided that the following conditions
  7. .\" are met:
  8. .\" 1. Redistributions of source code must retain the above copyright
  9. .\" notice, this list of conditions and the following disclaimer.
  10. .\" 2. Redistributions in binary form must reproduce the above copyright
  11. .\" notice, this list of conditions and the following disclaimer in the
  12. .\" documentation and/or other materials provided with the distribution.
  13. .\"
  14. .\"
  15. .\" @(#)pkg.8
  16. .\" $FreeBSD$
  17. .\"
  18. .Dd November 18, 2014
  19. .Dt PKG-SEARCH 8
  20. .Os
  21. .Sh NAME
  22. .Nm "pkg search"
  23. .Nd search package repository catalogues
  24. .Sh SYNOPSIS
  25. .Nm
  26. .Op Fl U
  27. .Op Fl r Ar reponame
  28. .Op Fl S Ar search
  29. .Op Fl L Ar label
  30. .Op Fl Q Ar query-modifier
  31. .Op Fl Cegix
  32. .Ar pattern
  33. .Nm
  34. .Op Fl cDdfopqRsU
  35. .Op Fl r Ar reponame
  36. .Op Fl Cegix
  37. .Ar pattern
  38. .Pp
  39. .Nm
  40. .Op Cm --no-repo-update
  41. .Op Cm --repository Ar reponame
  42. .Op Cm --search Ar search
  43. .Op Cm --label Ar label
  44. .Op Cm --query-modifier Ar query-modifier
  45. .Op Cm --{case-sensitive,exact,glob,case-insensitive,regex}
  46. .Ar pattern
  47. .Nm
  48. .Op Cm --{comment,description,depends-on,full,origins,prefix}
  49. .Op Cm --{quiet,raw,size,no-repo-update}
  50. .Op Cm --repository Ar reponame
  51. .Op Cm --{case-sensitive,exact,glob,case-insensitive,regex}
  52. .Op Fl -raw-format Ar format
  53. .Ar pattern
  54. .Sh DESCRIPTION
  55. .Nm
  56. is used for searching package repository catalogues.
  57. Packages available for installation can be matched by name, by name
  58. and version, by origin, or by text in the package comments or package
  59. descriptions.
  60. The output defaults to displaying the field matched by the search
  61. term, but any of the searchable fields may be displayed.
  62. The output may be modified to additionally show many other package
  63. data available from the repository catalogues.
  64. .Pp
  65. Package repository catalogues will be automatically updated whenever
  66. .Nm
  67. is run by a user ID with write access to the package database,
  68. unless disabled by the
  69. .Fl U
  70. flag or setting
  71. .Cm REPO_AUTOUPDATE
  72. to
  73. .Sy NO
  74. in
  75. .Xr pkg.conf 5 .
  76. .Pp
  77. Package repositories are defined in the
  78. .Fa pkg.conf
  79. file or by creating repository definitions in
  80. .Pa /usr/local/etc/pkg/repos.
  81. See
  82. .Xr pkg.conf 5
  83. for details.
  84. .Sh OPTIONS
  85. The following options are supported by
  86. .Nm :
  87. .Bl -tag -width repository
  88. .It Fl C , Cm --case-sensitive
  89. Make the exact
  90. .Fl ( e )
  91. or the regular expression
  92. .Fl ( x )
  93. matching against
  94. .Ar pkg-name
  95. case sensitive.
  96. .It Fl c , Cm --comment
  97. Search for packages with comment text matching
  98. .Ar pattern .
  99. Equivalent to
  100. .Fl "S comment" .
  101. .It Fl D , Cm --description
  102. Search for packages with description text matching
  103. .Ar pattern .
  104. Equivalent to
  105. .Fl "S description" .
  106. .It Fl d , Cm --depends-on
  107. Display the list of packages depended on by each matched package.
  108. Equivalent to
  109. .Fl "Q depends-on" .
  110. .It Fl e , Cm --exact
  111. .Ar pattern
  112. should be an exact match against the search field.
  113. .It Fl f , Cm --full
  114. Show ``full'' information about the package.
  115. Equivalent to
  116. .Fl "Q full" .
  117. .It Fl g , Cm --glob
  118. Treat
  119. .Ar pattern
  120. as a shell globbing expression.
  121. The glob pattern must match the entire field being searched.
  122. .It Fl i , Cm --case-insensitive
  123. Make the exact
  124. .Fl ( e )
  125. or regular expression
  126. .Fl ( x )
  127. matching against
  128. .Ar pattern
  129. case insensitive.
  130. This is the default, unless modified by setting
  131. .Ev CASE_SENSITIVE_MATCH
  132. to true in
  133. .Pa pkg.conf .
  134. .It Fl L Ar label , Cm --label Ar label
  135. Select which identifying label is printed for each matched package,
  136. unless
  137. .Fl q
  138. is used.
  139. Several different fields from the repository catalogue database may be
  140. used to search on, or to generate the label, as indicated by the
  141. .Ar label
  142. argument.
  143. See the
  144. .Qq Sx Search and Label Options
  145. section for details.
  146. If unspecified,
  147. .Ar label
  148. is set to the same as the value searched via the
  149. .Fl S Ar search
  150. option.
  151. .It Fl o , Cm --origins
  152. List packages by origin for each package matching
  153. .Ar pattern .
  154. Equivalent to
  155. .Fl "L origin" .
  156. .It Fl p , Cm --prefix
  157. Display the package installation prefix for each matched package.
  158. Equivalent to
  159. .Fl "Q prefix" .
  160. .It Fl q , Cm --quiet
  161. Be
  162. .Dq quiet .
  163. Produce less output.
  164. In particular do not show an identifying label field for each package.
  165. .It Fl Q Ar query-modifier , Cm --query-modifier Ar query-modifier
  166. Modify the query output by adding an additional field to the result.
  167. Multiple fields can be added by using additional
  168. .Fl Q Ar query-modifier
  169. flags.
  170. See the
  171. .Qq Sx Output Modifier Options
  172. section for details.
  173. .It Fl r Ar reponame , Cm --repository Ar reponame
  174. Search for packages from only the named repository,
  175. irrespective of the configured
  176. .Dq active
  177. status from
  178. .Pa repo.conf .
  179. By default all repository catalogues marked
  180. .Dq active
  181. are searched.
  182. .It Fl R , Fl -raw
  183. Display the full manifest (raw) from the matching packages.
  184. .It Fl S Ar search , Cm --search Ar search
  185. Specify the field to search the repository catalogue on.
  186. If unspecified, searches on
  187. .Ar pkg-name
  188. unless the search term contains a
  189. .Sy /
  190. character, when it searches on port
  191. .Ar origin .
  192. Output will be sorted in order of the
  193. .Ar search
  194. field.
  195. See the
  196. .Qq Sx Search and Label Options
  197. sections for more details.
  198. .It Fl -raw-format Ar format
  199. Choose the format of the raw output.
  200. The format can be:
  201. json, json-conpact, yaml (default).
  202. .It Fl s , Cm --size
  203. Display the installed size of matched packages.
  204. Equivalent to
  205. .Fl "Q size" .
  206. .It Fl U, Cm --no-repo-update
  207. Suppress the automatic update of the local copy of the repository catalogue
  208. from remote.
  209. Automatic repository catalogue updates are only attempted when the
  210. effective UID of the process has write access to the package database.
  211. Otherwise they are silently ignored.
  212. .It Fl x , Cm --regex
  213. Treat
  214. .Ar pattern
  215. as a regular expression according to the "modern" or "extended"
  216. syntax of
  217. .Xr re_format 7 .
  218. This is the default.
  219. Matches any substring of the search field unless explicit beginning
  220. or ending anchor terms are used.
  221. .El
  222. .Ss Search and Label Options
  223. The following database fields (or composites of several fields) can
  224. be used both for searching for a match to the given
  225. .Ar pattern
  226. and as identifying labels for the block of output for each package.
  227. .Bl -tag -width 2n
  228. .It Sy comment
  229. The one line comment field describing the port, derived from the
  230. .Cm COMMENT
  231. variable in the port's
  232. .Fa Makefile .
  233. When chosen as a label option, the output format will additionally
  234. include the package name, equivalent to
  235. .Fl "L pkg-name"
  236. .Fl "Q comment" .
  237. When chosen as a search option, only the
  238. .Sy comment
  239. field is used for sorting the output.
  240. .It Sy description
  241. The multi-line package description from the
  242. .Fa pkg-descr
  243. file in the port.
  244. This does include the
  245. .Cm WWW
  246. URL reference, if any, from that file.
  247. When chosen as a label option, the output format will additionally
  248. include the package name, equivalent to
  249. .Fl "L pkg-name"
  250. .Fl "Q description" .
  251. When chosen as a search option, only the
  252. .Sy description
  253. field is used for sorting the output.
  254. .It Sy name
  255. The name of the package, derived from the
  256. .Cm PORTNAME
  257. variable in the port's
  258. .Fa Makefile .
  259. .It Sy origin
  260. The port origin, in the format
  261. .Fa category/port ,
  262. that the package was compiled from.
  263. .It Sy pkg-name
  264. The package name in the format
  265. .Sy name Ns - Ns Cm version .
  266. The same as the
  267. .Cm PKGNAME
  268. variable in the port's
  269. .Fa Makefile .
  270. .El
  271. .Pp
  272. Any unambiguous prefix of the label name may be used on the command line.
  273. Thus
  274. .Fl "Sd" ,
  275. .Fl "S descr"
  276. and
  277. .Fl "S description"
  278. are all equivalent.
  279. .Ss Output Modifier Options
  280. Additional data from the repository catalogue to print for each matched
  281. package.
  282. Multiple output modifiers can be combined.
  283. Where more than one output field is required, either because multiple
  284. .Fl Q Ar query-modifier
  285. options were given, or one or more
  286. .Fl Q Ar query-modifier
  287. option was combined with the
  288. .Fl "L comment"
  289. or
  290. .Fl "L description"
  291. options, then each output field will be tagged with the field name.
  292. .Bl -tag -width 2n
  293. .It Sy annotations
  294. Arbitrary text in tag-value format that can be added to any package.
  295. .It Sy arch
  296. The architecture string indicating what OS version and CPU architecture
  297. the package is suitable for.
  298. For example,
  299. .Ar freebsd:9:x86:64
  300. indicates a package suitable for FreeBSD 9.x running on an amd64 processor,
  301. while
  302. .Ar freebsd:*
  303. indicates an architecture independent package suitable for any version of
  304. FreeBSD.
  305. .It Sy categories
  306. All categories, real and virtual, the underlying package belongs to,
  307. derived from the
  308. .Cm CATEGORIES
  309. variable in the port's
  310. .Fa Makefile .
  311. .It Sy comment
  312. The one line comment field describing the port, derived from the
  313. .Cm COMMENT
  314. variable in the port's
  315. .Fa Makefile .
  316. .It Sy depends-on
  317. The list of packages the named package depends on.
  318. Dependency packages are listed in the format
  319. .Sy name Ns - Ns Cm version
  320. one per line.
  321. If the port has no dependencies, nothing will be output for
  322. this field, including suppressing the tag name when multiple
  323. output fields are requested.
  324. .It Sy description
  325. The multi-line package description from the
  326. .Fa pkg-descr
  327. file in the port.
  328. This does include the
  329. .Cm WWW
  330. URL reference, if any, from that file.
  331. .It Sy full
  332. Show a standard set of fields, equivalent to a combination of the
  333. .Sy name ,
  334. .Sy version ,
  335. .Sy origin ,
  336. .Sy prefix ,
  337. .Sy repository ,
  338. .Sy categories ,
  339. .Sy license ,
  340. .Sy maintainer ,
  341. .Sy www ,
  342. .Sy comment ,
  343. .Sy options ,
  344. .Sy shared-libs-required ,
  345. .Sy shared-libs-provided ,
  346. .Sy annotations ,
  347. .Sy size ,
  348. .Sy pkg-size
  349. and
  350. .Sy descr
  351. fields, in that order.
  352. .It Sy licenses
  353. Displays a list of all the licenses the package is released under on a
  354. single line.
  355. Where more than one license applies, indicate if the terms of all
  356. licenses should apply
  357. .Sy (&)
  358. or if one or more licenses may be selected out of those available
  359. .Sy (|) .
  360. .It Sy maintainer
  361. Display the maintainer's e-mail address.
  362. .It Sy name
  363. Display the port name, which is derived from the
  364. .Cm PORTNAME
  365. variable in the port's
  366. .Fa Makefile .
  367. .It Sy options
  368. Displays a list of the port options and their state (
  369. .Sy on
  370. or
  371. .Sy off )
  372. when the package was built.
  373. If the package does not have any options to set, nothing will be
  374. output for this field, including suppressing the tag name when
  375. multiple output fields are requested.
  376. .It Sy pkg-size
  377. Display the size of the compressed package tarball, i.e., how much would
  378. need to be downloaded from the repository.
  379. .It Sy prefix
  380. Display the installation prefix for the package, usually
  381. .Fa /usr/local .
  382. .It Sy repository
  383. Displays the repository name and the corresponding base URL for the
  384. repository.
  385. For a default repository defined in
  386. .Pa pkg.conf .
  387. .It Sy required-by
  388. Displays all of the packages in the repository that require the named
  389. package as a dependency.
  390. Dependency packages are listed in the format
  391. .Sy name Ns - Ns Cm version
  392. one per line.
  393. If no other packages require the named package, nothing will be
  394. output for this field, including suppressing the tag name when
  395. multiple output fields are requested.
  396. .It Sy shared-libs-required
  397. If the package contains dynamically linked FreeBSD ELF binaries,
  398. display a list of all of the shared libraries other than those from
  399. the base system required for those binaries to run.
  400. Shared libraries for foreign (e.g., Linux) binaries run
  401. under emulation will not be displayed.
  402. If the package does not require any shared libraries, nothing will be
  403. output for this field including suppressing the tag name when multiple
  404. fields are requested.
  405. .It Sy shared-libs-provided
  406. If the package contains any shared libraries, display a list of
  407. the library names, including the ABI version number, if any.
  408. A shared library, of either the same or differing ABI versions, may
  409. legitimately be provided by more than installed package,
  410. but this frequently indicates a problem.
  411. .It Sy size
  412. Display the total amount of filesystem space the package files will
  413. take up once unpacked and installed.
  414. .It Sy url
  415. Display the URL that would be used to download the package from the
  416. repository.
  417. .It Sy version
  418. Display the package version, which is derived from the
  419. .Cm PKGVERSION
  420. variable in the port's
  421. .Fa Makefile .
  422. .It Sy www
  423. Display the general URL, if any, for the project developing the
  424. software used in the package.
  425. This is extracted from the
  426. .Fa pkg-descr
  427. file in the port.
  428. .El
  429. .Pp
  430. Any unambiguous prefix of the query modifier name may be used on the
  431. command line.
  432. Thus
  433. .Fl "Qm" ,
  434. .Fl "Q maint"
  435. and
  436. .Fl "Q maintainer"
  437. are all equivalent,
  438. but you need to use at least
  439. .Fl "Q si"
  440. and
  441. .Fl "Q sh"
  442. to distinguish
  443. .Cm size
  444. from
  445. .Cm shared-libs-required
  446. or
  447. .Cm shared-libs-provided ,
  448. and you'll need at least
  449. .Fl "Q shared-libs-p"
  450. to select the
  451. .Cm shared-libs-provided
  452. unambiguously.
  453. .Sh ENVIRONMENT
  454. The following environment variables affect the execution of
  455. .Nm .
  456. See
  457. .Xr pkg.conf 5
  458. for further description.
  459. .Bl -tag -width ".Ev NO_DESCRIPTIONS"
  460. .It Ev PKG_DBDIR
  461. .It Ev CASE_SENSITIVE_MATCH
  462. .El
  463. .Sh FILES
  464. See
  465. .Xr pkg.conf 5 .
  466. .Sh SEE ALSO
  467. .Xr pkg_printf 3 ,
  468. .Xr pkg_repos 3 ,
  469. .Xr pkg-repository 5 ,
  470. .Xr pkg.conf 5 ,
  471. .Xr pkg 8 ,
  472. .Xr pkg-add 8 ,
  473. .Xr pkg-annotate 8 ,
  474. .Xr pkg-audit 8 ,
  475. .Xr pkg-autoremove 8 ,
  476. .Xr pkg-backup 8 ,
  477. .Xr pkg-check 8 ,
  478. .Xr pkg-clean 8 ,
  479. .Xr pkg-config 8 ,
  480. .Xr pkg-convert 8 ,
  481. .Xr pkg-create 8 ,
  482. .Xr pkg-delete 8 ,
  483. .Xr pkg-fetch 8 ,
  484. .Xr pkg-info 8 ,
  485. .Xr pkg-install 8 ,
  486. .Xr pkg-lock 8 ,
  487. .Xr pkg-query 8 ,
  488. .Xr pkg-register 8 ,
  489. .Xr pkg-repo 8 ,
  490. .Xr pkg-rquery 8 ,
  491. .Xr pkg-set 8 ,
  492. .Xr pkg-shell 8 ,
  493. .Xr pkg-shlib 8 ,
  494. .Xr pkg-ssh 8 ,
  495. .Xr pkg-stats 8 ,
  496. .Xr pkg-update 8 ,
  497. .Xr pkg-updating 8 ,
  498. .Xr pkg-upgrade 8 ,
  499. .Xr pkg-version 8 ,
  500. .Xr pkg-which 8