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 6, 2014 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.Fx . 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 59For more information about using ports, see 60.Dq "Packages and Ports" 61in 62.%B "The FreeBSD Handbook" , 63.Pa ( file:/usr/share/doc/en_US.ISO8859-1/books/handbook/ports.html 64or 65.Pa https://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/ports.html ) . 66For information about creating new ports, see 67.%B "The Porter's Handbook" 68.Pa ( file:/usr/share/doc/en_US.ISO8859-1/books/porters-handbook/index.html 69or 70.Pa https://www.FreeBSD.org/doc/en_US.ISO8859-1/books/porters-handbook/ ) . 71.Sh TARGETS 72Some of the targets work recursively through subdirectories. 73This lets you, for example, install all of the 74.Dq Li biology 75ports. 76The targets that do this are 77.Cm build , checksum , clean , configure , 78.Cm depends , extract , fetch , install , 79and 80.Cm package . 81.Pp 82The following targets will be run automatically by each proceeding 83target in order. 84That is, 85.Cm build 86will be run 87(if necessary) 88by 89.Cm install , 90and so on all the way to 91.Cm fetch . 92Usually, you will only use the 93.Cm install 94target. 95.Bl -tag -width ".Cm configure" 96.It Cm config 97Configure 98.Va OPTIONS 99for this port using 100.Xr dialog4ports 1 . 101.It Cm fetch 102Fetch all of the files needed to build this port from the sites 103listed in 104.Va MASTER_SITES 105and 106.Va PATCH_SITES . 107See 108.Va FETCH_CMD , MASTER_SITE_OVERRIDE 109and 110.Va MASTER_SITE_BACKUP . 111.It Cm checksum 112Verify that the fetched distfile's checksum matches the one the port was 113tested against. 114If the distfile's checksum does not match, it also fetches the distfiles 115which are missing or failed the checksum calculation. 116Defining 117.Va NO_CHECKSUM 118will skip this step. 119.It Cm depends 120Install 121(or compile if only compilation is necessary) 122any dependencies of the current port. 123When called by the 124.Cm extract 125or 126.Cm fetch 127targets, this is run in piecemeal as 128.Cm fetch-depends , build-depends , 129etc. 130Defining 131.Va NO_DEPENDS 132will skip this step. 133.It Cm extract 134Expand the distfile into a work directory. 135.It Cm patch 136Apply any patches that are necessary for the port. 137.It Cm configure 138Configure the port. 139Some ports will ask you questions during this stage. 140See 141.Va INTERACTIVE 142and 143.Va BATCH . 144.It Cm build 145Build the port. 146This is the same as calling the 147.Cm all 148target. 149.It Cm install 150Install the port and register it with the package system. 151This is all you really need to do. 152.El 153.Pp 154The following targets are not run during the normal install process. 155.Bl -tag -width ".Cm fetch-recursive" 156.It Cm showconfig 157Display 158.Va OPTIONS 159config for this port. 160.It Cm showconfig-recursive 161Display 162.Va OPTIONS 163config for this port and all its dependencies. 164.It Cm rmconfig 165Remove 166.Va OPTIONS 167config for this port. 168.It Cm rmconfig-recursive 169Remove 170.Va OPTIONS 171config for this port and all its dependencies. 172.It Cm config-conditional 173Skip the ports which have already had their 174.Va OPTIONS 175configured. 176.It Cm config-recursive 177Configure 178.Va OPTIONS 179for this port and all its dependencies using 180.Xr dialog4ports 1 . 181.It Cm fetch-list 182Show list of files to be fetched in order to build the port. 183.It Cm fetch-recursive 184Fetch the distfiles of the port and all its dependencies. 185.It Cm fetch-recursive-list 186Show list of files that would be retrieved by 187.Cm fetch-recursive . 188.It Cm run-depends-list , build-depends-list 189Print a list of all the compile and run dependencies, and dependencies 190of those dependencies, by port directory. 191.It Cm all-depends-list 192Print a list of all dependencies for the port. 193.It Cm pretty-print-run-depends-list , pretty-print-build-depends-list 194Print a list of all the compile and run dependencies, and dependencies 195of those dependencies, by port name and version. 196.It Cm missing 197Print a list of missing dependencies to be installed for the port. 198.It Cm clean 199Remove the expanded source code. 200This recurses to dependencies unless 201.Va NOCLEANDEPENDS 202is defined. 203.It Cm distclean 204Remove the port's distfiles and perform the 205.Cm clean 206target. 207The 208.Cm clean 209portion recurses to dependencies unless 210.Va NOCLEANDEPENDS 211is defined, but the 212.Cm distclean 213portion never recurses 214(this is perhaps a bug). 215.It Cm reinstall 216Use this to restore a port after using 217.Xr pkg-delete 8 218when you should have used 219.Cm deinstall . 220.It Cm deinstall 221Remove an installed port from the system, similar to 222.Xr pkg-delete 8 . 223.It Cm deinstall-all 224Remove all installed ports with the same 225.Va PKGORIGIN 226from the system. 227.It Cm package 228Make a binary package for the port. 229The port will be installed if it has not already been. 230The package is a 231.Pa .tbz 232file that you can use to 233install the port on other machines with 234.Xr pkg-add 8 . 235If the directory specified by 236.Va PACKAGES 237does not exist, the package will be put into the current directory. 238See 239.Va PKGREPOSITORY 240and 241.Va PKGFILE . 242.It Cm package-recursive 243Like 244.Cm package , 245but makes a package for each depending port as well. 246.It Cm package-name 247Prints the name with version of the port. 248.It Cm readmes 249Create a port's 250.Pa README.html . 251This can be used from 252.Pa /usr/ports 253to create a browsable web of all ports on your system! 254.It Cm search 255Search the 256.Pa INDEX 257file for the pattern specified by the 258.Va key 259(searches the port name, comment, and dependencies), 260.Va name 261(searches the port name only), 262.Va path 263(searches the port path), 264.Va info 265(searches the port info), 266.Va maint 267(searches the port maintainer), 268.Va cat 269(searches the port category), 270.Va bdeps 271(searches the port build-time dependency), 272.Va rdeps 273(searches the port run-time dependency), 274.Va www 275(searches the port web site) 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.Pp 319By default the search is not case-sensitive. 320In order to make it case-sensitive you can use the 321.Va icase 322variable: 323.Bd -literal -offset indent 324make search name=p5-R icase=0 325.Ed 326.It Cm quicksearch 327Reduced 328.Cm search 329output. 330Only display name, path and info. 331.It Cm describe 332Generate a one-line description of each port for use in the 333.Pa INDEX 334file. 335.It Cm maintainer 336Display the port maintainer's email address. 337.It Cm index 338Create 339.Pa /usr/ports/INDEX , 340which is used by the 341.Cm pretty-print-* 342and 343.Cm search 344targets. 345Running the 346.Cm index 347target will ensure your 348.Pa INDEX 349file is up to date with your ports tree. 350.It Cm fetchindex 351Fetch the 352.Pa INDEX 353file from the 354.Fx 355cluster. 356.El 357.Sh ENVIRONMENT 358You can change all of these. 359.Bl -tag -width ".Va MASTER_SITES" 360.It Va PORTSDIR 361Location of the ports tree. 362This is 363.Pa /usr/ports 364on 365.Fx 366and 367.Ox , 368and 369.Pa /usr/pkgsrc 370on 371.Nx . 372.It Va WRKDIRPREFIX 373Where to create any temporary files. 374Useful if 375.Va PORTSDIR 376is read-only (perhaps mounted from a CD-ROM). 377.It Va DISTDIR 378Where to find/put distfiles, normally 379.Pa distfiles/ 380in 381.Va PORTSDIR . 382.It Va PACKAGES 383Used only for the 384.Cm package 385target; the base directory for the packages tree, normally 386.Pa packages/ 387in 388.Va PORTSDIR . 389If this directory exists, the package tree will be (partially) constructed. 390This directory does not have to exist; if it does not, packages will be 391placed into the current directory, or you can define one of 392.Bl -tag -width ".Va PKGREPOSITORY" 393.It Va PKGREPOSITORY 394Directory to put the package in. 395.It Va PKGFILE 396The full path to the package. 397.El 398.It Va LOCALBASE 399Where existing things are installed and where to search for files when 400resolving dependencies (usually 401.Pa /usr/local ) . 402.It Va PREFIX 403Where to install this port (usually set to the same as 404.Va LOCALBASE ) . 405.It Va MASTER_SITES 406Primary sites for distribution files if not found locally. 407.It Va PATCH_SITES 408Primary locations for distribution patch files if not found 409locally. 410.It Va MASTER_SITE_FREEBSD 411If set, go to the master 412.Fx 413site for all files. 414.It Va MASTER_SITE_OVERRIDE 415Try going to these sites for all files and patches, first. 416.It Va MASTER_SITE_BACKUP 417Try going to these sites for all files and patches, last. 418.It Va RANDOMIZE_MASTER_SITES 419Try the download locations in a random order. 420.It Va MASTER_SORT 421Sort the download locations according to user supplied pattern. 422Example: 423.Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net 424.It Va MASTER_SITE_INDEX 425Where to get 426.Pa INDEX 427source built on 428.Fx 429cluster (for 430.Cm fetchindex 431target). 432Defaults to 433.Pa https://www.FreeBSD.org/ports/ . 434.It Va FETCHINDEX 435Command to get 436.Pa INDEX 437(for 438.Cm fetchindex 439target). 440Defaults to 441.Dq Nm fetch Fl am . 442.It Va NOCLEANDEPENDS 443If defined, do not let 444.Cm clean 445recurse to dependencies. 446.It Va FETCH_CMD 447Command to use to fetch files. 448Normally 449.Xr fetch 1 . 450.It Va FORCE_PKG_REGISTER 451If set, overwrite any existing package registration on the system. 452.It Va MOTIFLIB 453Location of 454.Pa libXm. Ns Brq Pa a , Ns Pa so . 455.It Va INTERACTIVE 456If defined, only operate on a port if it requires interaction. 457.It Va BATCH 458If defined, only operate on a port if it can be installed 100% automatically. 459.It Va DISABLE_VULNERABILITIES 460If defined, disable check for security vulnerabilities using 461.Xr pkg-audit 8 462when installing new ports. 463.It Va NO_IGNORE 464If defined, allow installation of ports marked as 465.Aq Va FORBIDDEN . 466The default behavior of the Ports framework is to abort when the 467installation of a forbidden port is attempted. 468Of course, these ports may not work as expected, but if you really know 469what you are doing and are sure about installing a forbidden port, then 470.Va NO_IGNORE 471lets you do it. 472.It Va NO_CHECKSUM 473If defined, skip verifying the port's checksum. 474.It Va TRYBROKEN 475If defined, attempt to build a port even if it is marked as 476.Aq Va BROKEN . 477.It Va PORT_DBDIR 478Directory where the results of configuring 479.Va OPTIONS 480are stored. 481Defaults to 482.Pa /var/db/ports . 483Each port where 484.Va OPTIONS 485have been configured will have a uniquely named sub-directory, containing a 486single file 487.Pa options . 488.El 489.Sh MAKE VARIABLES 490The following list provides a name and short description for many of the 491variables that are used when building ports. 492More information on these and other related variables may be found in 493.Pa ${PORTSDIR}/Mk/* 494and the 495.Fx 496Porter's Handbook. 497.Bl -tag -width ".Va WITH_GHOSTSCRIPT_VER" 498.It Va WITH_OPENSSL_PORT 499.Pq Vt bool 500If set, causes ports that make use of OpenSSL to use the OpenSSL from 501ports 502.Pq if available 503instead of the OpenSSL from the base system. 504.It Va WITH_DEBUG 505.Pq Vt bool 506If set, debugging symbols are installed for ports binaries. 507.It Va WITH_DEBUG_PORTS 508A list of origins for which to set 509.Va WITH_DEBUG_PORTS . 510.It Va WITH_SSP_PORTS 511.Pq Vt bool 512If set, enables 513.Fl fstack-protector 514for most ports. 515.It Va WITH_GHOSTSCRIPT_VER 516If set, the version of ghostscript to be used by ports. 517.It Va WITH_CCACHE_BUILD 518.Pq Vt bool 519If set, enables the use of 520.Xr ccache 1 521for building ports. 522.It Va CCACHE_DIR 523Which directory to use for the ccache data. 524.El 525.Sh FILES 526.Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact 527.It Pa /usr/ports 528The default ports directory 529.It Pa /usr/ports/Mk/bsd.port.mk 530The big Kahuna. 531.El 532.Sh SEE ALSO 533.Xr make 1 , 534.Xr make.conf 5 , 535.Xr pkg 8 , 536.Xr portsnap 8 537.Pp 538The following are part of the ports collection: 539.Pp 540.Xr pkg 7 , 541.Xr portlint 1 542.Rs 543.%B "The FreeBSD Handbook" 544.Re 545.Pp 546.Pa https://www.FreeBSD.org/ports 547(searchable index of all ports) 548.Sh HISTORY 549The Ports Collection 550appeared in 551.Fx 1.0 . 552It has since spread to 553.Nx 554and 555.Ox . 556.Sh AUTHORS 557.An -nosplit 558This manual page was originated by 559.An David O'Brien . 560.Sh BUGS 561Ports documentation is split over four places \(em 562.Pa /usr/ports/Mk/bsd.port.mk , 563.%B "The Porter's Handbook" , 564the 565.Dq "Packages and Ports" 566chapter of 567.%B "The FreeBSD Handbook" , 568and 569this manual page. 570