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 18, 2021 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 . 41.Pp 42The ports tree, typically located at 43.Pa /usr/ports , 44consists of subdirectories, one for each category; those in turn contain 45individual ports. 46Each port is a directory with metadata and patches necessary to make 47the original application source code compile and run on 48.Fx . 49Compiling an application is as simple as typing 50.Dq Li "make build" 51in the port directory. 52The 53.Pa Makefile 54automatically fetches the 55application source code, either from a local disk or the network, unpacks it, 56applies the patches, and compiles it. 57It also recursively handles dependencies \(em other pieces of software 58the port depends on in order to build and work. 59Afterwards, 60.Dq Li "make install" 61installs the application. 62.Pp 63The 64.Fx 65Ports Collection is maintained in several branches, which differ mostly 66by versions of software provided: the 67.Em head 68branch contains all the latest changes, while the 69.Em quarterly 70branches only provide critical fixes. 71The 72.Em head 73branch can be installed or updated from the Subversion repository located at: 74.Pp 75.Lk https://svn.FreeBSD.org/ports/head 76.Pp 77The 78.Em quarterly 79branches can be found in Subversion in the 80.Pa branches/ 81subdirectory, eg: 82.Pp 83.Lk https://svn.FreeBSD.org/ports/branches/2019Q1 84.Pp 85It is generally a good idea to use the 86.Nm 87branch that matches the 88.Xr pkg 8 89repository being used. 90By default, for 91.Fx CURRENT 92the 93.Xr pkg 8 94is configured to install packages built from the 95.Em head 96branch, while for 97.Fx STABLE 98or RELEASE versions it is configured to install packages built from 99the latest 100.Em quarterly 101branch. 102Currently configured 103.Xr pkg 8 104repository can be verified by looking at the 105.Em url 106field in 107.Cm pkg -vv 108output. 109.Pp 110For more information about using ports, see the 111.Dq "Packages and Ports" section 112in 113.Sm off 114.%B "The FreeBSD Handbook" 115.No \&: 116.Sm on 117.Pp 118.Lk https://www.FreeBSD.org/doc/en/books/handbook/ports.html 119.Pp 120For information about creating new ports, see 121.Sm off 122.%B "The Porter's Handbook" 123.No \&: 124.Sm on 125.Pp 126.Lk https://www.FreeBSD.org/doc/en/books/porters-handbook/ 127.Sh TARGETS 128Some of the 129.Xr make 1 130targets work recursively through subdirectories. 131This lets you, for example, install all of the 132.Dq Li biology 133ports with one command. 134The targets that do this are 135.Cm build , checksum , clean , configure , 136.Cm depends , extract , fetch , install , 137and 138.Cm package . 139.Pp 140The following targets will be run automatically by each proceeding 141target in order. 142That is, 143.Cm build 144will be run (if necessary) by 145.Cm install , 146and so on all the way to 147.Cm fetch . 148Usually, you will only use the 149.Cm install 150target. 151.Bl -tag -width ".Cm configure" 152.It Cm config 153Configure 154.Va OPTIONS 155for this port using 156.Xr dialog4ports 1 . 157.It Cm fetch 158Fetch all of the files needed to build this port from the sites 159listed in 160.Va MASTER_SITES 161and 162.Va PATCH_SITES . 163See 164.Va FETCH_CMD , MASTER_SITE_OVERRIDE 165and 166.Va MASTER_SITE_BACKUP . 167.It Cm checksum 168Verify that the fetched distfile's checksum matches the one the port was 169tested against. 170If the distfile's checksum does not match, it also fetches the distfiles 171which are missing or failed the checksum calculation. 172Defining 173.Va NO_CHECKSUM 174will skip this step. 175.It Cm depends 176Install 177(or compile if only compilation is necessary) 178any dependencies of the current port. 179When called by the 180.Cm extract 181or 182.Cm fetch 183targets, this is run in piecemeal as 184.Cm fetch-depends , build-depends , 185etc. 186Defining 187.Va NO_DEPENDS 188will skip this step. 189.It Cm extract 190Expand the distfile into a work directory. 191.It Cm patch 192Apply any patches that are necessary for the port. 193.It Cm configure 194Configure the port. 195Some ports will ask you questions during this stage. 196See 197.Va INTERACTIVE 198and 199.Va BATCH . 200.It Cm build 201Build the port. 202This is the same as calling the 203.Cm all 204target. 205.It Cm install 206Install the port and register it with the package system. 207This is all you really need to do. 208.El 209.Pp 210The following targets are not run during the normal install process. 211.Bl -tag -width ".Cm fetch-recursive" 212.It Cm showconfig 213Display 214.Va OPTIONS 215config for this port. 216.It Cm showconfig-recursive 217Display 218.Va OPTIONS 219config for this port and all its dependencies. 220.It Cm rmconfig 221Remove 222.Va OPTIONS 223config for this port. 224.It Cm rmconfig-recursive 225Remove 226.Va OPTIONS 227config for this port and all its dependencies. 228.It Cm config-conditional 229Skip the ports which have already had their 230.Va OPTIONS 231configured. 232.It Cm config-recursive 233Configure 234.Va OPTIONS 235for this port and all its dependencies using 236.Xr dialog4ports 1 . 237.It Cm fetch-list 238Show list of files to be fetched in order to build the port. 239.It Cm fetch-recursive 240Fetch the distfiles of the port and all its dependencies. 241.It Cm fetch-recursive-list 242Show list of files that would be retrieved by 243.Cm fetch-recursive . 244.It Cm run-depends-list , build-depends-list 245Print a list of all the compile and run dependencies, and dependencies 246of those dependencies, by port directory. 247.It Cm all-depends-list 248Print a list of all dependencies for the port. 249.It Cm pretty-print-run-depends-list , pretty-print-build-depends-list 250Print a list of all the compile and run dependencies, and dependencies 251of those dependencies, by port name and version. 252.It Cm missing 253Print a list of missing dependencies to be installed for the port. 254.It Cm clean 255Remove the expanded source code. 256This recurses to dependencies unless 257.Va NOCLEANDEPENDS 258is defined. 259.It Cm distclean 260Remove the port's distfiles and perform the 261.Cm clean 262target. 263The 264.Cm clean 265portion recurses to dependencies unless 266.Va NOCLEANDEPENDS 267is defined, but the 268.Cm distclean 269portion never recurses 270(this is perhaps a bug). 271.It Cm reinstall 272Use this to restore a port after using 273.Xr pkg-delete 8 274when you should have used 275.Cm deinstall . 276.It Cm deinstall 277Remove an installed port from the system, similar to 278.Xr pkg-delete 8 . 279.It Cm deinstall-all 280Remove all installed ports with the same 281.Va PKGORIGIN 282from the system. 283.It Cm package 284Make a binary package for the port. 285The port will be installed if it has not already been. 286The package is a 287.Pa .txz 288file that you can use to 289install the port on other machines with 290.Xr pkg-add 8 . 291If the directory specified by 292.Va PACKAGES 293does not exist, the package will be put in 294.Pa /usr/ports/category/port/work/pkg . 295See 296.Va PKGREPOSITORY 297and 298.Va PKGFILE 299for more information. 300.It Cm package-recursive 301Like 302.Cm package , 303but makes a package for each depending port as well. 304.It Cm package-name 305Prints the name with version of the port. 306.It Cm readmes 307Create a port's 308.Pa README.html . 309This can be used from 310.Pa /usr/ports 311to create a browsable web of all ports on your system! 312.It Cm search 313Search the 314.Pa INDEX 315file for the pattern specified by the 316.Va key 317(searches the port name, comment, and dependencies), 318.Va name 319(searches the port name only), 320.Va path 321(searches the port path), 322.Va info 323(searches the port info), 324.Va maint 325(searches the port maintainer), 326.Va cat 327(searches the port category), 328.Va bdeps 329(searches the port build-time dependency), 330.Va rdeps 331(searches the port run-time dependency), 332.Va www 333(searches the port web site) 334.Xr make 1 335variables, and their exclusion counterparts: 336.Va xname , xkey 337etc. 338For example, one would type: 339.Pp 340.Dl "cd /usr/ports && make search name=query" 341.Pp 342to find all ports whose 343name matches 344.Dq Li query . 345Results include the matching ports' path, comment, maintainer, 346build dependencies, and run dependencies. 347.Bd -literal -offset indent 348cd /usr/ports && make search name=pear- \e 349 xbdeps=apache 350.Ed 351.Pp 352To find all ports whose 353names contain 354.Dq Li pear- 355and which do not have apache 356listed in build-time dependencies. 357.Bd -literal -offset indent 358cd /usr/ports && make search name=pear- \e 359 xname='ht(tp|ml)' 360.Ed 361.Pp 362To find all ports whose names contain 363.Dq Li pear- , 364but not 365.Dq Li html 366or 367.Dq Li http . 368.Bd -literal -offset indent 369make search key=apache display=name,path,info keylim=1 370.Ed 371.Pp 372To find ports that contain 373.Dq Li apache 374in either of the name, path, info 375fields, ignore the rest of the record. 376.Pp 377By default the search is not case-sensitive. 378In order to make it case-sensitive you can use the 379.Va icase 380variable: 381.Bd -literal -offset indent 382make search name=p5-R icase=0 383.Ed 384.It Cm quicksearch 385Reduced 386.Cm search 387output. 388Only display name, path and info. 389.It Cm describe 390Generate a one-line description of each port for use in the 391.Pa INDEX 392file. 393.It Cm maintainer 394Display the port maintainer's email address. 395.It Cm index 396Create 397.Pa /usr/ports/INDEX , 398which is used by the 399.Cm pretty-print-* 400and 401.Cm search 402targets. 403Running the 404.Cm index 405target will ensure your 406.Pa INDEX 407file is up to date with your ports tree. 408.It Cm fetchindex 409Fetch the 410.Pa INDEX 411file from the 412.Fx 413cluster. 414.El 415.Sh ENVIRONMENT 416You can change all of these. 417.Bl -tag -width ".Va MASTER_SITES" 418.It Va PORTSDIR 419Location of the ports tree. 420This is 421.Pa /usr/ports 422by default. 423.It Va WRKDIRPREFIX 424Where to create any temporary files. 425Useful if 426.Va PORTSDIR 427is read-only (perhaps mounted from a CD-ROM). 428.It Va DISTDIR 429Where to find/put distfiles, normally 430.Pa distfiles/ 431in 432.Va PORTSDIR . 433.It Va SU_CMD 434Command used to elevate privilege to configure and install a port. 435The unprivileged user must have write access to 436.Va WRKDIRPREFIX 437and 438.Va DISTDIR . 439The default is 440.Ql /usr/bin/su root -c . 441Many users set it to 442.Ql /usr/local/bin/sudo -E sh -c 443for convenience. 444.It Va PACKAGES 445Used only for the 446.Cm package 447target; the base directory for the packages tree, normally 448.Pa packages/ 449in 450.Va PORTSDIR . 451If this directory exists, the package tree will be (partially) constructed. 452This directory does not have to exist; if it does not, packages will be 453placed into the current directory, or you can define one of 454.Bl -tag -width ".Va PKGREPOSITORY" 455.It Va PKGREPOSITORY 456Directory to put the package in. 457.It Va PKGFILE 458The full path to the package. 459.El 460.It Va LOCALBASE 461Where existing things are installed and where to search for files when 462resolving dependencies (usually 463.Pa /usr/local ) . 464.It Va PREFIX 465Where to install this port (usually set to the same as 466.Va LOCALBASE ) . 467.It Va MASTER_SITES 468Primary sites for distribution files if not found locally. 469.It Va PATCH_SITES 470Primary locations for distribution patch files if not found 471locally. 472.It Va MASTER_SITE_FREEBSD 473If set, go to the master 474.Fx 475site for all files. 476.It Va MASTER_SITE_OVERRIDE 477Try going to these sites for all files and patches, first. 478.It Va MASTER_SITE_BACKUP 479Try going to these sites for all files and patches, last. 480.It Va RANDOMIZE_MASTER_SITES 481Try the download locations in a random order. 482.It Va MASTER_SORT 483Sort the download locations according to user supplied pattern. 484Example: 485.Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net 486.It Va MASTER_SITE_INDEX 487Where to get 488.Pa INDEX 489source built on 490.Fx 491cluster (for 492.Cm fetchindex 493target). 494Defaults to 495.Pa https://www.FreeBSD.org/ports/ . 496.It Va FETCHINDEX 497Command to get 498.Pa INDEX 499(for 500.Cm fetchindex 501target). 502Defaults to 503.Dq Li "fetch -am" . 504.It Va NOCLEANDEPENDS 505If defined, do not let 506.Cm clean 507recurse to dependencies. 508.It Va FETCH_CMD 509Command to use to fetch files. 510Normally 511.Xr fetch 1 . 512.It Va FORCE_PKG_REGISTER 513If set, overwrite any existing package registration on the system. 514.It Va INTERACTIVE 515If defined, only operate on a port if it requires interaction. 516.It Va BATCH 517If defined, only operate on a port if it can be installed 100% automatically. 518.It Va DISABLE_VULNERABILITIES 519If defined, disable check for security vulnerabilities using 520.Xr pkg-audit 8 521when installing new ports. 522.It Va NO_IGNORE 523If defined, allow installation of ports marked as 524.Aq Va FORBIDDEN . 525The default behavior of the Ports framework is to abort when the 526installation of a forbidden port is attempted. 527Of course, these ports may not work as expected, but if you really know 528what you are doing and are sure about installing a forbidden port, then 529.Va NO_IGNORE 530lets you do it. 531.It Va NO_CHECKSUM 532If defined, skip verifying the port's checksum. 533.It Va TRYBROKEN 534If defined, attempt to build a port even if it is marked as 535.Aq Va BROKEN . 536.It Va PORT_DBDIR 537Directory where the results of configuring 538.Va OPTIONS 539are stored. 540Defaults to 541.Pa /var/db/ports . 542Each port where 543.Va OPTIONS 544have been configured will have a uniquely named sub-directory, containing a 545single file 546.Pa options . 547.El 548.Sh MAKE VARIABLES 549The following list provides a name and short description for many of the 550variables that are used when building ports. 551More information on these and other related variables may be found in 552.Pa ${PORTSDIR}/Mk/* 553and the 554.Fx 555Porter's Handbook. 556.Bl -tag -width "WITH_CCACHE_BUILD" 557.It Va WITH_DEBUG 558.Pq Vt bool 559If set, debugging symbols are installed for ports binaries. 560.It Va WITH_DEBUG_PORTS 561A list of origins for which to set 562.Va WITH_DEBUG . 563.It Va WITH_CCACHE_BUILD 564.Pq Vt bool 565If set, enables the use of 566.Xr ccache 1 567for building ports. 568.It Va CCACHE_DIR 569Which directory to use for the 570.Xr ccache 1 571data. 572.El 573.Sh FILES 574.Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact 575.It Pa /usr/ports 576The default ports directory. 577.It Pa /usr/ports/Mk/bsd.port.mk 578The big Kahuna. 579.El 580.Sh EXAMPLES 581.Bl -tag -width 0n 582.It Sy Example 1\&: No Building and Installing a Port 583.Pp 584The following command builds and installs Emacs. 585.Bd -literal -offset 2n 586.Li # Ic cd /usr/ports/editors/emacs 587.Li # Ic make install 588.Ed 589.It Sy Example 2\&: No Installing Dependencies with Xr pkg 8 590.Pp 591The following example shows how to build and install a port without having to 592build its dependencies. 593Instead, the dependencies are downloaded via 594.Xr pkg 8 . 595.Bd -literal -offset 2n 596.Li # Ic make install-missing-packages 597.Li # Ic make install 598.Ed 599.Pp 600It is especially useful, when the dependencies are costly 601in time and resources to build 602.Pq like Pa lang/rust . 603The drawback is that 604.Xr pkg 8 605offers only packages built with the default set of 606.Va OPTIONS . 607.It Sy Example 3\&: No Building a Non-Default Flavor of a Port 608.Pp 609The following command builds a non-default flavor of a port. 610(In this case 611.Pa devel/py-pip 612is going to be built with Python 3.7 support.) 613.Bd -literal -offset 2n 614.Li # Ic cd /usr/ports/devel/py-pip 615.Li # Ic env FLAVOR=py37 make build 616.Ed 617.It Sy Example 4\&: No Setting Ports Options via Xr make.conf 5 618.Pp 619The following lines present various ways of configuring ports options via 620.Xr make.conf 5 621(as an alternative to, e.g., running 622.Dq Li make config ) : 623.Bd -literal -offset 2n 624# Enable NLS for all ports unless configured otherwise 625# using the options dialog. 626OPTIONS_SET= NLS 627# Disable DOCS for all ports overriding the options set 628# via the options dialog. 629OPTIONS_UNSET_FORCE= DOCS 630# Disable DOCS and EXAMPLES for the shells/zsh port. 631shells_zsh_UNSET= DOCS EXAMPLES 632.Ed 633.Pp 634These and other options-related variables are documented in 635.Pa /usr/ports/Mk/bsd.options.mk . 636.El 637.Sh SEE ALSO 638.Xr make 1 , 639.Xr make.conf 5 , 640.Xr development 7 , 641.Xr pkg 7 642.Pp 643Additional developer documentation: 644.Bl -dash -width "" -offset indent 645.It 646.Xr portlint 1 647.It 648.Pa /usr/ports/Mk/bsd.port.mk 649.El 650.Pp 651Additional user documentation: 652.Bl -dash -width "" -offset indent 653.It 654.Xr pkg 8 655.It 656.Lk "https://www.FreeBSD.org/ports" "Searchable index of all ports" 657.El 658.Sh HISTORY 659The Ports Collection 660appeared in 661.Fx 1.0 . 662It has since spread to 663.Nx 664and 665.Ox . 666.Sh AUTHORS 667.An -nosplit 668This manual page was originated by 669.An David O'Brien . 670.Sh BUGS 671Ports documentation is split over four places \(em 672.Pa /usr/ports/Mk/bsd.port.mk , 673.%B "The Porter's Handbook" , 674the 675.Dq "Packages and Ports" 676chapter of 677.%B "The FreeBSD Handbook" , 678and 679this manual page. 680