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