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