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 25, 1998 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 fetch 110Fetch all of the files needed to build this port from the sites 111listed in 112.Va MASTER_SITES 113and 114.Va PATCH_SITES . 115See 116.Va FETCH_CMD 117and 118.Va MASTER_SITE_OVERRIDE . 119.It Cm checksum 120Verify that the fetched distfile's checksum matches the one the port was 121tested against. 122Defining 123.Va NO_CHECKSUM 124will skip this step. 125.It Cm depends 126Install 127(or compile if only compilation is necessary) 128any dependencies of the current port. 129When called by the 130.Cm extract 131or 132.Cm fetch 133targets, this is run in piecemeal as 134.Cm fetch-depends , build-depends , 135etc. 136Defining 137.Va NO_DEPENDS 138will skip this step. 139.It Cm extract 140Expand the distfile into a work directory. 141.It Cm patch 142Apply any patches that are necessary for the port. 143.It Cm configure 144Configure the port. 145Some ports will ask you questions during this stage. 146See 147.Va INTERACTIVE 148and 149.Va BATCH . 150.It Cm build 151Build the port. 152This is the same as calling the 153.Cm all 154target. 155.It Cm install 156Install the port and register it with the package system. 157This is all you really need to do. 158.El 159.Pp 160The following targets are not run during the normal install process. 161.Bl -tag -width ".Cm fetch-recursive" 162.It Cm fetch-list 163Show list of files needed to be fetched in order to build the port. 164.It Cm fetch-recursive 165Fetch the distfiles of the port and all its dependencies. 166.It Cm fetch-recursive-list 167Show list of files that would be retrieved by 168.Cm fetch-recursive . 169.It Cm pretty-print-run-depends-list , pretty-print-build-depends-list 170Print a list of all the compile and run dependencies, and dependencies 171of those dependencies. 172.It Cm clean 173Remove the expanded source code. 174This recurses to dependencies unless 175.Va NOCLEANDEPENDS 176is defined. 177.It Cm distclean 178Remove the port's distfiles and perform the 179.Cm clean 180target. 181The 182.Cm clean 183portion recurses to dependencies unless 184.Va NOCLEANDEPENDS 185is defined, but the 186.Cm distclean 187portion never recurses 188(this is perhaps a bug). 189.It Cm reinstall 190Use this to restore a port after using 191.Xr pkg_delete 1 192when you should have used 193.Cm deinstall . 194.It Cm deinstall 195Remove an installed port from the system, similar to 196.Xr pkg_delete 1 . 197.It Cm deinstall-all 198Remove all installed ports with the same 199.Va PKGORIGIN 200from the system. 201.It Cm package 202Make a binary package for the port. 203The port will be installed if it has not already been. 204The package is a 205.Pa .tbz 206file that you can use to 207install the port on other machines with 208.Xr pkg_add 1 . 209If the directory specified by 210.Va PACKAGES 211does not exist, the package will be put into the current directory. 212See 213.Va PKGREPOSITORY 214and 215.Va PKGFILE . 216.It Cm package-recursive 217Like 218.Cm package , 219but makes a package for each depending port as well. 220.It Cm readmes 221Create a port's 222.Pa README.html . 223This can be used from 224.Pa /usr/ports 225to create a browsable web of all ports on your system! 226.It Cm search 227Search the 228.Pa INDEX 229file for the pattern specified by either the 230.Va key 231(searches the port name, comment, and dependencies) or 232.Va name 233(searches the port name only) 234.Xr make 1 235variable. 236For example, one would type: 237.Pp 238.Dl "cd /usr/ports && make search name=query" 239.Pp 240to find all ports whose 241name matches 242.Dq Li query . 243Results include the matching ports' path, comment, maintainer, 244build dependencies, and run dependencies. 245.It Cm index 246Create 247.Pa /usr/ports/INDEX , 248which is used by the 249.Cm pretty-print-* 250and 251.Cm search 252targets. 253While the master 254.Pa INDEX 255file in the CVS repository is periodically 256updated, running the 257.Cm index 258target will ensure your 259.Pa INDEX 260file is up to date with your ports tree. 261.El 262.Sh ENVIRONMENT 263You can change all of these. 264.Bl -tag -width ".Va MASTER_SITES" 265.It Va PORTSDIR 266Location of the ports tree. 267This is 268.Pa /usr/ports 269on 270.Fx 271and 272.Ox , 273and 274.Pa /usr/pkgsrc 275on 276.Nx . 277.It Va WRKDIRPREFIX 278Where to create any temporary files. 279Useful if 280.Va PORTSDIR 281is read-only (perhaps mounted from a CD-ROM). 282.It Va DISTDIR 283Where to find/put distfiles, normally 284.Pa distfiles/ 285in 286.Va PORTSDIR . 287.It Va PACKAGES 288Used only for the 289.Cm package 290target; the base directory for the packages tree, normally 291.Pa packages/ 292in 293.Va PORTSDIR . 294If this directory exists, the package tree will be (partially) constructed. 295This directory does not have to exist; if it does not, packages will be 296placed into the current directory, or you can define one of 297.Bl -tag -width ".Va PKGREPOSITORY" 298.It Va PKGREPOSITORY 299Directory to put the package in. 300.It Va PKGFILE 301The full path to the package. 302.El 303.It Va PREFIX 304Where to install things in general 305(usually 306.Pa /usr/local 307or 308.Pa /usr/X11R6 ) . 309.It Va MASTER_SITES 310Primary sites for distribution files if not found locally. 311.It Va PATCH_SITES 312Primary locations for distribution patch files if not found 313locally. 314.It Va MASTER_SITE_FREEBSD 315If set, go to the master 316.Fx 317site for all files. 318.It Va MASTER_SITE_OVERRIDE 319Try going to these sites for all files and patches, first. 320.It Va NOCLEANDEPENDS 321If defined, do not let 322.Cm clean 323recurse to dependencies. 324.It Va FETCH_CMD 325Command to use to fetch files. 326Normally 327.Xr fetch 1 . 328.It Va FORCE_PKG_REGISTER 329If set, overwrite any existing package registration on the system. 330.It Va MOTIFLIB 331Location of 332.Pa libXm. Ns Brq Pa a , Ns Pa so . 333.It Va INTERACTIVE 334If defined, only operate on a port if it requires interaction. 335.It Va BATCH 336If defined, only operate on a port if it can be installed 100% automatically. 337.El 338.Sh FILES 339.Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact 340.It Pa /usr/ports 341The default ports directory 342.No ( Fx 343and 344.Ox ) . 345.It Pa /usr/pkgsrc 346The default ports directory 347.Pq Nx . 348.It Pa /usr/ports/Mk/bsd.port.mk 349The big Kahuna. 350.El 351.Sh SEE ALSO 352.Xr make 1 , 353.Xr pkg_add 1 , 354.Xr pkg_create 1 , 355.Xr pkg_delete 1 , 356.Xr pkg_info 1 , 357.Xr pkg_version 1 358.Pp 359The following are part of the ports collection: 360.Pp 361.Xr pib 1 , 362.Xr portcheckout 1 , 363.Xr portlint 1 364.Rs 365.%B "The FreeBSD Handbook" 366.Re 367.Pp 368.Pa http://www.FreeBSD.org/ports 369(searchable index of all ports) 370.Sh AUTHORS 371.An -nosplit 372This man page was originated by 373.An David O'Brien . 374.Sh HISTORY 375The Ports Collection 376appeared in 377.Fx 1.0 . 378It has since spread to 379.Nx 380and 381.Ox . 382.Sh BUGS 383Ports documentation is split over four places \(em 384.Pa /usr/ports/Mk/bsd.port.mk , 385.%B "The Porter's Handbook" , 386the 387.Dq "Packages and Ports" 388chapter of 389.%B "The FreeBSD Handbook" , 390and 391this man page. 392.Pp 393This man page is too long. 394