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