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: src/share/man/man7/ports.7,v 1.76 2013/03/05 00:49:42 svnexp Exp $ 27.\" 28.Dd May 23, 2013 29.Dt DPORTS 7 30.Os 31.Sh NAME 32.Nm dports 33.Nd contributed applications 34.Sh DESCRIPTION 35The 36.Dx 37dports collection 38offers a simple way for users and 39administrators to install applications. 40dports is based on 41.Fx Ap s 42ports collection and most of ports' documentation applies. 43.Pp 44Each 45.Em port 46contains any patches necessary to make the original 47application source code compile and run on 48.Dx . 49Compiling an 50application is as simple as typing 51.Nm make Cm build 52in the port directory! 53The 54.Pa Makefile 55automatically fetches the 56application source code, either from a local disk or via FTP, unpacks it 57on your system, applies the patches, and compiles it. 58If all goes well, 59simply type 60.Nm make Cm install 61to install the application. 62.Pp 63For more information about using ports, see 64.Dq "Packages and Ports" 65in 66.%B "The FreeBSD Handbook" , 67.Pa ( file:/usr/share/doc/en_US.ISO8859-1/books/handbook/ports.html 68or 69.Pa http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/ports.html ) . 70For information about creating new ports, see 71.%B "The Porter's Handbook" 72.Pa ( file:/usr/share/doc/en_US.ISO8859-1/books/porters-handbook/index.html 73or 74.Pa http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/porters-handbook/ ) . 75.Sh TARGETS 76Some of the targets work recursively through subdirectories. 77This lets you, for example, install all of the 78.Dq Li biology 79ports. 80The targets that do this are 81.Cm build , checksum , clean , configure , 82.Cm depends , extract , fetch , install , 83and 84.Cm package . 85.Pp 86The following targets will be run automatically by each proceeding 87target in order. 88That is, 89.Cm build 90will be run 91(if necessary) 92by 93.Cm install , 94and so on all the way to 95.Cm fetch . 96Usually, you will only use the 97.Cm install 98target. 99.Bl -tag -width ".Cm configure" 100.It Cm config 101Configure 102.Va OPTIONS 103for this port using 104.Xr dialog 1 . 105.It Cm fetch 106Fetch all of the files needed to build this port from the sites 107listed in 108.Va MASTER_SITES 109and 110.Va PATCH_SITES . 111See 112.Va FETCH_CMD , MASTER_SITE_OVERRIDE 113and 114.Va MASTER_SITE_BACKUP . 115.It Cm checksum 116Verify that the fetched distfile's checksum matches the one the port was 117tested against. 118If the distfile's checksum does not match, it also fetches the distfiles 119which are missing or failed the checksum calculation. 120Defining 121.Va NO_CHECKSUM 122will skip this step. 123.It Cm depends 124Install 125(or compile if only compilation is necessary) 126any dependencies of the current port. 127When called by the 128.Cm extract 129or 130.Cm fetch 131targets, this is run in piecemeal as 132.Cm fetch-depends , build-depends , 133etc. 134Defining 135.Va NO_DEPENDS 136will skip this step. 137.It Cm extract 138Expand the distfile into a work directory. 139.It Cm patch 140Apply any patches that are necessary for the port. 141.It Cm configure 142Configure the port. 143Some ports will ask you questions during this stage. 144See 145.Va INTERACTIVE 146and 147.Va BATCH . 148.It Cm build 149Build the port. 150This is the same as calling the 151.Cm all 152target. 153.It Cm install 154Install the port and register it with the package system. 155This is all you really need to do. 156.El 157.Pp 158The following targets are not run during the normal install process. 159.Bl -tag -width ".Cm fetch-recursive" 160.It Cm showconfig 161Display 162.Va OPTIONS 163config for this port. 164.It Cm showconfig-recursive 165Display 166.Va OPTIONS 167config for this port and all its dependencies. 168.It Cm rmconfig 169Remove 170.Va OPTIONS 171config for this port. 172.It Cm rmconfig-recursive 173Remove 174.Va OPTIONS 175config for this port and all its dependencies. 176.It Cm config-conditional 177Skip the ports which have already had their 178.Va OPTIONS 179configured. 180.It Cm config-recursive 181Configure 182.Va OPTIONS 183for this port and all its dependencies using 184.Xr dialog 1 . 185.It Cm fetch-list 186Show list of files to be fetched in order to build the port. 187.It Cm fetch-recursive 188Fetch the distfiles of the port and all its dependencies. 189.It Cm fetch-recursive-list 190Show list of files that would be retrieved by 191.Cm fetch-recursive . 192.It Cm run-depends-list , build-depends-list 193Print a list of all the compile and run dependencies, and dependencies 194of those dependencies, by port directory. 195.It Cm all-depends-list 196Print a list of all dependencies for the port. 197.It Cm pretty-print-run-depends-list , pretty-print-build-depends-list 198Print a list of all the compile and run dependencies, and dependencies 199of those dependencies, by port name and version. 200.It Cm missing 201Print a list of missing dependencies to be installed for the port. 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 package-name 251Prints the name with version of the port. 252.It Cm readmes 253Create a port's 254.Pa README.html . 255This can be used from 256.Pa /usr/dports 257to create a browsable web of all ports on your system! 258.\".It Cm search 259.\"Search the 260.\".Pa INDEX 261.\"file for the pattern specified by the 262.\".Va key 263.\"(searches the port name, comment, and dependencies), 264.\".Va name 265.\"(searches the port name only), 266.\".Va path 267.\"(searches the port path), 268.\".Va info 269.\"(searches the port info), 270.\".Va maint 271.\"(searches the port maintainer), 272.\".Va cat 273.\"(searches the port category), 274.\".Va bdeps 275.\"(searches the port build-time dependency), 276.\".Va rdeps 277.\"(searches the port run-time dependency), 278.\".Va www 279.\"(searches the port web site) 280.\".Xr make 1 281.\"variables, and their exclusion counterparts: 282.\".Va xname , xkey 283.\"etc. 284.\"For example, one would type: 285.\".Pp 286.\".Dl "cd /usr/dports && make search name=query" 287.\".Pp 288.\"to find all ports whose 289.\"name matches 290.\".Dq Li query . 291.\"Results include the matching ports' path, comment, maintainer, 292.\"build dependencies, and run dependencies. 293.\".Bd -literal -offset indent 294.\"cd /usr/dports && make search name=pear- \e 295.\" xbdeps=apache 296.\".Ed 297.\".Pp 298.\"To find all ports whose 299.\"names contain 300.\".Dq Li pear- 301.\"and which do not have apache 302.\"listed in build-time dependencies. 303.\".Bd -literal -offset indent 304.\"cd /usr/dports && make search name=pear- \e 305.\" xname='ht(tp|ml)' 306.\".Ed 307.\".Pp 308.\"To find all ports whose names contain 309.\".Dq Li pear- , 310.\"but not 311.\".Dq Li html 312.\"or 313.\".Dq Li http . 314.\".Bd -literal -offset indent 315.\"make search key=apache display=name,path,info keylim=1 316.\".Ed 317.\".Pp 318.\"To find ports that contain 319.\".Dq Li apache 320.\"in either of the name, path, info 321.\"fields, ignore the rest of the record. 322.\".Pp 323.\"By default the search is not case-sensitive. 324.\"In order to make it case-sensitive you can use the 325.\".Va icase 326.\"variable: 327.\".Bd -literal -offset indent 328.\"make search name=p5-R icase=0 329.\".Ed 330.\".It Cm quicksearch 331.\"Reduced 332.\".Cm search 333.\"output. 334.\"Only display name, path and info. 335.It Cm describe 336Generate a one-line description of each port for use in the 337.Pa INDEX 338file. 339.It Cm maintainer 340Display the port maintainer's email address. 341.\".It Cm index 342.\"Create 343.\".Pa /usr/dports/INDEX , 344.\"which is used by the 345.\".Cm pretty-print-* 346.\"and 347.\".Cm search 348.\"targets. 349.\"Running the 350.\".Cm index 351.\"target will ensure your 352.\".Pa INDEX 353.\"file is up to date with your ports tree. 354.\".It Cm fetchindex 355.\"Fetch the 356.\".Pa INDEX 357.\"file from the 358.\".Fx 359.\"cluster. 360.El 361.Sh ENVIRONMENT 362You can change all of these. 363.Bl -tag -width ".Va MASTER_SITES" 364.It Va PORTSDIR 365Location of the ports tree. 366This is 367.Pa /usr/dports 368on 369.Dx , 370.Pa /usr/ports 371on 372.Fx 373and 374.Ox , 375and 376.Pa /usr/pkgsrc 377on 378.Nx . 379.It Va WRKDIRPREFIX 380Where to create any temporary files. 381Useful if 382.Va PORTSDIR 383is read-only (perhaps mounted from a CD-ROM). 384Its default value is /usr/obj/dports . 385.It Va DISTDIR 386Where to find/put distfiles, normally 387.Pa /usr/distfiles . 388.It Va PACKAGES 389Used only for the 390.Cm package 391target; the base directory for the packages tree, normally 392.Pa /usr/packages . 393If this directory exists, the package tree will be (partially) constructed. 394This directory does not have to exist; if it does not, packages will be 395placed into the current directory, or you can define one of 396.Bl -tag -width ".Va PKGREPOSITORY" 397.It Va PKGREPOSITORY 398Directory to put the package in. 399.It Va PKGFILE 400The full path to the package. 401.El 402.It Va LOCALBASE 403Where existing things are installed and where to search for files when 404resolving dependencies (usually 405.Pa /usr/local ) . 406.It Va PREFIX 407Where to install this port (usually set to the same as 408.Va LOCALBASE ) . 409.It Va MASTER_SITES 410Primary sites for distribution files if not found locally. 411.It Va PATCH_SITES 412Primary locations for distribution patch files if not found 413locally. 414.It Va MASTER_SITE_FREEBSD 415If set, go to the master 416.Fx 417site for all files. 418.It Va MASTER_SITE_OVERRIDE 419Try going to these sites for all files and patches, first. 420.It Va MASTER_SITE_BACKUP 421Try going to these sites for all files and patches, last. 422.It Va RANDOMIZE_MASTER_SITES 423Try the download locations in a random order. 424.It Va MASTER_SORT 425Sort the download locations according to user supplied pattern. 426Example: 427.Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net 428.\".It Va MASTER_SITE_INDEX 429.\"Where to get 430.\".Pa INDEX 431.\"source built on 432.\".Fx 433.\"cluster (for 434.\".Cm fetchindex 435.\"target). 436.\"Defaults to 437.\".Pa http://www.FreeBSD.org/ports/ . 438.\".It Va FETCHINDEX 439.\"Command to get 440.\".Pa INDEX 441.\"(for 442.\".Cm fetchindex 443.\"target). 444.\"Defaults to 445.\".Dq Nm fetch Fl am . 446.It Va NOCLEANDEPENDS 447If defined, do not let 448.Cm clean 449recurse to dependencies. 450.It Va FETCH_CMD 451Command to use to fetch files. 452Normally 453.Xr fetch 1 . 454.It Va FORCE_PKG_REGISTER 455If set, overwrite any existing package registration on the system. 456.It Va MOTIFLIB 457Location of 458.Pa libXm. Ns Brq Pa a , Ns Pa so . 459.It Va INTERACTIVE 460If defined, only operate on a port if it requires interaction. 461.It Va BATCH 462If defined, only operate on a port if it can be installed 100% automatically. 463.It Va DISABLE_VULNERABILITIES 464If defined, disable check for security vulnerabilities using 465.Xr portaudit 1 Pq Pa ports/ports-mgmt/portaudit 466when installing new ports. 467.It Va NO_IGNORE 468If defined, allow installation of ports marked as 469.Aq Va FORBIDDEN . 470The default behavior of the Ports framework is to abort when the 471installation of a forbidden port is attempted. 472Of course, these ports may not work as expected, but if you really know 473what you are doing and are sure about installing a forbidden port, then 474.Va NO_IGNORE 475lets you do it. 476.It Va NO_CHECKSUM 477If defined, skip verifying the port's checksum. 478.It Va TRYBROKEN 479If defined, attempt to build a port even if it is marked as 480.Aq Va BROKEN . 481.It Va PORT_DBDIR 482Directory where the results of configuring 483.Va OPTIONS 484are stored. 485Defaults to 486.Pa /var/db/ports . 487Each port where 488.Va OPTIONS 489have been configured will have a uniquely named sub-directory, containing a 490single file 491.Pa options . 492.El 493.Sh FILES 494.Bl -tag -width ".Pa /usr/dports/Mk/bsd.port.mk" -compact 495.It Pa /usr/dports 496The default ports directory 497.It Pa /usr/dports/Mk/bsd.port.mk 498The big Kahuna. 499.El 500.Sh SEE ALSO 501.Xr make 1 , 502.Xr pkg 8 503.\".Xr portsnap 8 504.Pp 505The following are part of the ports collection: 506.Pp 507.Xr portaudit 1 , 508.Xr portlint 1 509.Rs 510.%B "The FreeBSD Handbook" 511.Re 512.Pp 513.Pa http://www.FreeBSD.org/ports 514(searchable index of all ports) 515.Sh HISTORY 516The Ports Collection 517appeared in 518.Fx 1.0 . 519It has since spread to 520.Nx , 521.Ox 522and 523.Dx . 524.Sh AUTHORS 525.An -nosplit 526This manual page was originated by 527.An David O'Brien . 528.Sh BUGS 529Ports documentation is split over four places \(em 530.Pa /usr/dports/Mk/bsd.port.mk , 531.%B "The Porter's Handbook" , 532the 533.Dq "Packages and Ports" 534chapter of 535.%B "The FreeBSD Handbook" , 536and 537this manual page. 538