share/man/man7/dports.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: src/share/man/man7/ports.7,v 1.76 2013/03/05 00:49:42 svnexp Exp $
  27 .\"
  28 .Dd May 23, 2013
  29 .Dt DPORTS 7
  30 .Os
  31 .Sh NAME
  32 .Nm dports
  33 .Nd contributed applications
  34 .Sh DESCRIPTION
  35 The
  36 .Dx
  37 dports collection
  38 offers a simple way for users and
  39 administrators to install applications.
  40 dports is based on
  41 .Fx Ap s
  42 ports collection and most of ports' documentation applies.
  43 .Pp
  44 Each
  45 .Em port
  46 contains any patches necessary to make the original
  47 application source code compile and run on
  48 .Dx .
  49 Compiling an
  50 application is as simple as typing
  51 .Nm make Cm build
  52 in the port directory!
  53 The
  54 .Pa Makefile
  55 automatically fetches the
  56 application source code, either from a local disk or via FTP, unpacks it
  57 on your system, applies the patches, and compiles it.
  58 If all goes well,
  59 simply type
  60 .Nm make Cm install
  61 to install the application.
  62 .Pp
  63 For more information about using ports, see
  64 .Dq "Packages and Ports"
  65 in
  66 .%B "The FreeBSD Handbook" ,
  67 .Pa ( file:/usr/share/doc/en_US.ISO8859-1/books/handbook/ports.html
  68 or
  69 .Pa http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/ports.html ) .
  70 For information about creating new ports, see
  71 .%B "The Porter's Handbook"
  72 .Pa ( file:/usr/share/doc/en_US.ISO8859-1/books/porters-handbook/index.html
  73 or
  74 .Pa http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/porters-handbook/ ) .
  75 .Sh TARGETS
  76 Some of the targets work recursively through subdirectories.
  77 This lets you, for example, install all of the
  78 .Dq Li biology
  79 ports.
  80 The targets that do this are
  81 .Cm build , checksum , clean , configure ,
  82 .Cm depends , extract , fetch , install ,
  83 and
  84 .Cm package .
  85 .Pp
  86 The following targets will be run automatically by each proceeding
  87 target in order.
  88 That is,
  89 .Cm build
  90 will be run
  91 (if necessary)
  92 by
  93 .Cm install ,
  94 and so on all the way to
  95 .Cm fetch .
  96 Usually, you will only use the
  97 .Cm install
  98 target.
  99 .Bl -tag -width ".Cm configure"
 100 .It Cm config
 101 Configure
 102 .Va OPTIONS
 103 for this port using
 104 .Xr dialog 1 .
 105 .It Cm fetch
 106 Fetch all of the files needed to build this port from the sites
 107 listed in
 108 .Va MASTER_SITES
 109 and
 110 .Va PATCH_SITES .
 111 See
 112 .Va FETCH_CMD , MASTER_SITE_OVERRIDE
 113 and
 114 .Va MASTER_SITE_BACKUP .
 115 .It Cm checksum
 116 Verify that the fetched distfile's checksum matches the one the port was
 117 tested against.
 118 If the distfile's checksum does not match, it also fetches the distfiles
 119 which are missing or failed the checksum calculation.
 120 Defining
 121 .Va NO_CHECKSUM
 122 will skip this step.
 123 .It Cm depends
 124 Install
 125 (or compile if only compilation is necessary)
 126 any dependencies of the current port.
 127 When called by the
 128 .Cm extract
 129 or
 130 .Cm fetch
 131 targets, this is run in piecemeal as
 132 .Cm fetch-depends , build-depends ,
 133 etc.
 134 Defining
 135 .Va NO_DEPENDS
 136 will skip this step.
 137 .It Cm extract
 138 Expand the distfile into a work directory.
 139 .It Cm patch
 140 Apply any patches that are necessary for the port.
 141 .It Cm configure
 142 Configure the port.
 143 Some ports will ask you questions during this stage.
 144 See
 145 .Va INTERACTIVE
 146 and
 147 .Va BATCH .
 148 .It Cm build
 149 Build the port.
 150 This is the same as calling the
 151 .Cm all
 152 target.
 153 .It Cm install
 154 Install the port and register it with the package system.
 155 This is all you really need to do.
 156 .El
 157 .Pp
 158 The following targets are not run during the normal install process.
 159 .Bl -tag -width ".Cm fetch-recursive"
 160 .It Cm showconfig
 161 Display
 162 .Va OPTIONS
 163 config for this port.
 164 .It Cm showconfig-recursive
 165 Display
 166 .Va OPTIONS
 167 config for this port and all its dependencies.
 168 .It Cm rmconfig
 169 Remove
 170 .Va OPTIONS
 171 config for this port.
 172 .It Cm rmconfig-recursive
 173 Remove
 174 .Va OPTIONS
 175 config for this port and all its dependencies.
 176 .It Cm config-conditional
 177 Skip the ports which have already had their
 178 .Va OPTIONS
 179 configured.
 180 .It Cm config-recursive
 181 Configure
 182 .Va OPTIONS
 183 for this port and all its dependencies using
 184 .Xr dialog 1 .
 185 .It Cm fetch-list
 186 Show list of files to be fetched in order to build the port.
 187 .It Cm fetch-recursive
 188 Fetch the distfiles of the port and all its dependencies.
 189 .It Cm fetch-recursive-list
 190 Show list of files that would be retrieved by
 191 .Cm fetch-recursive .
 192 .It Cm run-depends-list , build-depends-list
 193 Print a list of all the compile and run dependencies, and dependencies
 194 of those dependencies, by port directory.
 195 .It Cm all-depends-list
 196 Print a list of all dependencies for the port.
 197 .It Cm pretty-print-run-depends-list , pretty-print-build-depends-list
 198 Print a list of all the compile and run dependencies, and dependencies
 199 of those dependencies, by port name and version.
 200 .It Cm missing
 201 Print a list of missing dependencies to be installed for the port.
 202 .It Cm clean
 203 Remove the expanded source code.
 204 This recurses to dependencies unless
 205 .Va NOCLEANDEPENDS
 206 is defined.
 207 .It Cm distclean
 208 Remove the port's distfiles and perform the
 209 .Cm clean
 210 target.
 211 The
 212 .Cm clean
 213 portion recurses to dependencies unless
 214 .Va NOCLEANDEPENDS
 215 is defined, but the
 216 .Cm distclean
 217 portion never recurses
 218 (this is perhaps a bug).
 219 .It Cm reinstall
 220 Use this to restore a port after using
 221 .Xr pkg_delete 1
 222 when you should have used
 223 .Cm deinstall .
 224 .It Cm deinstall
 225 Remove an installed port from the system, similar to
 226 .Xr pkg_delete 1 .
 227 .It Cm deinstall-all
 228 Remove all installed ports with the same
 229 .Va PKGORIGIN
 230 from the system.
 231 .It Cm package
 232 Make a binary package for the port.
 233 The port will be installed if it has not already been.
 234 The package is a
 235 .Pa .tbz
 236 file that you can use to
 237 install the port on other machines with
 238 .Xr pkg_add 1 .
 239 If the directory specified by
 240 .Va PACKAGES
 241 does not exist, the package will be put into the current directory.
 242 See
 243 .Va PKGREPOSITORY
 244 and
 245 .Va PKGFILE .
 246 .It Cm package-recursive
 247 Like
 248 .Cm package ,
 249 but makes a package for each depending port as well.
 250 .It Cm package-name
 251 Prints the name with version of the port.
 252 .It Cm readmes
 253 Create a port's
 254 .Pa README.html .
 255 This can be used from
 256 .Pa /usr/dports
 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/dports && 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/dports && 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/dports && 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-sensitive.
 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/dports/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/dports
 368 on
 369 .Dx ,
 370 .Pa /usr/ports
 371 on
 372 .Fx
 373 and
 374 .Ox ,
 375 and
 376 .Pa /usr/pkgsrc
 377 on
 378 .Nx .
 379 .It Va WRKDIRPREFIX
 380 Where to create any temporary files.
 381 Useful if
 382 .Va PORTSDIR
 383 is read-only (perhaps mounted from a CD-ROM).
 384 Its default value is /usr/obj/dports .
 385 .It Va DISTDIR
 386 Where to find/put distfiles, normally
 387 .Pa /usr/distfiles .
 388 .It Va PACKAGES
 389 Used only for the
 390 .Cm package
 391 target; the base directory for the packages tree, normally
 392 .Pa /usr/packages .
 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 LOCALBASE
 403 Where existing things are installed and where to search for files when
 404 resolving dependencies (usually
 405 .Pa /usr/local ) .
 406 .It Va PREFIX
 407 Where to install this port (usually set to the same as
 408 .Va LOCALBASE ) .
 409 .It Va MASTER_SITES
 410 Primary sites for distribution files if not found locally.
 411 .It Va PATCH_SITES
 412 Primary locations for distribution patch files if not found
 413 locally.
 414 .It Va MASTER_SITE_FREEBSD
 415 If set, go to the master
 416 .Fx
 417 site for all files.
 418 .It Va MASTER_SITE_OVERRIDE
 419 Try going to these sites for all files and patches, first.
 420 .It Va MASTER_SITE_BACKUP
 421 Try going to these sites for all files and patches, last.
 422 .It Va RANDOMIZE_MASTER_SITES
 423 Try the download locations in a random order.
 424 .It Va MASTER_SORT
 425 Sort the download locations according to user supplied pattern.
 426 Example:
 427 .Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net
 428 .\".It Va MASTER_SITE_INDEX
 429 .\"Where to get
 430 .\".Pa INDEX
 431 .\"source built on
 432 .\".Fx
 433 .\"cluster (for
 434 .\".Cm fetchindex
 435 .\"target).
 436 .\"Defaults to
 437 .\".Pa http://www.FreeBSD.org/ports/ .
 438 .\".It Va FETCHINDEX
 439 .\"Command to get
 440 .\".Pa INDEX
 441 .\"(for
 442 .\".Cm fetchindex
 443 .\"target).
 444 .\"Defaults to
 445 .\".Dq Nm fetch Fl am .
 446 .It Va NOCLEANDEPENDS
 447 If defined, do not let
 448 .Cm clean
 449 recurse to dependencies.
 450 .It Va FETCH_CMD
 451 Command to use to fetch files.
 452 Normally
 453 .Xr fetch 1 .
 454 .It Va FORCE_PKG_REGISTER
 455 If set, overwrite any existing package registration on the system.
 456 .It Va MOTIFLIB
 457 Location of
 458 .Pa libXm. Ns Brq Pa a , Ns Pa so .
 459 .It Va INTERACTIVE
 460 If defined, only operate on a port if it requires interaction.
 461 .It Va BATCH
 462 If defined, only operate on a port if it can be installed 100% automatically.
 463 .It Va DISABLE_VULNERABILITIES
 464 If defined, disable check for security vulnerabilities using
 465 .Xr portaudit 1 Pq Pa ports/ports-mgmt/portaudit
 466 when installing new ports.
 467 .It Va NO_IGNORE
 468 If defined, allow installation of ports marked as
 469 .Aq Va FORBIDDEN .
 470 The default behavior of the Ports framework is to abort when the
 471 installation of a forbidden port is attempted.
 472 Of course, these ports may not work as expected, but if you really know
 473 what you are doing and are sure about installing a forbidden port, then
 474 .Va NO_IGNORE
 475 lets you do it.
 476 .It Va NO_CHECKSUM
 477 If defined, skip verifying the port's checksum.
 478 .It Va TRYBROKEN
 479 If defined, attempt to build a port even if it is marked as
 480 .Aq Va BROKEN .
 481 .It Va PORT_DBDIR
 482 Directory where the results of configuring
 483 .Va OPTIONS
 484 are stored.
 485 Defaults to
 486 .Pa /var/db/ports .
 487 Each port where
 488 .Va OPTIONS
 489 have been configured will have a uniquely named sub-directory, containing a
 490 single file
 491 .Pa options .
 492 .El
 493 .Sh FILES
 494 .Bl -tag -width ".Pa /usr/dports/Mk/bsd.port.mk" -compact
 495 .It Pa /usr/dports
 496 The default ports directory
 497 .It Pa /usr/dports/Mk/bsd.port.mk
 498 The big Kahuna.
 499 .El
 500 .Sh SEE ALSO
 501 .Xr make 1 ,
 502 .Xr pkg 8
 503 .\".Xr portsnap 8
 504 .Pp
 505 The following are part of the ports collection:
 506 .Pp
 507 .Xr portaudit 1 ,
 508 .Xr portlint 1
 509 .Rs
 510 .%B "The FreeBSD Handbook"
 511 .Re
 512 .Pp
 513 .Pa http://www.FreeBSD.org/ports
 514 (searchable index of all ports)
 515 .Sh HISTORY
 516 The Ports Collection
 517 appeared in
 518 .Fx 1.0 .
 519 It has since spread to
 520 .Nx ,
 521 .Ox
 522 and
 523 .Dx .
 524 .Sh AUTHORS
 525 .An -nosplit
 526 This manual page was originated by
 527 .An David O'Brien .
 528 .Sh BUGS
 529 Ports documentation is split over four places \(em
 530 .Pa /usr/dports/Mk/bsd.port.mk ,
 531 .%B "The Porter's Handbook" ,
 532 the
 533 .Dq "Packages and Ports"
 534 chapter of
 535 .%B "The FreeBSD Handbook" ,
 536 and
 537 this manual page.