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.Dd September 24, 2023 27.Dt PORTS 7 28.Os 29.Sh NAME 30.Nm ports 31.Nd contributed applications 32.Sh DESCRIPTION 33The 34.Fx 35Ports Collection 36offers a simple way to compile and install third party applications. 37It is also used to build packages, to be installed using 38.Xr pkg 8 . 39.Pp 40The ports tree, typically located at 41.Pa /usr/ports , 42consists of subdirectories, one for each category; those in turn contain 43individual ports. 44Each port is a directory with metadata and patches necessary to make 45the original application source code compile and run on 46.Fx . 47Compiling an application is as simple as typing 48.Dq Li "make build" 49in the port directory. 50The 51.Pa Makefile 52automatically fetches the 53application source code, either from a local disk or the network, unpacks it, 54applies the patches, and compiles it. 55It also recursively handles dependencies \(em other pieces of software 56the port depends on in order to build and work. 57Afterwards, 58.Dq Li "make install" 59installs the application. 60.Pp 61The 62.Fx 63Ports Collection is maintained in several branches, which differ mostly 64by versions of software provided: the 65.Em main 66branch contains all the latest changes and corresponds to the 67.Em latest 68package set, while the 69.Em quarterly 70branches only provide critical fixes. 71The 72.Em main 73branch can be cloned and updated from the Git repository located at: 74.Pp 75.Lk https://git.FreeBSD.org/ports.git 76.Pp 77so eg: 78.Pp 79.Cm git clone https://git.FreeBSD.org/ports.git 80.Pp 81The 82.Em quarterly 83branches can be found in Git as branches like 84.Pa yyyyQn 85, where 86.Em yyyy 87indicates the year and 88.Em n 89indicates the quarter 90.Po 1 to 4 91.Pc , eg: 92.Pp 93.Cm git clone -b 2021Q2 https://git.FreeBSD.org/ports.git 94.Pp 95It is generally a good idea to use the 96.Nm 97branch that matches the 98.Xr pkg 8 99repository being used. 100By default, for 101.Fx CURRENT 102the 103.Xr pkg 8 104is configured to install packages built from the 105.Em main 106branch, while for 107.Fx STABLE 108or RELEASE versions it is configured to install packages built from 109the latest 110.Em quarterly 111branch. 112Currently configured 113.Xr pkg 8 114repository can be verified by looking at the 115.Em url 116field in 117.Cm pkg -vv 118output. 119.Pp 120For more information about using ports, see the 121.Dq "Packages and Ports" section 122in 123.Sm off 124.%B "The FreeBSD Handbook" 125.No \&: 126.Sm on 127.Pp 128.Lk https://docs.FreeBSD.org/en/books/handbook/ports/ 129.Pp 130For information about creating new ports, see 131.Sm off 132.%B "The Porter's Handbook" 133.No \&: 134.Sm on 135.Pp 136.Lk https://docs.FreeBSD.org/en/books/porters-handbook/ 137.Sh TARGETS 138Some of the 139.Xr make 1 140targets work recursively through subdirectories. 141This lets you, for example, install all of the 142.Dq Li biology 143ports with one command. 144The targets that do this are 145.Cm build , checksum , clean , configure , 146.Cm depends , extract , fetch , install , 147and 148.Cm package . 149.Pp 150The following targets will be run automatically by each proceeding 151target in order. 152That is, 153.Cm build 154will be run (if necessary) by 155.Cm install , 156and so on all the way to 157.Cm fetch . 158Usually, you will only use the 159.Cm install 160target. 161.Bl -tag -width ".Cm configure" 162.It Cm config 163Configure 164.Va OPTIONS 165for this port using 166.Xr dialog4ports 1 . 167.It Cm fetch 168Fetch all of the files needed to build this port from the sites 169listed in 170.Va MASTER_SITES 171and 172.Va PATCH_SITES . 173See 174.Va FETCH_CMD , MASTER_SITE_OVERRIDE 175and 176.Va MASTER_SITE_BACKUP . 177.It Cm checksum 178Verify that the fetched distfile's checksum matches the one the port was 179tested against. 180If the distfile's checksum does not match, it also fetches the distfiles 181which are missing or failed the checksum calculation. 182Defining 183.Va NO_CHECKSUM 184will skip this step. 185.It Cm depends 186Install 187(or compile if only compilation is necessary) 188any dependencies of the current port. 189When called by the 190.Cm extract 191or 192.Cm fetch 193targets, this is run in piecemeal as 194.Cm fetch-depends , build-depends , 195etc. 196Defining 197.Va NO_DEPENDS 198will skip this step. 199.It Cm extract 200Expand the distfile into a work directory. 201.It Cm patch 202Apply any patches that are necessary for the port. 203.It Cm configure 204Configure the port. 205Some ports will ask you questions during this stage. 206See 207.Va INTERACTIVE 208and 209.Va BATCH . 210.It Cm build 211Build the port. 212This is the same as calling the 213.Cm all 214target. 215.It Cm install 216Install the port and register it with the package system. 217This is all you really need to do. 218.It Cm install-missing-packages 219Install missing dependencies from packages instead of building them. 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 the list of files to fetch in order to build the port (but not its 251dependencies). 252.It Cm fetch-recursive 253Fetch the distfiles of the port and all its dependencies. 254.It Cm fetch-recursive-list 255Show list of files that would be retrieved by 256.Cm fetch-recursive . 257.It Cm build-depends-list , run-depends-list 258Print a list of all the direct compile or run dependencies for this port. 259.It Cm all-depends-list 260Print a list of all recursive dependencies for this port. 261.It Cm pretty-print-build-depends-list , pretty-print-run-depends-list 262Print a list of all the recursive compile or run dependencies for this port by 263port 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 .pkg 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://download.FreeBSD.org/ports/index/ . 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 DEBUG_FLAGS 576.Pq Default: Ql -g 577Additional 578.Va CFLAGS 579to set when 580.Va WITH_DEBUG 581is set. 582.It Va WITH_CCACHE_BUILD 583.Pq Vt bool 584If set, enables the use of 585.Xr ccache 1 586for building ports. 587.It Va CCACHE_DIR 588Which directory to use for the 589.Xr ccache 1 590data. 591.El 592.Sh FILES 593.Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact 594.It Pa /usr/ports 595The default ports directory. 596.It Pa /usr/ports/Mk/bsd.port.mk 597The big Kahuna. 598.El 599.Sh EXAMPLES 600.Bl -tag -width 0n 601.It Sy Example 1\&: No Building and Installing a Port 602.Pp 603The following command builds and installs Emacs. 604.Bd -literal -offset 2n 605.Li # Ic cd /usr/ports/editors/emacs 606.Li # Ic make install 607.Ed 608.It Sy Example 2\&: No Installing Dependencies with Xr pkg 8 609.Pp 610The following example shows how to build and install a port without having to 611build its dependencies. 612Instead, the dependencies are downloaded via 613.Xr pkg 8 . 614.Bd -literal -offset 2n 615.Li # Ic make install-missing-packages 616.Li # Ic make install 617.Ed 618.Pp 619It is especially useful, when the dependencies are costly 620in time and resources to build 621.Pq like Pa lang/rust . 622The drawback is that 623.Xr pkg 8 624offers only packages built with the default set of 625.Va OPTIONS . 626.It Sy Example 3\&: No Building a Non-Default Flavor of a Port 627.Pp 628The following command builds a non-default flavor of a port. 629(In this case 630.Pa devel/py-pip 631is going to be built with Python 3.7 support.) 632.Bd -literal -offset 2n 633.Li # Ic cd /usr/ports/devel/py-pip 634.Li # Ic env FLAVOR=py37 make build 635.Ed 636.It Sy Example 4\&: No Setting Ports Options via Xr make.conf 5 637.Pp 638The following lines present various ways of configuring ports options via 639.Xr make.conf 5 640(as an alternative to, e.g., running 641.Dq Li make config ) : 642.Bd -literal -offset 2n 643# Enable NLS for all ports unless configured otherwise 644# using the options dialog. 645OPTIONS_SET= NLS 646# Disable DOCS for all ports overriding the options set 647# via the options dialog. 648OPTIONS_UNSET_FORCE= DOCS 649# Disable DOCS and EXAMPLES for the shells/zsh port. 650shells_zsh_UNSET= DOCS EXAMPLES 651.Ed 652.Pp 653These and other options-related variables are documented in 654.Pa /usr/ports/Mk/bsd.options.mk . 655.It Sy Example 5\&: No Setting Xr make 1 Variables for Specific Ports via Xr make.conf 5 656.Pp 657The following example shows how to set arbitrary 658.Xr make 1 659variables only specific ports: 660.Bd -literal -offset 2n 661# Set DISABLE_MAKE_JOBS for the lang/rust port: 662\&.if ${.CURDIR:M*/lang/rust} 663DISABLE_MAKE_JOBS= yes 664TRYBROKEN= yes 665\&.endif 666.Ed 667.It Sy Example 6\&: No Debugging Ports 668By default ports are built and packaged without debugging support (e.g., 669debugging symbols are stripped from binaries, optimization flags are used for 670compiling, verbose logging is disabled). 671Whether ports are built with debugging symbols can be controlled by the 672settings in 673.Xr make.conf 5 , 674e.g., 675.Bd -literal -offset 2n 676# Enable debugging for all ports. 677WITH_DEBUG= yes 678# Enable debugging for selected ports. 679WITH_DEBUG_PORTS= mail/dovecot security/krb5 680.Ed 681.Pp 682It is also possible to use the debug variables on the command line: 683.Bd -literal -offset 2n 684.Li # Ic make -DWITH_DEBUG DEBUG_FLAGS="-g -O0" build 685.Ed 686.Pp 687See the 688.Sx MAKE VARIABLES 689section to learn more about the debug variables. 690.Pp 691To understand the details of what happens when the debug variables are set it 692is best to consult the files located at 693.Pa ${PORTSDIR}/Mk/* 694.Po Pa bsd.port.mk 695in particular 696.Pc . 697.Pp 698If debugging is enabled for a specific port, the ports framework will: 699.Bl -bullet 700.It 701Add 702.Va DEBUG_FLAGS 703(defaults to 704.Ql -g ) 705to 706.Va CFLAGS . 707.It 708Try to prevent the binaries from being stripped (including checking the install 709target to replace 710.Ql install-strip 711with 712.Ql install ) . 713Whether a binary has been stripped can be checked with 714.Xr file 1 . 715.It 716Try to enable other debugging features like debug build type or verbose logging. 717However, this is port-specific and the ports framework might not be aware of 718each supported debugging feature a given piece of software has to offer). 719.El 720.El 721.Sh SEE ALSO 722.Xr make 1 , 723.Xr make.conf 5 , 724.Xr development 7 , 725.Xr pkg 7 726.Pp 727Additional developer documentation: 728.Bl -dash -width "" -offset indent 729.It 730.Xr portlint 1 731.It 732.Pa /usr/ports/Mk/bsd.port.mk 733.El 734.Pp 735Additional user documentation: 736.Bl -dash -width "" -offset indent 737.It 738.Xr pkg 8 739.It 740.Lk "https://www.FreeBSD.org/ports" "Searchable index of all ports" 741.El 742.Sh HISTORY 743The Ports Collection 744appeared in 745.Fx 1.0 . 746It has since spread to 747.Nx 748and 749.Ox . 750.Sh AUTHORS 751.An -nosplit 752This manual page was originated by 753.An David O'Brien . 754.Sh BUGS 755Ports documentation is split over four places \(em 756.Pa /usr/ports/Mk/bsd.port.mk , 757.%B "The Porter's Handbook" , 758the 759.Dq "Packages and Ports" 760chapter of 761.%B "The FreeBSD Handbook" , 762and 763this manual page. 764