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 June 1, 2023 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://docs.FreeBSD.org/en/books/handbook/ports/ 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://docs.FreeBSD.org/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.It Cm install-missing-packages 221Install missing dependencies from packages instead of building them. 222.El 223.Pp 224The following targets are not run during the normal install process. 225.Bl -tag -width ".Cm fetch-recursive" 226.It Cm showconfig 227Display 228.Va OPTIONS 229config for this port. 230.It Cm showconfig-recursive 231Display 232.Va OPTIONS 233config for this port and all its dependencies. 234.It Cm rmconfig 235Remove 236.Va OPTIONS 237config for this port. 238.It Cm rmconfig-recursive 239Remove 240.Va OPTIONS 241config for this port and all its dependencies. 242.It Cm config-conditional 243Skip the ports which have already had their 244.Va OPTIONS 245configured. 246.It Cm config-recursive 247Configure 248.Va OPTIONS 249for this port and all its dependencies using 250.Xr dialog4ports 1 . 251.It Cm fetch-list 252Show the list of files to fetch in order to build the port (but not its 253dependencies). 254.It Cm fetch-recursive 255Fetch the distfiles of the port and all its dependencies. 256.It Cm fetch-recursive-list 257Show list of files that would be retrieved by 258.Cm fetch-recursive . 259.It Cm build-depends-list , run-depends-list 260Print a list of all the direct compile or run dependencies for this port. 261.It Cm all-depends-list 262Print a list of all recursive dependencies for this port. 263.It Cm pretty-print-build-depends-list , pretty-print-run-depends-list 264Print a list of all the recursive compile or run dependencies for this port by 265port name and version. 266.It Cm missing 267Print a list of missing dependencies to be installed for the port. 268.It Cm clean 269Remove the expanded source code. 270This recurses to dependencies unless 271.Va NOCLEANDEPENDS 272is defined. 273.It Cm distclean 274Remove the port's distfiles and perform the 275.Cm clean 276target. 277The 278.Cm clean 279portion recurses to dependencies unless 280.Va NOCLEANDEPENDS 281is defined, but the 282.Cm distclean 283portion never recurses 284(this is perhaps a bug). 285.It Cm reinstall 286Use this to restore a port after using 287.Xr pkg-delete 8 288when you should have used 289.Cm deinstall . 290.It Cm deinstall 291Remove an installed port from the system, similar to 292.Xr pkg-delete 8 . 293.It Cm deinstall-all 294Remove all installed ports with the same 295.Va PKGORIGIN 296from the system. 297.It Cm package 298Make a binary package for the port. 299The port will be installed if it has not already been. 300The package is a 301.Pa .pkg 302file that you can use to 303install the port on other machines with 304.Xr pkg-add 8 . 305If the directory specified by 306.Va PACKAGES 307does not exist, the package will be put in 308.Pa /usr/ports/category/port/work/pkg . 309See 310.Va PKGREPOSITORY 311and 312.Va PKGFILE 313for more information. 314.It Cm package-recursive 315Like 316.Cm package , 317but makes a package for each depending port as well. 318.It Cm package-name 319Prints the name with version of the port. 320.It Cm readmes 321Create a port's 322.Pa README.html . 323This can be used from 324.Pa /usr/ports 325to create a browsable web of all ports on your system! 326.It Cm search 327Search the 328.Pa INDEX 329file for the pattern specified by the 330.Va key 331(searches the port name, comment, and dependencies), 332.Va name 333(searches the port name only), 334.Va path 335(searches the port path), 336.Va info 337(searches the port info), 338.Va maint 339(searches the port maintainer), 340.Va cat 341(searches the port category), 342.Va bdeps 343(searches the port build-time dependency), 344.Va rdeps 345(searches the port run-time dependency), 346.Va www 347(searches the port web site) 348.Xr make 1 349variables, and their exclusion counterparts: 350.Va xname , xkey 351etc. 352For example, one would type: 353.Pp 354.Dl "cd /usr/ports && make search name=query" 355.Pp 356to find all ports whose 357name matches 358.Dq Li query . 359Results include the matching ports' path, comment, maintainer, 360build dependencies, and run dependencies. 361.Bd -literal -offset indent 362cd /usr/ports && make search name=pear- \e 363 xbdeps=apache 364.Ed 365.Pp 366To find all ports whose 367names contain 368.Dq Li pear- 369and which do not have apache 370listed in build-time dependencies. 371.Bd -literal -offset indent 372cd /usr/ports && make search name=pear- \e 373 xname='ht(tp|ml)' 374.Ed 375.Pp 376To find all ports whose names contain 377.Dq Li pear- , 378but not 379.Dq Li html 380or 381.Dq Li http . 382.Bd -literal -offset indent 383make search key=apache display=name,path,info keylim=1 384.Ed 385.Pp 386To find ports that contain 387.Dq Li apache 388in either of the name, path, info 389fields, ignore the rest of the record. 390.Pp 391By default the search is not case-sensitive. 392In order to make it case-sensitive you can use the 393.Va icase 394variable: 395.Bd -literal -offset indent 396make search name=p5-R icase=0 397.Ed 398.It Cm quicksearch 399Reduced 400.Cm search 401output. 402Only display name, path and info. 403.It Cm describe 404Generate a one-line description of each port for use in the 405.Pa INDEX 406file. 407.It Cm maintainer 408Display the port maintainer's email address. 409.It Cm index 410Create 411.Pa /usr/ports/INDEX , 412which is used by the 413.Cm pretty-print-* 414and 415.Cm search 416targets. 417Running the 418.Cm index 419target will ensure your 420.Pa INDEX 421file is up to date with your ports tree. 422.It Cm fetchindex 423Fetch the 424.Pa INDEX 425file from the 426.Fx 427cluster. 428.El 429.Sh ENVIRONMENT 430You can change all of these. 431.Bl -tag -width ".Va MASTER_SITES" 432.It Va PORTSDIR 433Location of the ports tree. 434This is 435.Pa /usr/ports 436by default. 437.It Va WRKDIRPREFIX 438Where to create any temporary files. 439Useful if 440.Va PORTSDIR 441is read-only (perhaps mounted from a CD-ROM). 442.It Va DISTDIR 443Where to find/put distfiles, normally 444.Pa distfiles/ 445in 446.Va PORTSDIR . 447.It Va SU_CMD 448Command used to elevate privilege to configure and install a port. 449The unprivileged user must have write access to 450.Va WRKDIRPREFIX 451and 452.Va DISTDIR . 453The default is 454.Ql /usr/bin/su root -c . 455Many users set it to 456.Ql /usr/local/bin/sudo -E sh -c 457for convenience. 458.It Va PACKAGES 459Used only for the 460.Cm package 461target; the base directory for the packages tree, normally 462.Pa packages/ 463in 464.Va PORTSDIR . 465If this directory exists, the package tree will be (partially) constructed. 466This directory does not have to exist; if it does not, packages will be 467placed into the current directory, or you can define one of 468.Bl -tag -width ".Va PKGREPOSITORY" 469.It Va PKGREPOSITORY 470Directory to put the package in. 471.It Va PKGFILE 472The full path to the package. 473.El 474.It Va LOCALBASE 475Where existing things are installed and where to search for files when 476resolving dependencies (usually 477.Pa /usr/local ) . 478.It Va PREFIX 479Where to install this port (usually set to the same as 480.Va LOCALBASE ) . 481.It Va MASTER_SITES 482Primary sites for distribution files if not found locally. 483.It Va PATCH_SITES 484Primary locations for distribution patch files if not found 485locally. 486.It Va MASTER_SITE_FREEBSD 487If set, go to the master 488.Fx 489site for all files. 490.It Va MASTER_SITE_OVERRIDE 491Try going to these sites for all files and patches, first. 492.It Va MASTER_SITE_BACKUP 493Try going to these sites for all files and patches, last. 494.It Va RANDOMIZE_MASTER_SITES 495Try the download locations in a random order. 496.It Va MASTER_SORT 497Sort the download locations according to user supplied pattern. 498Example: 499.Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net 500.It Va MASTER_SITE_INDEX 501Where to get 502.Pa INDEX 503source built on 504.Fx 505cluster (for 506.Cm fetchindex 507target). 508Defaults to 509.Pa https://www.FreeBSD.org/ports/ . 510.It Va FETCHINDEX 511Command to get 512.Pa INDEX 513(for 514.Cm fetchindex 515target). 516Defaults to 517.Dq Li "fetch -am" . 518.It Va NOCLEANDEPENDS 519If defined, do not let 520.Cm clean 521recurse to dependencies. 522.It Va FETCH_CMD 523Command to use to fetch files. 524Normally 525.Xr fetch 1 . 526.It Va FORCE_PKG_REGISTER 527If set, overwrite any existing package registration on the system. 528.It Va INTERACTIVE 529If defined, only operate on a port if it requires interaction. 530.It Va BATCH 531If defined, only operate on a port if it can be installed 100% automatically. 532.It Va DISABLE_VULNERABILITIES 533If defined, disable check for security vulnerabilities using 534.Xr pkg-audit 8 535when installing new ports. 536.It Va NO_IGNORE 537If defined, allow installation of ports marked as 538.Aq Va FORBIDDEN . 539The default behavior of the Ports framework is to abort when the 540installation of a forbidden port is attempted. 541Of course, these ports may not work as expected, but if you really know 542what you are doing and are sure about installing a forbidden port, then 543.Va NO_IGNORE 544lets you do it. 545.It Va NO_CHECKSUM 546If defined, skip verifying the port's checksum. 547.It Va TRYBROKEN 548If defined, attempt to build a port even if it is marked as 549.Aq Va BROKEN . 550.It Va PORT_DBDIR 551Directory where the results of configuring 552.Va OPTIONS 553are stored. 554Defaults to 555.Pa /var/db/ports . 556Each port where 557.Va OPTIONS 558have been configured will have a uniquely named sub-directory, containing a 559single file 560.Pa options . 561.El 562.Sh MAKE VARIABLES 563The following list provides a name and short description for many of the 564variables that are used when building ports. 565More information on these and other related variables may be found in 566.Pa ${PORTSDIR}/Mk/* 567and the 568.Fx 569Porter's Handbook. 570.Bl -tag -width "WITH_CCACHE_BUILD" 571.It Va WITH_DEBUG 572.Pq Vt bool 573If set, debugging symbols are installed for ports binaries. 574.It Va WITH_DEBUG_PORTS 575A list of origins for which to set 576.Va WITH_DEBUG . 577.It Va DEBUG_FLAGS 578.Pq Default: Ql -g 579Additional 580.Va CFLAGS 581to set when 582.Va WITH_DEBUG 583is set. 584.It Va WITH_CCACHE_BUILD 585.Pq Vt bool 586If set, enables the use of 587.Xr ccache 1 588for building ports. 589.It Va CCACHE_DIR 590Which directory to use for the 591.Xr ccache 1 592data. 593.El 594.Sh FILES 595.Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact 596.It Pa /usr/ports 597The default ports directory. 598.It Pa /usr/ports/Mk/bsd.port.mk 599The big Kahuna. 600.El 601.Sh EXAMPLES 602.Bl -tag -width 0n 603.It Sy Example 1\&: No Building and Installing a Port 604.Pp 605The following command builds and installs Emacs. 606.Bd -literal -offset 2n 607.Li # Ic cd /usr/ports/editors/emacs 608.Li # Ic make install 609.Ed 610.It Sy Example 2\&: No Installing Dependencies with Xr pkg 8 611.Pp 612The following example shows how to build and install a port without having to 613build its dependencies. 614Instead, the dependencies are downloaded via 615.Xr pkg 8 . 616.Bd -literal -offset 2n 617.Li # Ic make install-missing-packages 618.Li # Ic make install 619.Ed 620.Pp 621It is especially useful, when the dependencies are costly 622in time and resources to build 623.Pq like Pa lang/rust . 624The drawback is that 625.Xr pkg 8 626offers only packages built with the default set of 627.Va OPTIONS . 628.It Sy Example 3\&: No Building a Non-Default Flavor of a Port 629.Pp 630The following command builds a non-default flavor of a port. 631(In this case 632.Pa devel/py-pip 633is going to be built with Python 3.7 support.) 634.Bd -literal -offset 2n 635.Li # Ic cd /usr/ports/devel/py-pip 636.Li # Ic env FLAVOR=py37 make build 637.Ed 638.It Sy Example 4\&: No Setting Ports Options via Xr make.conf 5 639.Pp 640The following lines present various ways of configuring ports options via 641.Xr make.conf 5 642(as an alternative to, e.g., running 643.Dq Li make config ) : 644.Bd -literal -offset 2n 645# Enable NLS for all ports unless configured otherwise 646# using the options dialog. 647OPTIONS_SET= NLS 648# Disable DOCS for all ports overriding the options set 649# via the options dialog. 650OPTIONS_UNSET_FORCE= DOCS 651# Disable DOCS and EXAMPLES for the shells/zsh port. 652shells_zsh_UNSET= DOCS EXAMPLES 653.Ed 654.Pp 655These and other options-related variables are documented in 656.Pa /usr/ports/Mk/bsd.options.mk . 657.It Sy Example 5\&: No Setting Xr make 1 Variables for Specific Ports via Xr make.conf 5 658.Pp 659The following example shows how to set arbitrary 660.Xr make 1 661variables only specific ports: 662.Bd -literal -offset 2n 663# Set DISABLE_MAKE_JOBS for the lang/rust port: 664\&.if ${.CURDIR:M*/lang/rust} 665DISABLE_MAKE_JOBS= yes 666TRYBROKEN= yes 667\&.endif 668.Ed 669.It Sy Example 6\&: No Debugging Ports 670By default ports are built and packaged without debugging support (e.g., 671debugging symbols are stripped from binaries, optimization flags are used for 672compiling, verbose logging is disabled). 673Whether ports are built with debugging symbols can be controlled by the 674settings in 675.Xr make.conf 5 , 676e.g., 677.Bd -literal -offset 2n 678# Enable debugging for all ports. 679WITH_DEBUG= yes 680# Enable debugging for selected ports. 681WITH_DEBUG_PORTS= mail/dovecot security/krb5 682.Ed 683.Pp 684It is also possible to use the debug variables on the command line: 685.Bd -literal -offset 2n 686.Li # Ic make -DWITH_DEBUG DEBUG_FLAGS="-g -O0" build 687.Ed 688.Pp 689See the 690.Sx MAKE VARIABLES 691section to learn more about the debug variables. 692.Pp 693To understand the details of what happens when the debug variables are set it 694is best to consult the files located at 695.Pa ${PORTSDIR}/Mk/* 696.Po Pa bsd.port.mk 697in particular 698.Pc . 699.Pp 700If debugging is enabled for a specific port, the ports framework will: 701.Bl -bullet 702.It 703Add 704.Va DEBUG_FLAGS 705(defaults to 706.Ql -g ) 707to 708.Va CFLAGS . 709.It 710Try to prevent the binaries from being stripped (including checking the install 711target to replace 712.Ql install-strip 713with 714.Ql install ) . 715Whether a binary has been stripped can be checked with 716.Xr file 1 . 717.It 718Try to enable other debugging features like debug build type or verbose logging. 719However, this is port-specific and the ports framework might not be aware of 720each supported debugging feature a given piece of software has to offer). 721.El 722.El 723.Sh SEE ALSO 724.Xr make 1 , 725.Xr make.conf 5 , 726.Xr development 7 , 727.Xr pkg 7 728.Pp 729Additional developer documentation: 730.Bl -dash -width "" -offset indent 731.It 732.Xr portlint 1 733.It 734.Pa /usr/ports/Mk/bsd.port.mk 735.El 736.Pp 737Additional user documentation: 738.Bl -dash -width "" -offset indent 739.It 740.Xr pkg 8 741.It 742.Lk "https://www.FreeBSD.org/ports" "Searchable index of all ports" 743.El 744.Sh HISTORY 745The Ports Collection 746appeared in 747.Fx 1.0 . 748It has since spread to 749.Nx 750and 751.Ox . 752.Sh AUTHORS 753.An -nosplit 754This manual page was originated by 755.An David O'Brien . 756.Sh BUGS 757Ports documentation is split over four places \(em 758.Pa /usr/ports/Mk/bsd.port.mk , 759.%B "The Porter's Handbook" , 760the 761.Dq "Packages and Ports" 762chapter of 763.%B "The FreeBSD Handbook" , 764and 765this manual page. 766