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