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 February 4, 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 PACKAGES 441Used only for the 442.Cm package 443target; the base directory for the packages tree, normally 444.Pa packages/ 445in 446.Va PORTSDIR . 447If this directory exists, the package tree will be (partially) constructed. 448This directory does not have to exist; if it does not, packages will be 449placed into the current directory, or you can define one of 450.Bl -tag -width ".Va PKGREPOSITORY" 451.It Va PKGREPOSITORY 452Directory to put the package in. 453.It Va PKGFILE 454The full path to the package. 455.El 456.It Va LOCALBASE 457Where existing things are installed and where to search for files when 458resolving dependencies (usually 459.Pa /usr/local ) . 460.It Va PREFIX 461Where to install this port (usually set to the same as 462.Va LOCALBASE ) . 463.It Va MASTER_SITES 464Primary sites for distribution files if not found locally. 465.It Va PATCH_SITES 466Primary locations for distribution patch files if not found 467locally. 468.It Va MASTER_SITE_FREEBSD 469If set, go to the master 470.Fx 471site for all files. 472.It Va MASTER_SITE_OVERRIDE 473Try going to these sites for all files and patches, first. 474.It Va MASTER_SITE_BACKUP 475Try going to these sites for all files and patches, last. 476.It Va RANDOMIZE_MASTER_SITES 477Try the download locations in a random order. 478.It Va MASTER_SORT 479Sort the download locations according to user supplied pattern. 480Example: 481.Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net 482.It Va MASTER_SITE_INDEX 483Where to get 484.Pa INDEX 485source built on 486.Fx 487cluster (for 488.Cm fetchindex 489target). 490Defaults to 491.Pa https://www.FreeBSD.org/ports/ . 492.It Va FETCHINDEX 493Command to get 494.Pa INDEX 495(for 496.Cm fetchindex 497target). 498Defaults to 499.Dq Li "fetch -am" . 500.It Va NOCLEANDEPENDS 501If defined, do not let 502.Cm clean 503recurse to dependencies. 504.It Va FETCH_CMD 505Command to use to fetch files. 506Normally 507.Xr fetch 1 . 508.It Va FORCE_PKG_REGISTER 509If set, overwrite any existing package registration on the system. 510.It Va MOTIFLIB 511Location of 512.Pa "libXm\&." Ns Brq Pa a , Ns Pa so . 513.It Va INTERACTIVE 514If defined, only operate on a port if it requires interaction. 515.It Va BATCH 516If defined, only operate on a port if it can be installed 100% automatically. 517.It Va DISABLE_VULNERABILITIES 518If defined, disable check for security vulnerabilities using 519.Xr pkg-audit 8 520when installing new ports. 521.It Va NO_IGNORE 522If defined, allow installation of ports marked as 523.Aq Va FORBIDDEN . 524The default behavior of the Ports framework is to abort when the 525installation of a forbidden port is attempted. 526Of course, these ports may not work as expected, but if you really know 527what you are doing and are sure about installing a forbidden port, then 528.Va NO_IGNORE 529lets you do it. 530.It Va NO_CHECKSUM 531If defined, skip verifying the port's checksum. 532.It Va TRYBROKEN 533If defined, attempt to build a port even if it is marked as 534.Aq Va BROKEN . 535.It Va PORT_DBDIR 536Directory where the results of configuring 537.Va OPTIONS 538are stored. 539Defaults to 540.Pa /var/db/ports . 541Each port where 542.Va OPTIONS 543have been configured will have a uniquely named sub-directory, containing a 544single file 545.Pa options . 546.El 547.Sh MAKE VARIABLES 548The following list provides a name and short description for many of the 549variables that are used when building ports. 550More information on these and other related variables may be found in 551.Pa ${PORTSDIR}/Mk/* 552and the 553.Fx 554Porter's Handbook. 555.Bl -tag -width "WITH_CCACHE_BUILD" 556.It Va WITH_DEBUG 557.Pq Vt bool 558If set, debugging symbols are installed for ports binaries. 559.It Va WITH_DEBUG_PORTS 560A list of origins for which to set 561.Va WITH_DEBUG_PORTS . 562.It Va WITH_CCACHE_BUILD 563.Pq Vt bool 564If set, enables the use of 565.Xr ccache 1 566for building ports. 567.It Va CCACHE_DIR 568Which directory to use for the 569.Xr ccache 1 570data. 571.El 572.Sh FILES 573.Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact 574.It Pa /usr/ports 575The default ports directory. 576.It Pa /usr/ports/Mk/bsd.port.mk 577The big Kahuna. 578.El 579.Sh EXAMPLES 580.Bl -tag -width 0n 581.It Sy Example 1\&: No Building and Installing a Port 582.Pp 583The following command builds and installs Emacs. 584.Bd -literal -offset 2n 585.Li # Ic cd /usr/ports/editors/emacs 586.Li # Ic make install 587.Ed 588.It Sy Example 2\&: No Installing Dependencies with Xr pkg 8 589.Pp 590The following example shows how to build and install a port without having to 591build its dependencies. 592Instead, the dependencies are downloaded via 593.Xr pkg 8 . 594.Bd -literal -offset 2n 595.Li # Ic make install-missing-packages 596.Li # Ic make install 597.Ed 598.Pp 599It is especially useful, when the dependencies are costly 600in time and resources to build 601.Pq like Pa lang/rust . 602The drawback is that 603.Xr pkg 8 604offers only packages built with the default set of 605.Va OPTIONS . 606.It Sy Example 3\&: No Building a Non-Default Flavor of a Port 607.Pp 608The following command builds a non-default flavor of a port. 609(In this case 610.Pa devel/py-pip 611is going to be built with Python 3.7 support.) 612.Bd -literal -offset 2n 613.Li # Ic cd /usr/ports/devel/py-pip 614.Li # Ic env FLAVOR=py37 make build 615.Ed 616.El 617.Sh SEE ALSO 618.Xr make 1 , 619.Xr make.conf 5 , 620.Xr development 7 , 621.Xr pkg 7 , 622.Xr portsnap 8 623.Pp 624Additional developer documentation: 625.Bl -dash -width "" -offset indent 626.It 627.Xr portlint 1 628.It 629.Pa /usr/ports/Mk/bsd.port.mk 630.El 631.Pp 632Additional user documentation: 633.Bl -dash -width "" -offset indent 634.It 635.Xr pkg 8 636.It 637.Lk "https://www.FreeBSD.org/ports" "Searchable index of all ports" 638.El 639.Sh HISTORY 640The Ports Collection 641appeared in 642.Fx 1.0 . 643It has since spread to 644.Nx 645and 646.Ox . 647.Sh AUTHORS 648.An -nosplit 649This manual page was originated by 650.An David O'Brien . 651.Sh BUGS 652Ports documentation is split over four places \(em 653.Pa /usr/ports/Mk/bsd.port.mk , 654.%B "The Porter's Handbook" , 655the 656.Dq "Packages and Ports" 657chapter of 658.%B "The FreeBSD Handbook" , 659and 660this manual page. 661