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