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 June 16, 2004 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 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 122and 123.Va MASTER_SITE_OVERRIDE . 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 rmconfig 172Remove 173.Va OPTIONS 174config for this port. 175.It Cm fetch-list 176Show list of files to be fetched in order to build the port. 177.It Cm fetch-recursive 178Fetch the distfiles of the port and all its dependencies. 179.It Cm fetch-recursive-list 180Show list of files that would be retrieved by 181.Cm fetch-recursive . 182.It Cm pretty-print-run-depends-list , pretty-print-build-depends-list 183Print a list of all the compile and run dependencies, and dependencies 184of those dependencies. 185.It Cm clean 186Remove the expanded source code. 187This recurses to dependencies unless 188.Va NOCLEANDEPENDS 189is defined. 190.It Cm distclean 191Remove the port's distfiles and perform the 192.Cm clean 193target. 194The 195.Cm clean 196portion recurses to dependencies unless 197.Va NOCLEANDEPENDS 198is defined, but the 199.Cm distclean 200portion never recurses 201(this is perhaps a bug). 202.It Cm reinstall 203Use this to restore a port after using 204.Xr pkg_delete 1 205when you should have used 206.Cm deinstall . 207.It Cm deinstall 208Remove an installed port from the system, similar to 209.Xr pkg_delete 1 . 210.It Cm deinstall-all 211Remove all installed ports with the same 212.Va PKGORIGIN 213from the system. 214.It Cm package 215Make a binary package for the port. 216The port will be installed if it has not already been. 217The package is a 218.Pa .tbz 219file that you can use to 220install the port on other machines with 221.Xr pkg_add 1 . 222If the directory specified by 223.Va PACKAGES 224does not exist, the package will be put into the current directory. 225See 226.Va PKGREPOSITORY 227and 228.Va PKGFILE . 229.It Cm package-recursive 230Like 231.Cm package , 232but makes a package for each depending port as well. 233.It Cm readmes 234Create a port's 235.Pa README.html . 236This can be used from 237.Pa /usr/ports 238to create a browsable web of all ports on your system! 239.It Cm search 240Search the 241.Pa INDEX 242file for the pattern specified by the 243.Va key 244(searches the port name, comment, and dependencies), 245.Va name 246(searches the port name only), 247.Va path 248(searches the port path), 249.Va info 250(searches the port info), 251.Va maint 252(searches the port maintainer), 253.Va cat 254(searches the port category), 255.Va bdeps 256(searches the port build-time dependency), 257.Va rdeps 258(searches the port run-time dependency) 259.Xr make 1 260variables, and their exclusion counterparts: 261.Va xname , xkey 262etc. 263For example, one would type: 264.Pp 265.Dl "cd /usr/ports && make search name=query" 266.Pp 267to find all ports whose 268name matches 269.Dq Li query . 270Results include the matching ports' path, comment, maintainer, 271build dependencies, and run dependencies. 272.Bd -literal -offset indent 273cd /usr/ports && make search name=pear- \e 274 xbdeps=apache 275.Ed 276.Pp 277To find all ports whose 278names contain 279.Dq Li pear- 280and which do not have apache 281listed in build-time dependencies. 282.Bd -literal -offset indent 283cd /usr/ports && make search name=pear- \e 284 xname='ht(tp|ml)' 285.Ed 286.Pp 287To find all ports whose names contain 288.Dq Li pear- , 289but not 290.Dq Li html 291or 292.Dq Li http . 293.Bd -literal -offset indent 294make search key=apache display=name,path,info keylim=1 295.Ed 296.Pp 297To find ports that contain 298.Dq Li apache 299in either of the name, path, info 300fields, ignore the rest of the record. 301.It Cm describe 302Generate a one-line description of each port for use in the 303.Pa INDEX 304file. 305.It Cm index 306Create 307.Pa /usr/ports/INDEX , 308which is used by the 309.Cm pretty-print-* 310and 311.Cm search 312targets. 313Running the 314.Cm index 315target will ensure your 316.Pa INDEX 317file is up to date with your ports tree. 318.It Cm fetchindex 319Fetch the 320.Pa INDEX 321file from the 322.Fx 323cluster. 324.El 325.Sh ENVIRONMENT 326You can change all of these. 327.Bl -tag -width ".Va MASTER_SITES" 328.It Va PORTSDIR 329Location of the ports tree. 330This is 331.Pa /usr/ports 332on 333.Fx 334and 335.Ox , 336and 337.Pa /usr/pkgsrc 338on 339.Nx . 340.It Va WRKDIRPREFIX 341Where to create any temporary files. 342Useful if 343.Va PORTSDIR 344is read-only (perhaps mounted from a CD-ROM). 345.It Va DISTDIR 346Where to find/put distfiles, normally 347.Pa distfiles/ 348in 349.Va PORTSDIR . 350.It Va PACKAGES 351Used only for the 352.Cm package 353target; the base directory for the packages tree, normally 354.Pa packages/ 355in 356.Va PORTSDIR . 357If this directory exists, the package tree will be (partially) constructed. 358This directory does not have to exist; if it does not, packages will be 359placed into the current directory, or you can define one of 360.Bl -tag -width ".Va PKGREPOSITORY" 361.It Va PKGREPOSITORY 362Directory to put the package in. 363.It Va PKGFILE 364The full path to the package. 365.El 366.It Va PREFIX 367Where to install things in general 368(usually 369.Pa /usr/local 370or 371.Pa /usr/X11R6 ) . 372.It Va MASTER_SITES 373Primary sites for distribution files if not found locally. 374.It Va PATCH_SITES 375Primary locations for distribution patch files if not found 376locally. 377.It Va MASTER_SITE_FREEBSD 378If set, go to the master 379.Fx 380site for all files. 381.It Va MASTER_SITE_OVERRIDE 382Try going to these sites for all files and patches, first. 383.It Va NOCLEANDEPENDS 384If defined, do not let 385.Cm clean 386recurse to dependencies. 387.It Va FETCH_CMD 388Command to use to fetch files. 389Normally 390.Xr fetch 1 . 391.It Va FORCE_PKG_REGISTER 392If set, overwrite any existing package registration on the system. 393.It Va MOTIFLIB 394Location of 395.Pa libXm. Ns Brq Pa a , Ns Pa so . 396.It Va INTERACTIVE 397If defined, only operate on a port if it requires interaction. 398.It Va BATCH 399If defined, only operate on a port if it can be installed 100% automatically. 400.It Va OPTIONS 401If defined, list of what 402.Va WITH_* 403options this port accepts. 404.Em Note : 405to make 406.Va OPTIONS 407actually work, it is necessary to include 408.Pa bsd.port.pre.mk 409before starting to test the 410.Va WITH_* 411variables. 412.El 413.Sh FILES 414.Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact 415.It Pa /usr/ports 416The default ports directory 417.No ( Fx 418and 419.Ox ) . 420.It Pa /usr/pkgsrc 421The default ports directory 422.Pq Nx . 423.It Pa /usr/ports/Mk/bsd.port.mk 424The big Kahuna. 425.El 426.Sh SEE ALSO 427.Xr make 1 , 428.Xr pkg_add 1 , 429.Xr pkg_create 1 , 430.Xr pkg_delete 1 , 431.Xr pkg_info 1 , 432.Xr pkg_version 1 433.Pp 434The following are part of the ports collection: 435.Pp 436.Xr pib 1 , 437.Xr portcheckout 1 , 438.Xr portlint 1 439.Rs 440.%B "The FreeBSD Handbook" 441.Re 442.Pp 443.Pa http://www.FreeBSD.org/ports 444(searchable index of all ports) 445.Sh AUTHORS 446.An -nosplit 447This man page was originated by 448.An David O'Brien . 449.Sh HISTORY 450The Ports Collection 451appeared in 452.Fx 1.0 . 453It has since spread to 454.Nx 455and 456.Ox . 457.Sh BUGS 458Ports documentation is split over four places \(em 459.Pa /usr/ports/Mk/bsd.port.mk , 460.%B "The Porter's Handbook" , 461the 462.Dq "Packages and Ports" 463chapter of 464.%B "The FreeBSD Handbook" , 465and 466this man page. 467.Pp 468This man page is too long. 469