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