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