6/share/man/man7/ports.7

   1 .\"
   2 .\" Copyright (c) 1997 David E. O'Brien
   3 .\"
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd January 21, 2008
  29 .Dt PORTS 7
  30 .Os
  31 .Sh NAME
  32 .Nm ports
  33 .Nd contributed applications
  34 .Sh DESCRIPTION
  35 The
  36 .Fx
  37 Ports Collection
  38 offers a simple way for users and
  39 administrators to install applications.
  40 Each
  41 .Em port
  42 contains any patches necessary to make the original
  43 application source code compile and run on
  44 .Bx .
  45 Compiling an
  46 application is as simple as typing
  47 .Nm make Cm build
  48 in the port directory!
  49 The
  50 .Pa Makefile
  51 automatically fetches the
  52 application source code, either from a local disk or via FTP, unpacks it
  53 on your system, applies the patches, and compiles it.
  54 If all goes well,
  55 simply type
  56 .Nm make Cm install
  57 to install the application.
  58 .Pp
  59 It is possible to download and use ports from the
  60 .Fx
  61 repository
  62 that are newer than the installed system; however it is important to
  63 install the appropriate
  64 .Dq "Upgrade Kit"
  65 from
  66 .Pa http://www.FreeBSD.org/ports/
  67 first!
  68 The
  69 .Xr portcheckout 1 Pq Pa ports/ports-mgmt/portcheckout
  70 script (also a port, of course!) will help to download new ports.
  71 .Pp
  72 For more information about using ports, see
  73 .Dq "Packages and Ports"
  74 in
  75 .%B "The FreeBSD Handbook" ,
  76 .Pa ( file:/usr/share/doc/en_US.ISO8859-1/books/handbook/ports.html
  77 or
  78 .Pa http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/ports.html ) .
  79 For information about creating new ports, see
  80 .%B "The Porter's Handbook"
  81 .Pa ( file:/usr/share/doc/en_US.ISO8859-1/books/porters-handbook/index.html
  82 or
  83 .Pa http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/porters-handbook/ ) .
  84 .Sh TARGETS
  85 Some of the targets work recursively through subdirectories.
  86 This lets you, for example, install all of the
  87 .Dq Li biology
  88 ports.
  89 The targets that do this are
  90 .Cm build , checksum , clean , configure ,
  91 .Cm depends , extract , fetch , install ,
  92 and
  93 .Cm package .
  94 .Pp
  95 The following targets will be run automatically by each proceeding
  96 target in order.
  97 That is,
  98 .Cm build
  99 will be run
 100 (if necessary)
 101 by
 102 .Cm install ,
 103 and so on all the way to
 104 .Cm fetch .
 105 Usually, you will only use the
 106 .Cm install
 107 target.
 108 .Bl -tag -width ".Cm configure"
 109 .It Cm config
 110 Configure
 111 .Va OPTIONS
 112 for this port using
 113 .Xr dialog 1 .
 114 .It Cm config-recursive
 115 Configure
 116 .Va OPTIONS
 117 for this port and all its dependencies using
 118 .Xr dialog 1 .
 119 .It Cm fetch
 120 Fetch all of the files needed to build this port from the sites
 121 listed in
 122 .Va MASTER_SITES
 123 and
 124 .Va PATCH_SITES .
 125 See
 126 .Va FETCH_CMD , MASTER_SITE_OVERRIDE
 127 and
 128 .Va MASTER_SITE_BACKUP .
 129 .It Cm checksum
 130 Verify that the fetched distfile's checksum matches the one the port was
 131 tested against.
 132 Defining
 133 .Va NO_CHECKSUM
 134 will skip this step.
 135 .It Cm depends
 136 Install
 137 (or compile if only compilation is necessary)
 138 any dependencies of the current port.
 139 When called by the
 140 .Cm extract
 141 or
 142 .Cm fetch
 143 targets, this is run in piecemeal as
 144 .Cm fetch-depends , build-depends ,
 145 etc.
 146 Defining
 147 .Va NO_DEPENDS
 148 will skip this step.
 149 .It Cm extract
 150 Expand the distfile into a work directory.
 151 .It Cm patch
 152 Apply any patches that are necessary for the port.
 153 .It Cm configure
 154 Configure the port.
 155 Some ports will ask you questions during this stage.
 156 See
 157 .Va INTERACTIVE
 158 and
 159 .Va BATCH .
 160 .It Cm build
 161 Build the port.
 162 This is the same as calling the
 163 .Cm all
 164 target.
 165 .It Cm install
 166 Install the port and register it with the package system.
 167 This is all you really need to do.
 168 .El
 169 .Pp
 170 The following targets are not run during the normal install process.
 171 .Bl -tag -width ".Cm fetch-recursive"
 172 .It Cm showconfig
 173 Display
 174 .Va OPTIONS
 175 config for this port.
 176 .It Cm showconfig-recursive
 177 Display
 178 .Va OPTIONS
 179 config for this port and all its dependencies.
 180 .It Cm rmconfig
 181 Remove
 182 .Va OPTIONS
 183 config for this port.
 184 .It Cm rmconfig-recursive
 185 Remove
 186 .Va OPTIONS
 187 config for this port and all its dependencies.
 188 .It Cm config-conditional
 189 Skip the ports which have already had their
 190 .Va OPTIONS
 191 configured.
 192 .It Cm fetch-list
 193 Show list of files to be fetched in order to build the port.
 194 .It Cm fetch-recursive
 195 Fetch the distfiles of the port and all its dependencies.
 196 .It Cm fetch-recursive-list
 197 Show list of files that would be retrieved by
 198 .Cm fetch-recursive .
 199 .It Cm pretty-print-run-depends-list , pretty-print-build-depends-list
 200 Print a list of all the compile and run dependencies, and dependencies
 201 of those dependencies.
 202 .It Cm missing
 203 Print a list of missing dependencies to be installed for the port.
 204 .It Cm clean
 205 Remove the expanded source code.
 206 This recurses to dependencies unless
 207 .Va NOCLEANDEPENDS
 208 is defined.
 209 .It Cm distclean
 210 Remove the port's distfiles and perform the
 211 .Cm clean
 212 target.
 213 The
 214 .Cm clean
 215 portion recurses to dependencies unless
 216 .Va NOCLEANDEPENDS
 217 is defined, but the
 218 .Cm distclean
 219 portion never recurses
 220 (this is perhaps a bug).
 221 .It Cm reinstall
 222 Use this to restore a port after using
 223 .Xr pkg_delete 1
 224 when you should have used
 225 .Cm deinstall .
 226 .It Cm deinstall
 227 Remove an installed port from the system, similar to
 228 .Xr pkg_delete 1 .
 229 .It Cm deinstall-all
 230 Remove all installed ports with the same
 231 .Va PKGORIGIN
 232 from the system.
 233 .It Cm package
 234 Make a binary package for the port.
 235 The port will be installed if it has not already been.
 236 The package is a
 237 .Pa .tbz
 238 file that you can use to
 239 install the port on other machines with
 240 .Xr pkg_add 1 .
 241 If the directory specified by
 242 .Va PACKAGES
 243 does not exist, the package will be put into the current directory.
 244 See
 245 .Va PKGREPOSITORY
 246 and
 247 .Va PKGFILE .
 248 .It Cm package-recursive
 249 Like
 250 .Cm package ,
 251 but makes a package for each depending port as well.
 252 .It Cm readmes
 253 Create a port's
 254 .Pa README.html .
 255 This can be used from
 256 .Pa /usr/ports
 257 to create a browsable web of all ports on your system!
 258 .It Cm search
 259 Search the
 260 .Pa INDEX
 261 file for the pattern specified by the
 262 .Va key
 263 (searches the port name, comment, and dependencies),
 264 .Va name
 265 (searches the port name only),
 266 .Va path
 267 (searches the port path),
 268 .Va info
 269 (searches the port info),
 270 .Va maint
 271 (searches the port maintainer),
 272 .Va cat
 273 (searches the port category),
 274 .Va bdeps
 275 (searches the port build-time dependency),
 276 .Va rdeps
 277 (searches the port run-time dependency),
 278 .Va www
 279 (searches the port web site)
 280 .Xr make 1
 281 variables, and their exclusion counterparts:
 282 .Va xname , xkey
 283 etc.
 284 For example, one would type:
 285 .Pp
 286 .Dl "cd /usr/ports && make search name=query"
 287 .Pp
 288 to find all ports whose
 289 name matches
 290 .Dq Li query .
 291 Results include the matching ports' path, comment, maintainer,
 292 build dependencies, and run dependencies.
 293 .Bd -literal -offset indent
 294 cd /usr/ports && make search name=pear- \e
 295     xbdeps=apache
 296 .Ed
 297 .Pp
 298 To find all ports whose
 299 names contain
 300 .Dq Li pear-
 301 and which do not have apache
 302 listed in build-time dependencies.
 303 .Bd -literal -offset indent
 304 cd /usr/ports && make search name=pear- \e
 305     xname='ht(tp|ml)'
 306 .Ed
 307 .Pp
 308 To find all ports whose names contain
 309 .Dq Li pear- ,
 310 but not
 311 .Dq Li html
 312 or
 313 .Dq Li http .
 314 .Bd -literal -offset indent
 315 make search key=apache display=name,path,info keylim=1
 316 .Ed
 317 .Pp
 318 To find ports that contain
 319 .Dq Li apache
 320 in either of the name, path, info
 321 fields, ignore the rest of the record.
 322 .Pp
 323 By default the search is not case-nsensitive.
 324 In order to make it case-sensitive you can use the
 325 .Va icase
 326 variable:
 327 .Bd -literal -offset indent
 328 make search name=p5-R icase=0
 329 .Ed
 330 .It Cm quicksearch
 331 Reduced
 332 .Cm search
 333 output.
 334 Only display name, path and info.
 335 .It Cm describe
 336 Generate a one-line description of each port for use in the
 337 .Pa INDEX
 338 file.
 339 .It Cm maintainer
 340 Display the port maintainer's email address.
 341 .It Cm index
 342 Create
 343 .Pa /usr/ports/INDEX ,
 344 which is used by the
 345 .Cm pretty-print-*
 346 and
 347 .Cm search
 348 targets.
 349 Running the
 350 .Cm index
 351 target will ensure your
 352 .Pa INDEX
 353 file is up to date with your ports tree.
 354 .It Cm fetchindex
 355 Fetch the
 356 .Pa INDEX
 357 file from the
 358 .Fx
 359 cluster.
 360 .El
 361 .Sh ENVIRONMENT
 362 You can change all of these.
 363 .Bl -tag -width ".Va MASTER_SITES"
 364 .It Va PORTSDIR
 365 Location of the ports tree.
 366 This is
 367 .Pa /usr/ports
 368 on
 369 .Fx
 370 and
 371 .Ox ,
 372 and
 373 .Pa /usr/pkgsrc
 374 on
 375 .Nx .
 376 .It Va WRKDIRPREFIX
 377 Where to create any temporary files.
 378 Useful if
 379 .Va PORTSDIR
 380 is read-only (perhaps mounted from a CD-ROM).
 381 .It Va DISTDIR
 382 Where to find/put distfiles, normally
 383 .Pa distfiles/
 384 in
 385 .Va PORTSDIR .
 386 .It Va PACKAGES
 387 Used only for the
 388 .Cm package
 389 target; the base directory for the packages tree, normally
 390 .Pa packages/
 391 in
 392 .Va PORTSDIR .
 393 If this directory exists, the package tree will be (partially) constructed.
 394 This directory does not have to exist; if it does not, packages will be
 395 placed into the current directory, or you can define one of
 396 .Bl -tag -width ".Va PKGREPOSITORY"
 397 .It Va PKGREPOSITORY
 398 Directory to put the package in.
 399 .It Va PKGFILE
 400 The full path to the package.
 401 .El
 402 .It Va PREFIX
 403 Where to install things in general
 404 (usually
 405 .Pa /usr/local ) .
 406 .It Va MASTER_SITES
 407 Primary sites for distribution files if not found locally.
 408 .It Va PATCH_SITES
 409 Primary locations for distribution patch files if not found
 410 locally.
 411 .It Va MASTER_SITE_FREEBSD
 412 If set, go to the master
 413 .Fx
 414 site for all files.
 415 .It Va MASTER_SITE_OVERRIDE
 416 Try going to these sites for all files and patches, first.
 417 .It Va MASTER_SITE_BACKUP
 418 Try going to these sites for all files and patches, last.
 419 .It Va RANDOMIZE_MASTER_SITES
 420 Try the download locations in a random order.
 421 .It Va MASTER_SORT
 422 Sort the download locations according to user supplied pattern.
 423 Example:
 424 .Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net
 425 .It Va MASTER_SITE_INDEX
 426 Where to get
 427 .Pa INDEX
 428 source built on
 429 .Fx
 430 cluster (for
 431 .Cm fetchindex
 432 target).
 433 Defaults to
 434 .Pa http://www.FreeBSD.org/ports/ .
 435 .It Va FETCHINDEX
 436 Command to get
 437 .Pa INDEX
 438 (for
 439 .Cm fetchindex
 440 target).
 441 Defaults to
 442 .Dq Nm fetch Fl am .
 443 .It Va NOCLEANDEPENDS
 444 If defined, do not let
 445 .Cm clean
 446 recurse to dependencies.
 447 .It Va FETCH_CMD
 448 Command to use to fetch files.
 449 Normally
 450 .Xr fetch 1 .
 451 .It Va FORCE_PKG_REGISTER
 452 If set, overwrite any existing package registration on the system.
 453 .It Va MOTIFLIB
 454 Location of
 455 .Pa libXm. Ns Brq Pa a , Ns Pa so .
 456 .It Va INTERACTIVE
 457 If defined, only operate on a port if it requires interaction.
 458 .It Va BATCH
 459 If defined, only operate on a port if it can be installed 100% automatically.
 460 .It Va DISABLE_VULNERABILITIES
 461 If defined, disable check for security vulnerabilities using
 462 .Xr portaudit 1 Pq Pa ports/ports-mgmt/portaudit
 463 when installing new ports.
 464 .It Va NO_IGNORE
 465 If defined, allow installation of ports marked as
 466 .Aq Va FORBIDDEN .
 467 The default behavior of the Ports framework is to abort when the
 468 installation of a forbidden port is attempted.
 469 Of course, these ports may not work as expected, but if you really know
 470 what you are doing and are sure about installing a forbidden port, then
 471 .Va NO_IGNORE
 472 lets you do it.
 473 .It Va PORT_DBDIR
 474 Directory where the results of configuring
 475 .Va OPTIONS
 476 are stored.
 477 Defaults to
 478 .Pa /var/db/ports .
 479 Each port where
 480 .Va OPTIONS
 481 have been configured will have a uniquely named sub-directory, containing a
 482 single file
 483 .Pa options .
 484 .El
 485 .Sh FILES
 486 .Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact
 487 .It Pa /usr/ports
 488 The default ports directory
 489 .No ( Fx
 490 and
 491 .Ox ) .
 492 .It Pa /usr/pkgsrc
 493 The default ports directory
 494 .Pq Nx .
 495 .It Pa /usr/ports/Mk/bsd.port.mk
 496 The big Kahuna.
 497 .El
 498 .Sh SEE ALSO
 499 .Xr make 1 ,
 500 .Xr pkg_add 1 ,
 501 .Xr pkg_create 1 ,
 502 .Xr pkg_delete 1 ,
 503 .Xr pkg_info 1 ,
 504 .Xr pkg_version 1
 505 .Pp
 506 The following are part of the ports collection:
 507 .Pp
 508 .Xr portaudit 1 ,
 509 .Xr portcheckout 1 ,
 510 .Xr portlint 1
 511 .Rs
 512 .%B "The FreeBSD Handbook"
 513 .Re
 514 .Pp
 515 .Pa http://www.FreeBSD.org/ports
 516 (searchable index of all ports)
 517 .Sh HISTORY
 518 The Ports Collection
 519 appeared in
 520 .Fx 1.0 .
 521 It has since spread to
 522 .Nx
 523 and
 524 .Ox .
 525 .Sh AUTHORS
 526 .An -nosplit
 527 This manual page was originated by
 528 .An David O'Brien .
 529 .Sh BUGS
 530 Ports documentation is split over four places \(em
 531 .Pa /usr/ports/Mk/bsd.port.mk ,
 532 .%B "The Porter's Handbook" ,
 533 the
 534 .Dq "Packages and Ports"
 535 chapter of
 536 .%B "The FreeBSD Handbook" ,
 537 and
 538 this manual page.