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 10, 2020 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 .tbz 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 into the current directory. 294See 295.Va PKGREPOSITORY 296and 297.Va PKGFILE . 298.It Cm package-recursive 299Like 300.Cm package , 301but makes a package for each depending port as well. 302.It Cm package-name 303Prints the name with version of the port. 304.It Cm readmes 305Create a port's 306.Pa README.html . 307This can be used from 308.Pa /usr/ports 309to create a browsable web of all ports on your system! 310.It Cm search 311Search the 312.Pa INDEX 313file for the pattern specified by the 314.Va key 315(searches the port name, comment, and dependencies), 316.Va name 317(searches the port name only), 318.Va path 319(searches the port path), 320.Va info 321(searches the port info), 322.Va maint 323(searches the port maintainer), 324.Va cat 325(searches the port category), 326.Va bdeps 327(searches the port build-time dependency), 328.Va rdeps 329(searches the port run-time dependency), 330.Va www 331(searches the port web site) 332.Xr make 1 333variables, and their exclusion counterparts: 334.Va xname , xkey 335etc. 336For example, one would type: 337.Pp 338.Dl "cd /usr/ports && make search name=query" 339.Pp 340to find all ports whose 341name matches 342.Dq Li query . 343Results include the matching ports' path, comment, maintainer, 344build dependencies, and run dependencies. 345.Bd -literal -offset indent 346cd /usr/ports && make search name=pear- \e 347 xbdeps=apache 348.Ed 349.Pp 350To find all ports whose 351names contain 352.Dq Li pear- 353and which do not have apache 354listed in build-time dependencies. 355.Bd -literal -offset indent 356cd /usr/ports && make search name=pear- \e 357 xname='ht(tp|ml)' 358.Ed 359.Pp 360To find all ports whose names contain 361.Dq Li pear- , 362but not 363.Dq Li html 364or 365.Dq Li http . 366.Bd -literal -offset indent 367make search key=apache display=name,path,info keylim=1 368.Ed 369.Pp 370To find ports that contain 371.Dq Li apache 372in either of the name, path, info 373fields, ignore the rest of the record. 374.Pp 375By default the search is not case-sensitive. 376In order to make it case-sensitive you can use the 377.Va icase 378variable: 379.Bd -literal -offset indent 380make search name=p5-R icase=0 381.Ed 382.It Cm quicksearch 383Reduced 384.Cm search 385output. 386Only display name, path and info. 387.It Cm describe 388Generate a one-line description of each port for use in the 389.Pa INDEX 390file. 391.It Cm maintainer 392Display the port maintainer's email address. 393.It Cm index 394Create 395.Pa /usr/ports/INDEX , 396which is used by the 397.Cm pretty-print-* 398and 399.Cm search 400targets. 401Running the 402.Cm index 403target will ensure your 404.Pa INDEX 405file is up to date with your ports tree. 406.It Cm fetchindex 407Fetch the 408.Pa INDEX 409file from the 410.Fx 411cluster. 412.El 413.Sh ENVIRONMENT 414You can change all of these. 415.Bl -tag -width ".Va MASTER_SITES" 416.It Va PORTSDIR 417Location of the ports tree. 418This is 419.Pa /usr/ports 420by default. 421.It Va WRKDIRPREFIX 422Where to create any temporary files. 423Useful if 424.Va PORTSDIR 425is read-only (perhaps mounted from a CD-ROM). 426.It Va DISTDIR 427Where to find/put distfiles, normally 428.Pa distfiles/ 429in 430.Va PORTSDIR . 431.It Va SU_CMD 432Command used to elevate privilege to configure and install a port. 433The unprivileged user must have write access to 434.Va WRKDIRPREFIX 435and 436.Va DISTDIR . 437The default is 438.Ql /usr/bin/su root -c . 439Many users set it to 440.Ql /usr/local/bin/sudo -E sh -c 441for convenience. 442.It Va PACKAGES 443Used only for the 444.Cm package 445target; the base directory for the packages tree, normally 446.Pa packages/ 447in 448.Va PORTSDIR . 449If this directory exists, the package tree will be (partially) constructed. 450This directory does not have to exist; if it does not, packages will be 451placed into the current directory, or you can define one of 452.Bl -tag -width ".Va PKGREPOSITORY" 453.It Va PKGREPOSITORY 454Directory to put the package in. 455.It Va PKGFILE 456The full path to the package. 457.El 458.It Va LOCALBASE 459Where existing things are installed and where to search for files when 460resolving dependencies (usually 461.Pa /usr/local ) . 462.It Va PREFIX 463Where to install this port (usually set to the same as 464.Va LOCALBASE ) . 465.It Va MASTER_SITES 466Primary sites for distribution files if not found locally. 467.It Va PATCH_SITES 468Primary locations for distribution patch files if not found 469locally. 470.It Va MASTER_SITE_FREEBSD 471If set, go to the master 472.Fx 473site for all files. 474.It Va MASTER_SITE_OVERRIDE 475Try going to these sites for all files and patches, first. 476.It Va MASTER_SITE_BACKUP 477Try going to these sites for all files and patches, last. 478.It Va RANDOMIZE_MASTER_SITES 479Try the download locations in a random order. 480.It Va MASTER_SORT 481Sort the download locations according to user supplied pattern. 482Example: 483.Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net 484.It Va MASTER_SITE_INDEX 485Where to get 486.Pa INDEX 487source built on 488.Fx 489cluster (for 490.Cm fetchindex 491target). 492Defaults to 493.Pa https://www.FreeBSD.org/ports/ . 494.It Va FETCHINDEX 495Command to get 496.Pa INDEX 497(for 498.Cm fetchindex 499target). 500Defaults to 501.Dq Li "fetch -am" . 502.It Va NOCLEANDEPENDS 503If defined, do not let 504.Cm clean 505recurse to dependencies. 506.It Va FETCH_CMD 507Command to use to fetch files. 508Normally 509.Xr fetch 1 . 510.It Va FORCE_PKG_REGISTER 511If set, overwrite any existing package registration on the system. 512.It Va INTERACTIVE 513If defined, only operate on a port if it requires interaction. 514.It Va BATCH 515If defined, only operate on a port if it can be installed 100% automatically. 516.It Va DISABLE_VULNERABILITIES 517If defined, disable check for security vulnerabilities using 518.Xr pkg-audit 8 519when installing new ports. 520.It Va NO_IGNORE 521If defined, allow installation of ports marked as 522.Aq Va FORBIDDEN . 523The default behavior of the Ports framework is to abort when the 524installation of a forbidden port is attempted. 525Of course, these ports may not work as expected, but if you really know 526what you are doing and are sure about installing a forbidden port, then 527.Va NO_IGNORE 528lets you do it. 529.It Va NO_CHECKSUM 530If defined, skip verifying the port's checksum. 531.It Va TRYBROKEN 532If defined, attempt to build a port even if it is marked as 533.Aq Va BROKEN . 534.It Va PORT_DBDIR 535Directory where the results of configuring 536.Va OPTIONS 537are stored. 538Defaults to 539.Pa /var/db/ports . 540Each port where 541.Va OPTIONS 542have been configured will have a uniquely named sub-directory, containing a 543single file 544.Pa options . 545.El 546.Sh MAKE VARIABLES 547The following list provides a name and short description for many of the 548variables that are used when building ports. 549More information on these and other related variables may be found in 550.Pa ${PORTSDIR}/Mk/* 551and the 552.Fx 553Porter's Handbook. 554.Bl -tag -width "WITH_CCACHE_BUILD" 555.It Va WITH_DEBUG 556.Pq Vt bool 557If set, debugging symbols are installed for ports binaries. 558.It Va WITH_DEBUG_PORTS 559A list of origins for which to set 560.Va WITH_DEBUG . 561.It Va WITH_CCACHE_BUILD 562.Pq Vt bool 563If set, enables the use of 564.Xr ccache 1 565for building ports. 566.It Va CCACHE_DIR 567Which directory to use for the 568.Xr ccache 1 569data. 570.El 571.Sh FILES 572.Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact 573.It Pa /usr/ports 574The default ports directory. 575.It Pa /usr/ports/Mk/bsd.port.mk 576The big Kahuna. 577.El 578.Sh EXAMPLES 579.Bl -tag -width 0n 580.It Sy Example 1\&: No Building and Installing a Port 581.Pp 582The following command builds and installs Emacs. 583.Bd -literal -offset 2n 584.Li # Ic cd /usr/ports/editors/emacs 585.Li # Ic make install 586.Ed 587.It Sy Example 2\&: No Installing Dependencies with Xr pkg 8 588.Pp 589The following example shows how to build and install a port without having to 590build its dependencies. 591Instead, the dependencies are downloaded via 592.Xr pkg 8 . 593.Bd -literal -offset 2n 594.Li # Ic make install-missing-packages 595.Li # Ic make install 596.Ed 597.Pp 598It is especially useful, when the dependencies are costly 599in time and resources to build 600.Pq like Pa lang/rust . 601The drawback is that 602.Xr pkg 8 603offers only packages built with the default set of 604.Va OPTIONS . 605.It Sy Example 3\&: No Building a Non-Default Flavor of a Port 606.Pp 607The following command builds a non-default flavor of a port. 608(In this case 609.Pa devel/py-pip 610is going to be built with Python 3.7 support.) 611.Bd -literal -offset 2n 612.Li # Ic cd /usr/ports/devel/py-pip 613.Li # Ic env FLAVOR=py37 make build 614.Ed 615.It Sy Example 4\&: No Setting Ports Options via Xr make.conf 5 616.Pp 617The following lines present various ways of configuring ports options via 618.Xr make.conf 5 619(as an alternative to, e.g., running 620.Dq Li make config ) : 621.Bd -literal -offset 2n 622# Enable NLS for all ports unless configured otherwise 623# using the options dialog. 624OPTIONS_SET= NLS 625# Disable DOCS for all ports overriding the options set 626# via the options dialog. 627OPTIONS_UNSET_FORCE= DOCS 628# Disable DOCS and EXAMPLES for the shells/zsh port. 629shells_zsh_UNSET= DOCS EXAMPLES 630.Ed 631.Pp 632These and other options-related variables are documented in 633.Pa /usr/ports/Mk/bsd.options.mk . 634.El 635.Sh SEE ALSO 636.Xr make 1 , 637.Xr make.conf 5 , 638.Xr development 7 , 639.Xr pkg 7 640.Pp 641Additional developer documentation: 642.Bl -dash -width "" -offset indent 643.It 644.Xr portlint 1 645.It 646.Pa /usr/ports/Mk/bsd.port.mk 647.El 648.Pp 649Additional user documentation: 650.Bl -dash -width "" -offset indent 651.It 652.Xr pkg 8 653.It 654.Lk "https://www.FreeBSD.org/ports" "Searchable index of all ports" 655.El 656.Sh HISTORY 657The Ports Collection 658appeared in 659.Fx 1.0 . 660It has since spread to 661.Nx 662and 663.Ox . 664.Sh AUTHORS 665.An -nosplit 666This manual page was originated by 667.An David O'Brien . 668.Sh BUGS 669Ports documentation is split over four places \(em 670.Pa /usr/ports/Mk/bsd.port.mk , 671.%B "The Porter's Handbook" , 672the 673.Dq "Packages and Ports" 674chapter of 675.%B "The FreeBSD Handbook" , 676and 677this manual page. 678