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 February 9, 2012
  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 fetch
 115 Fetch all of the files needed to build this port from the sites
 116 listed in
 117 .Va MASTER_SITES
 118 and
 119 .Va PATCH_SITES .
 120 See
 121 .Va FETCH_CMD , MASTER_SITE_OVERRIDE
 122 and
 123 .Va MASTER_SITE_BACKUP .
 124 .It Cm checksum
 125 Verify that the fetched distfile's checksum matches the one the port was
 126 tested against.
 127 If the distfile's checksum does not match, it also fetches the distfiles
 128 which are missing or failed the checksum calculation.
 129 Defining
 130 .Va NO_CHECKSUM
 131 will skip this step.
 132 .It Cm depends
 133 Install
 134 (or compile if only compilation is necessary)
 135 any dependencies of the current port.
 136 When called by the
 137 .Cm extract
 138 or
 139 .Cm fetch
 140 targets, this is run in piecemeal as
 141 .Cm fetch-depends , build-depends ,
 142 etc.
 143 Defining
 144 .Va NO_DEPENDS
 145 will skip this step.
 146 .It Cm extract
 147 Expand the distfile into a work directory.
 148 .It Cm patch
 149 Apply any patches that are necessary for the port.
 150 .It Cm configure
 151 Configure the port.
 152 Some ports will ask you questions during this stage.
 153 See
 154 .Va INTERACTIVE
 155 and
 156 .Va BATCH .
 157 .It Cm build
 158 Build the port.
 159 This is the same as calling the
 160 .Cm all
 161 target.
 162 .It Cm install
 163 Install the port and register it with the package system.
 164 This is all you really need to do.
 165 .El
 166 .Pp
 167 The following targets are not run during the normal install process.
 168 .Bl -tag -width ".Cm fetch-recursive"
 169 .It Cm showconfig
 170 Display
 171 .Va OPTIONS
 172 config for this port.
 173 .It Cm showconfig-recursive
 174 Display
 175 .Va OPTIONS
 176 config for this port and all its dependencies.
 177 .It Cm rmconfig
 178 Remove
 179 .Va OPTIONS
 180 config for this port.
 181 .It Cm rmconfig-recursive
 182 Remove
 183 .Va OPTIONS
 184 config for this port and all its dependencies.
 185 .It Cm config-conditional
 186 Skip the ports which have already had their
 187 .Va OPTIONS
 188 configured.
 189 .It Cm config-recursive
 190 Configure
 191 .Va OPTIONS
 192 for this port and all its dependencies using
 193 .Xr dialog 1 .
 194 .It Cm fetch-list
 195 Show list of files to be fetched in order to build the port.
 196 .It Cm fetch-recursive
 197 Fetch the distfiles of the port and all its dependencies.
 198 .It Cm fetch-recursive-list
 199 Show list of files that would be retrieved by
 200 .Cm fetch-recursive .
 201 .It Cm run-depends-list , build-depends-list
 202 Print a list of all the compile and run dependencies, and dependencies
 203 of those dependencies, by port directory.
 204 .It Cm all-depends-list
 205 Print a list of all dependencies for the port.
 206 .It Cm pretty-print-run-depends-list , pretty-print-build-depends-list
 207 Print a list of all the compile and run dependencies, and dependencies
 208 of those dependencies, by port name and version.
 209 .It Cm missing
 210 Print a list of missing dependencies to be installed for the port.
 211 .It Cm clean
 212 Remove the expanded source code.
 213 This recurses to dependencies unless
 214 .Va NOCLEANDEPENDS
 215 is defined.
 216 .It Cm distclean
 217 Remove the port's distfiles and perform the
 218 .Cm clean
 219 target.
 220 The
 221 .Cm clean
 222 portion recurses to dependencies unless
 223 .Va NOCLEANDEPENDS
 224 is defined, but the
 225 .Cm distclean
 226 portion never recurses
 227 (this is perhaps a bug).
 228 .It Cm reinstall
 229 Use this to restore a port after using
 230 .Xr pkg_delete 1
 231 when you should have used
 232 .Cm deinstall .
 233 .It Cm deinstall
 234 Remove an installed port from the system, similar to
 235 .Xr pkg_delete 1 .
 236 .It Cm deinstall-all
 237 Remove all installed ports with the same
 238 .Va PKGORIGIN
 239 from the system.
 240 .It Cm package
 241 Make a binary package for the port.
 242 The port will be installed if it has not already been.
 243 The package is a
 244 .Pa .tbz
 245 file that you can use to
 246 install the port on other machines with
 247 .Xr pkg_add 1 .
 248 If the directory specified by
 249 .Va PACKAGES
 250 does not exist, the package will be put into the current directory.
 251 See
 252 .Va PKGREPOSITORY
 253 and
 254 .Va PKGFILE .
 255 .It Cm package-recursive
 256 Like
 257 .Cm package ,
 258 but makes a package for each depending port as well.
 259 .It Cm package-name
 260 Prints the name with version of the port.
 261 .It Cm readmes
 262 Create a port's
 263 .Pa README.html .
 264 This can be used from
 265 .Pa /usr/ports
 266 to create a browsable web of all ports on your system!
 267 .It Cm search
 268 Search the
 269 .Pa INDEX
 270 file for the pattern specified by the
 271 .Va key
 272 (searches the port name, comment, and dependencies),
 273 .Va name
 274 (searches the port name only),
 275 .Va path
 276 (searches the port path),
 277 .Va info
 278 (searches the port info),
 279 .Va maint
 280 (searches the port maintainer),
 281 .Va cat
 282 (searches the port category),
 283 .Va bdeps
 284 (searches the port build-time dependency),
 285 .Va rdeps
 286 (searches the port run-time dependency),
 287 .Va www
 288 (searches the port web site)
 289 .Xr make 1
 290 variables, and their exclusion counterparts:
 291 .Va xname , xkey
 292 etc.
 293 For example, one would type:
 294 .Pp
 295 .Dl "cd /usr/ports && make search name=query"
 296 .Pp
 297 to find all ports whose
 298 name matches
 299 .Dq Li query .
 300 Results include the matching ports' path, comment, maintainer,
 301 build dependencies, and run dependencies.
 302 .Bd -literal -offset indent
 303 cd /usr/ports && make search name=pear- \e
 304     xbdeps=apache
 305 .Ed
 306 .Pp
 307 To find all ports whose
 308 names contain
 309 .Dq Li pear-
 310 and which do not have apache
 311 listed in build-time dependencies.
 312 .Bd -literal -offset indent
 313 cd /usr/ports && make search name=pear- \e
 314     xname='ht(tp|ml)'
 315 .Ed
 316 .Pp
 317 To find all ports whose names contain
 318 .Dq Li pear- ,
 319 but not
 320 .Dq Li html
 321 or
 322 .Dq Li http .
 323 .Bd -literal -offset indent
 324 make search key=apache display=name,path,info keylim=1
 325 .Ed
 326 .Pp
 327 To find ports that contain
 328 .Dq Li apache
 329 in either of the name, path, info
 330 fields, ignore the rest of the record.
 331 .Pp
 332 By default the search is not case-sensitive.
 333 In order to make it case-sensitive you can use the
 334 .Va icase
 335 variable:
 336 .Bd -literal -offset indent
 337 make search name=p5-R icase=0
 338 .Ed
 339 .It Cm quicksearch
 340 Reduced
 341 .Cm search
 342 output.
 343 Only display name, path and info.
 344 .It Cm describe
 345 Generate a one-line description of each port for use in the
 346 .Pa INDEX
 347 file.
 348 .It Cm maintainer
 349 Display the port maintainer's email address.
 350 .It Cm index
 351 Create
 352 .Pa /usr/ports/INDEX ,
 353 which is used by the
 354 .Cm pretty-print-*
 355 and
 356 .Cm search
 357 targets.
 358 Running the
 359 .Cm index
 360 target will ensure your
 361 .Pa INDEX
 362 file is up to date with your ports tree.
 363 .It Cm fetchindex
 364 Fetch the
 365 .Pa INDEX
 366 file from the
 367 .Fx
 368 cluster.
 369 .El
 370 .Sh ENVIRONMENT
 371 You can change all of these.
 372 .Bl -tag -width ".Va MASTER_SITES"
 373 .It Va PORTSDIR
 374 Location of the ports tree.
 375 This is
 376 .Pa /usr/ports
 377 on
 378 .Fx
 379 and
 380 .Ox ,
 381 and
 382 .Pa /usr/pkgsrc
 383 on
 384 .Nx .
 385 .It Va WRKDIRPREFIX
 386 Where to create any temporary files.
 387 Useful if
 388 .Va PORTSDIR
 389 is read-only (perhaps mounted from a CD-ROM).
 390 .It Va DISTDIR
 391 Where to find/put distfiles, normally
 392 .Pa distfiles/
 393 in
 394 .Va PORTSDIR .
 395 .It Va PACKAGES
 396 Used only for the
 397 .Cm package
 398 target; the base directory for the packages tree, normally
 399 .Pa packages/
 400 in
 401 .Va PORTSDIR .
 402 If this directory exists, the package tree will be (partially) constructed.
 403 This directory does not have to exist; if it does not, packages will be
 404 placed into the current directory, or you can define one of
 405 .Bl -tag -width ".Va PKGREPOSITORY"
 406 .It Va PKGREPOSITORY
 407 Directory to put the package in.
 408 .It Va PKGFILE
 409 The full path to the package.
 410 .El
 411 .It Va LOCALBASE
 412 Where existing things are installed and where to search for files when
 413 resolving dependencies (usually
 414 .Pa /usr/local ) .
 415 .It Va PREFIX
 416 Where to install this port (usually set to the same as
 417 .Va LOCALBASE ) .
 418 .It Va MASTER_SITES
 419 Primary sites for distribution files if not found locally.
 420 .It Va PATCH_SITES
 421 Primary locations for distribution patch files if not found
 422 locally.
 423 .It Va MASTER_SITE_FREEBSD
 424 If set, go to the master
 425 .Fx
 426 site for all files.
 427 .It Va MASTER_SITE_OVERRIDE
 428 Try going to these sites for all files and patches, first.
 429 .It Va MASTER_SITE_BACKUP
 430 Try going to these sites for all files and patches, last.
 431 .It Va RANDOMIZE_MASTER_SITES
 432 Try the download locations in a random order.
 433 .It Va MASTER_SORT
 434 Sort the download locations according to user supplied pattern.
 435 Example:
 436 .Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net
 437 .It Va MASTER_SITE_INDEX
 438 Where to get
 439 .Pa INDEX
 440 source built on
 441 .Fx
 442 cluster (for
 443 .Cm fetchindex
 444 target).
 445 Defaults to
 446 .Pa http://www.FreeBSD.org/ports/ .
 447 .It Va FETCHINDEX
 448 Command to get
 449 .Pa INDEX
 450 (for
 451 .Cm fetchindex
 452 target).
 453 Defaults to
 454 .Dq Nm fetch Fl am .
 455 .It Va NOCLEANDEPENDS
 456 If defined, do not let
 457 .Cm clean
 458 recurse to dependencies.
 459 .It Va FETCH_CMD
 460 Command to use to fetch files.
 461 Normally
 462 .Xr fetch 1 .
 463 .It Va FORCE_PKG_REGISTER
 464 If set, overwrite any existing package registration on the system.
 465 .It Va MOTIFLIB
 466 Location of
 467 .Pa libXm. Ns Brq Pa a , Ns Pa so .
 468 .It Va INTERACTIVE
 469 If defined, only operate on a port if it requires interaction.
 470 .It Va BATCH
 471 If defined, only operate on a port if it can be installed 100% automatically.
 472 .It Va DISABLE_VULNERABILITIES
 473 If defined, disable check for security vulnerabilities using
 474 .Xr portaudit 1 Pq Pa ports/ports-mgmt/portaudit
 475 when installing new ports.
 476 .It Va NO_IGNORE
 477 If defined, allow installation of ports marked as
 478 .Aq Va FORBIDDEN .
 479 The default behavior of the Ports framework is to abort when the
 480 installation of a forbidden port is attempted.
 481 Of course, these ports may not work as expected, but if you really know
 482 what you are doing and are sure about installing a forbidden port, then
 483 .Va NO_IGNORE
 484 lets you do it.
 485 .It Va NO_CHECKSUM
 486 If defined, skip verifying the port's checksum.
 487 .It Va TRYBROKEN
 488 If defined, attempt to build a port even if it is marked as
 489 .Aq Va BROKEN .
 490 .It Va PORT_DBDIR
 491 Directory where the results of configuring
 492 .Va OPTIONS
 493 are stored.
 494 Defaults to
 495 .Pa /var/db/ports .
 496 Each port where
 497 .Va OPTIONS
 498 have been configured will have a uniquely named sub-directory, containing a
 499 single file
 500 .Pa options .
 501 .El
 502 .Sh FILES
 503 .Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact
 504 .It Pa /usr/ports
 505 The default ports directory
 506 .No ( Fx
 507 and
 508 .Ox ) .
 509 .It Pa /usr/pkgsrc
 510 The default ports directory
 511 .Pq Nx .
 512 .It Pa /usr/ports/Mk/bsd.port.mk
 513 The big Kahuna.
 514 .El
 515 .Sh SEE ALSO
 516 .Xr make 1 ,
 517 .Xr pkg_add 1 ,
 518 .Xr pkg_create 1 ,
 519 .Xr pkg_delete 1 ,
 520 .Xr pkg_info 1 ,
 521 .Xr pkg_version 1
 522 .Pp
 523 The following are part of the ports collection:
 524 .Pp
 525 .Xr portaudit 1 ,
 526 .Xr portcheckout 1 ,
 527 .Xr portlint 1
 528 .Rs
 529 .%B "The FreeBSD Handbook"
 530 .Re
 531 .Pp
 532 .Pa http://www.FreeBSD.org/ports
 533 (searchable index of all ports)
 534 .Sh HISTORY
 535 The Ports Collection
 536 appeared in
 537 .Fx 1.0 .
 538 It has since spread to
 539 .Nx
 540 and
 541 .Ox .
 542 .Sh AUTHORS
 543 .An -nosplit
 544 This manual page was originated by
 545 .An David O'Brien .
 546 .Sh BUGS
 547 Ports documentation is split over four places \(em
 548 .Pa /usr/ports/Mk/bsd.port.mk ,
 549 .%B "The Porter's Handbook" ,
 550 the
 551 .Dq "Packages and Ports"
 552 chapter of
 553 .%B "The FreeBSD Handbook" ,
 554 and
 555 this manual page.