1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 1997 David E. O'Brien 5.\" 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.Dd March 21, 2025 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://docs.FreeBSD.org/en/books/handbook/ports/ 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://docs.FreeBSD.org/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 portconfig 1 Pq Pa ports/ports-mgmt/portconfig . 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 portconfig 1 Pq Pa ports/ports-mgmt/portconfig . 237.It Cm fetch-list 238Show the list of files to fetch in order to build the port (but not its 239dependencies). 240.It Cm fetch-recursive 241Fetch the distfiles of the port and all its dependencies. 242.It Cm fetch-recursive-list 243Show list of files that would be retrieved by 244.Cm fetch-recursive . 245.It Cm build-depends-list , run-depends-list 246Print a list of all the direct compile or run dependencies for this port. 247.It Cm all-depends-list 248Print a list of all recursive dependencies for this port. 249.It Cm pretty-print-build-depends-list , pretty-print-run-depends-list 250Print a list of all the recursive compile or run dependencies for this port by 251port 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 .pkg 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://download.FreeBSD.org/ports/index/ . 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 DEBUG_FLAGS 562.Pq Default: Ql -g 563Additional 564.Va CFLAGS 565to set when 566.Va WITH_DEBUG 567is set. 568.It Va WITH_CCACHE_BUILD 569.Pq Vt bool 570If set, enables the use of 571.Xr ccache 1 572for building ports. 573.It Va CCACHE_DIR 574Which directory to use for the 575.Xr ccache 1 576data. 577.El 578.Sh FILES 579.Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact 580.It Pa /usr/ports 581The default ports directory. 582.It Pa /usr/ports/Mk/bsd.port.mk 583The big Kahuna. 584.El 585.Sh EXAMPLES 586.Bl -tag -width 0n 587.It Sy Example 1\&: No Building and Installing a Port 588.Pp 589The following command builds and installs Emacs. 590.Bd -literal -offset 2n 591.Li # Ic cd /usr/ports/editors/emacs 592.Li # Ic make install 593.Ed 594.It Sy Example 2\&: No Installing Dependencies with Xr pkg 8 595.Pp 596The following example shows how to build and install a port without having to 597build its dependencies. 598Instead, the dependencies are downloaded via 599.Xr pkg 8 . 600.Bd -literal -offset 2n 601.Li # Ic make install-missing-packages 602.Li # Ic make install 603.Ed 604.Pp 605It is especially useful, when the dependencies are costly 606in time and resources to build 607.Pq like Pa lang/rust . 608The drawback is that 609.Xr pkg 8 610offers only packages built with the default set of 611.Va OPTIONS . 612.It Sy Example 3\&: No Building a Non-Default Flavor of a Port 613.Pp 614The following command builds a non-default flavor of a port. 615(In this case 616.Pa devel/py-pip 617is going to be built with Python 3.7 support.) 618.Bd -literal -offset 2n 619.Li # Ic cd /usr/ports/devel/py-pip 620.Li # Ic env FLAVOR=py37 make build 621.Ed 622.It Sy Example 4\&: No Setting Ports Options via Xr make.conf 5 623.Pp 624The following lines present various ways of configuring ports options via 625.Xr make.conf 5 626(as an alternative to, e.g., running 627.Dq Li make config ) : 628.Bd -literal -offset 2n 629# Enable NLS for all ports unless configured otherwise 630# using the options dialog. 631OPTIONS_SET= NLS 632# Disable DOCS for all ports overriding the options set 633# via the options dialog. 634OPTIONS_UNSET_FORCE= DOCS 635# Disable DOCS and EXAMPLES for the shells/zsh port. 636shells_zsh_UNSET= DOCS EXAMPLES 637.Ed 638.Pp 639These and other options-related variables are documented in 640.Pa /usr/ports/Mk/bsd.options.mk . 641.It Sy Example 5\&: No Setting Xr make 1 Variables for Specific Ports via Xr make.conf 5 642.Pp 643The following example shows how to set arbitrary 644.Xr make 1 645variables only specific ports: 646.Bd -literal -offset 2n 647# Set DISABLE_MAKE_JOBS for the lang/rust port: 648\&.if ${.CURDIR:M*/lang/rust} 649DISABLE_MAKE_JOBS= yes 650TRYBROKEN= yes 651\&.endif 652.Ed 653.It Sy Example 6\&: No Debugging Ports 654By default ports are built and packaged without debugging support (e.g., 655debugging symbols are stripped from binaries, optimization flags are used for 656compiling, verbose logging is disabled). 657Whether ports are built with debugging symbols can be controlled by the 658settings in 659.Xr make.conf 5 , 660e.g., 661.Bd -literal -offset 2n 662# Enable debugging for all ports. 663WITH_DEBUG= yes 664# Enable debugging for selected ports. 665WITH_DEBUG_PORTS= mail/dovecot security/krb5 666.Ed 667.Pp 668It is also possible to use the debug variables on the command line: 669.Bd -literal -offset 2n 670.Li # Ic make -DWITH_DEBUG DEBUG_FLAGS="-g -O0" build 671.Ed 672.Pp 673See the 674.Sx MAKE VARIABLES 675section to learn more about the debug variables. 676.Pp 677To understand the details of what happens when the debug variables are set it 678is best to consult the files located at 679.Pa ${PORTSDIR}/Mk/* 680.Po Pa bsd.port.mk 681in particular 682.Pc . 683.Pp 684If debugging is enabled for a specific port, the ports framework will: 685.Bl -bullet 686.It 687Add 688.Va DEBUG_FLAGS 689(defaults to 690.Ql -g ) 691to 692.Va CFLAGS . 693.It 694Try to prevent the binaries from being stripped (including checking the install 695target to replace 696.Ql install-strip 697with 698.Ql install ) . 699Whether a binary has been stripped can be checked with 700.Xr file 1 . 701.It 702Try to enable other debugging features like debug build type or verbose logging. 703However, this is port-specific and the ports framework might not be aware of 704each supported debugging feature a given piece of software has to offer). 705.El 706.Sh SEE ALSO 707.Xr make 1 , 708.Xr make.conf 5 , 709.Xr development 7 , 710.Xr pkg 7 711.Pp 712Additional developer documentation: 713.Bl -dash -width "" -offset indent 714.It 715.Xr portlint 1 716.It 717.Pa /usr/ports/Mk/bsd.port.mk 718.El 719.Pp 720Additional user documentation: 721.Bl -dash -width "" -offset indent 722.It 723.Xr pkg 8 724.It 725.Lk "https://www.FreeBSD.org/ports" "Searchable index of all ports" 726.El 727.Sh HISTORY 728The Ports Collection 729appeared in 730.Fx 1.0 . 731It has since spread to 732.Nx 733and 734.Ox . 735.Sh AUTHORS 736.An -nosplit 737This manual page was originated by 738.An David O'Brien . 739.Sh BUGS 740Ports documentation is split over four places \(em 741.Pa /usr/ports/Mk/bsd.port.mk , 742.%B "The Porter's Handbook" , 743the 744.Dq "Packages and Ports" 745chapter of 746.%B "The FreeBSD Handbook" , 747and 748this manual page. 749