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 November 20, 2018 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 to compile and install third party applications. 39It is also used to build packages, to be installed using 40.Xr pkg 8 . 41It can be installed and updated using 42.Xr portsnap 8 . 43.Pp 44The ports tree, typically located at 45.Pa /usr/ports , 46consists of subdirectories, one for each category; those in turn contain 47individual ports. 48Each port is a directory with metadata and patches necessary to make 49the original application source code compile and run on 50.Fx . 51Compiling an application is as simple as typing 52.Dq Li "make build" 53in the port directory. 54The 55.Pa Makefile 56automatically fetches the 57application source code, either from a local disk or the network, unpacks it, 58applies the patches, and compiles it. 59It also recursively handles dependencies \(em other pieces of software 60the port depends on in order to build and work. 61Afterwards, 62.Dq Li "make install" 63installs the application. 64.Pp 65For more information about using ports, see the 66.Dq "Packages and Ports" section 67in 68.Sm off 69.%B "The FreeBSD Handbook" 70.No \&: 71.Sm on 72.Pp 73.Lk https://www.FreeBSD.org/doc/en/books/handbook/ports.html 74.Pp 75For information about creating new ports, see 76.Sm off 77.%B "The Porter's Handbook" 78.No \&: 79.Sm on 80.Pp 81.Lk https://www.FreeBSD.org/doc/en/books/porters-handbook/ 82.Sh TARGETS 83Some of the 84.Xr make 1 85targets work recursively through subdirectories. 86This lets you, for example, install all of the 87.Dq Li biology 88ports with one command. 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 (if necessary) by 100.Cm install , 101and so on all the way to 102.Cm fetch . 103Usually, you will only use the 104.Cm install 105target. 106.Bl -tag -width ".Cm configure" 107.It Cm config 108Configure 109.Va OPTIONS 110for this port using 111.Xr dialog4ports 1 . 112.It Cm fetch 113Fetch all of the files needed to build this port from the sites 114listed in 115.Va MASTER_SITES 116and 117.Va PATCH_SITES . 118See 119.Va FETCH_CMD , MASTER_SITE_OVERRIDE 120and 121.Va MASTER_SITE_BACKUP . 122.It Cm checksum 123Verify that the fetched distfile's checksum matches the one the port was 124tested against. 125If the distfile's checksum does not match, it also fetches the distfiles 126which are missing or failed the checksum calculation. 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 config-recursive 188Configure 189.Va OPTIONS 190for this port and all its dependencies using 191.Xr dialog4ports 1 . 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 run-depends-list , build-depends-list 200Print a list of all the compile and run dependencies, and dependencies 201of those dependencies, by port directory. 202.It Cm all-depends-list 203Print a list of all dependencies for the port. 204.It Cm pretty-print-run-depends-list , pretty-print-build-depends-list 205Print a list of all the compile and run dependencies, and dependencies 206of those dependencies, by port name and version. 207.It Cm missing 208Print a list of missing dependencies to be installed for the port. 209.It Cm clean 210Remove the expanded source code. 211This recurses to dependencies unless 212.Va NOCLEANDEPENDS 213is defined. 214.It Cm distclean 215Remove the port's distfiles and perform the 216.Cm clean 217target. 218The 219.Cm clean 220portion recurses to dependencies unless 221.Va NOCLEANDEPENDS 222is defined, but the 223.Cm distclean 224portion never recurses 225(this is perhaps a bug). 226.It Cm reinstall 227Use this to restore a port after using 228.Xr pkg-delete 8 229when you should have used 230.Cm deinstall . 231.It Cm deinstall 232Remove an installed port from the system, similar to 233.Xr pkg-delete 8 . 234.It Cm deinstall-all 235Remove all installed ports with the same 236.Va PKGORIGIN 237from the system. 238.It Cm package 239Make a binary package for the port. 240The port will be installed if it has not already been. 241The package is a 242.Pa .tbz 243file that you can use to 244install the port on other machines with 245.Xr pkg-add 8 . 246If the directory specified by 247.Va PACKAGES 248does not exist, the package will be put into the current directory. 249See 250.Va PKGREPOSITORY 251and 252.Va PKGFILE . 253.It Cm package-recursive 254Like 255.Cm package , 256but makes a package for each depending port as well. 257.It Cm package-name 258Prints the name with version of the port. 259.It Cm readmes 260Create a port's 261.Pa README.html . 262This can be used from 263.Pa /usr/ports 264to create a browsable web of all ports on your system! 265.It Cm search 266Search the 267.Pa INDEX 268file for the pattern specified by the 269.Va key 270(searches the port name, comment, and dependencies), 271.Va name 272(searches the port name only), 273.Va path 274(searches the port path), 275.Va info 276(searches the port info), 277.Va maint 278(searches the port maintainer), 279.Va cat 280(searches the port category), 281.Va bdeps 282(searches the port build-time dependency), 283.Va rdeps 284(searches the port run-time dependency), 285.Va www 286(searches the port web site) 287.Xr make 1 288variables, and their exclusion counterparts: 289.Va xname , xkey 290etc. 291For example, one would type: 292.Pp 293.Dl "cd /usr/ports && make search name=query" 294.Pp 295to find all ports whose 296name matches 297.Dq Li query . 298Results include the matching ports' path, comment, maintainer, 299build dependencies, and run dependencies. 300.Bd -literal -offset indent 301cd /usr/ports && make search name=pear- \e 302 xbdeps=apache 303.Ed 304.Pp 305To find all ports whose 306names contain 307.Dq Li pear- 308and which do not have apache 309listed in build-time dependencies. 310.Bd -literal -offset indent 311cd /usr/ports && make search name=pear- \e 312 xname='ht(tp|ml)' 313.Ed 314.Pp 315To find all ports whose names contain 316.Dq Li pear- , 317but not 318.Dq Li html 319or 320.Dq Li http . 321.Bd -literal -offset indent 322make search key=apache display=name,path,info keylim=1 323.Ed 324.Pp 325To find ports that contain 326.Dq Li apache 327in either of the name, path, info 328fields, ignore the rest of the record. 329.Pp 330By default the search is not case-sensitive. 331In order to make it case-sensitive you can use the 332.Va icase 333variable: 334.Bd -literal -offset indent 335make search name=p5-R icase=0 336.Ed 337.It Cm quicksearch 338Reduced 339.Cm search 340output. 341Only display name, path and info. 342.It Cm describe 343Generate a one-line description of each port for use in the 344.Pa INDEX 345file. 346.It Cm maintainer 347Display the port maintainer's email address. 348.It Cm index 349Create 350.Pa /usr/ports/INDEX , 351which is used by the 352.Cm pretty-print-* 353and 354.Cm search 355targets. 356Running the 357.Cm index 358target will ensure your 359.Pa INDEX 360file is up to date with your ports tree. 361.It Cm fetchindex 362Fetch the 363.Pa INDEX 364file from the 365.Fx 366cluster. 367.El 368.Sh ENVIRONMENT 369You can change all of these. 370.Bl -tag -width ".Va MASTER_SITES" 371.It Va PORTSDIR 372Location of the ports tree. 373This is 374.Pa /usr/ports 375on 376.Fx 377and 378.Ox , 379and 380.Pa /usr/pkgsrc 381on 382.Nx . 383.It Va WRKDIRPREFIX 384Where to create any temporary files. 385Useful if 386.Va PORTSDIR 387is read-only (perhaps mounted from a CD-ROM). 388.It Va DISTDIR 389Where to find/put distfiles, normally 390.Pa distfiles/ 391in 392.Va PORTSDIR . 393.It Va PACKAGES 394Used only for the 395.Cm package 396target; the base directory for the packages tree, normally 397.Pa packages/ 398in 399.Va PORTSDIR . 400If this directory exists, the package tree will be (partially) constructed. 401This directory does not have to exist; if it does not, packages will be 402placed into the current directory, or you can define one of 403.Bl -tag -width ".Va PKGREPOSITORY" 404.It Va PKGREPOSITORY 405Directory to put the package in. 406.It Va PKGFILE 407The full path to the package. 408.El 409.It Va LOCALBASE 410Where existing things are installed and where to search for files when 411resolving dependencies (usually 412.Pa /usr/local ) . 413.It Va PREFIX 414Where to install this port (usually set to the same as 415.Va LOCALBASE ) . 416.It Va MASTER_SITES 417Primary sites for distribution files if not found locally. 418.It Va PATCH_SITES 419Primary locations for distribution patch files if not found 420locally. 421.It Va MASTER_SITE_FREEBSD 422If set, go to the master 423.Fx 424site for all files. 425.It Va MASTER_SITE_OVERRIDE 426Try going to these sites for all files and patches, first. 427.It Va MASTER_SITE_BACKUP 428Try going to these sites for all files and patches, last. 429.It Va RANDOMIZE_MASTER_SITES 430Try the download locations in a random order. 431.It Va MASTER_SORT 432Sort the download locations according to user supplied pattern. 433Example: 434.Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net 435.It Va MASTER_SITE_INDEX 436Where to get 437.Pa INDEX 438source built on 439.Fx 440cluster (for 441.Cm fetchindex 442target). 443Defaults to 444.Pa https://www.FreeBSD.org/ports/ . 445.It Va FETCHINDEX 446Command to get 447.Pa INDEX 448(for 449.Cm fetchindex 450target). 451Defaults to 452.Dq Li "fetch -am" . 453.It Va NOCLEANDEPENDS 454If defined, do not let 455.Cm clean 456recurse to dependencies. 457.It Va FETCH_CMD 458Command to use to fetch files. 459Normally 460.Xr fetch 1 . 461.It Va FORCE_PKG_REGISTER 462If set, overwrite any existing package registration on the system. 463.It Va MOTIFLIB 464Location of 465.Pa "libXm\&." Ns Brq Pa a , Ns Pa so . 466.It Va INTERACTIVE 467If defined, only operate on a port if it requires interaction. 468.It Va BATCH 469If defined, only operate on a port if it can be installed 100% automatically. 470.It Va DISABLE_VULNERABILITIES 471If defined, disable check for security vulnerabilities using 472.Xr pkg-audit 8 473when installing new ports. 474.It Va NO_IGNORE 475If defined, allow installation of ports marked as 476.Aq Va FORBIDDEN . 477The default behavior of the Ports framework is to abort when the 478installation of a forbidden port is attempted. 479Of course, these ports may not work as expected, but if you really know 480what you are doing and are sure about installing a forbidden port, then 481.Va NO_IGNORE 482lets you do it. 483.It Va NO_CHECKSUM 484If defined, skip verifying the port's checksum. 485.It Va TRYBROKEN 486If defined, attempt to build a port even if it is marked as 487.Aq Va BROKEN . 488.It Va PORT_DBDIR 489Directory where the results of configuring 490.Va OPTIONS 491are stored. 492Defaults to 493.Pa /var/db/ports . 494Each port where 495.Va OPTIONS 496have been configured will have a uniquely named sub-directory, containing a 497single file 498.Pa options . 499.El 500.Sh MAKE VARIABLES 501The following list provides a name and short description for many of the 502variables that are used when building ports. 503More information on these and other related variables may be found in 504.Pa ${PORTSDIR}/Mk/* 505and the 506.Fx 507Porter's Handbook. 508.Bl -tag -width ".Va WITH_GHOSTSCRIPT_VER" 509.It Va WITH_DEBUG 510.Pq Vt bool 511If set, debugging symbols are installed for ports binaries. 512.It Va WITH_DEBUG_PORTS 513A list of origins for which to set 514.Va WITH_DEBUG_PORTS . 515.It Va WITH_SSP_PORTS 516.Pq Vt bool 517If set, enables 518.Fl fstack-protector 519for most ports. 520.It Va WITH_GHOSTSCRIPT_VER 521If set, the version of ghostscript to be used by ports. 522.It Va WITH_CCACHE_BUILD 523.Pq Vt bool 524If set, enables the use of 525.Xr ccache 1 526for building ports. 527.It Va CCACHE_DIR 528Which directory to use for the 529.Xr ccache 1 530data. 531.El 532.Sh FILES 533.Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact 534.It Pa /usr/ports 535The default ports directory. 536.It Pa /usr/ports/Mk/bsd.port.mk 537The big Kahuna. 538.El 539.Sh EXAMPLES 540Build and install Emacs: 541.Bd -literal -offset indent 542cd /usr/ports/editors/emacs 543make install 544.Ed 545.Sh SEE ALSO 546.Xr make 1 , 547.Xr make.conf 5 , 548.Xr pkg 7 , 549.Xr portsnap 8 550.Pp 551Additional developer documentation: 552.Bl -dash -width "" -offset indent 553.It 554.Xr portlint 1 555.It 556.Pa /usr/ports/Mk/bsd.port.mk 557.El 558.Pp 559Additional user documentation: 560.Bl -dash -width "" -offset indent 561.It 562.Xr pkg 8 563.It 564.Lk "https://www.FreeBSD.org/ports" "Searchable index of all ports" 565.El 566.Sh HISTORY 567The Ports Collection 568appeared in 569.Fx 1.0 . 570It has since spread to 571.Nx 572and 573.Ox . 574.Sh AUTHORS 575.An -nosplit 576This manual page was originated by 577.An David O'Brien . 578.Sh BUGS 579Ports documentation is split over four places \(em 580.Pa /usr/ports/Mk/bsd.port.mk , 581.%B "The Porter's Handbook" , 582the 583.Dq "Packages and Ports" 584chapter of 585.%B "The FreeBSD Handbook" , 586and 587this manual page. 588