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