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 August 3, 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 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://www.FreeBSD.org/doc/en/books/handbook/ports.html 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://www.FreeBSD.org/doc/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 dialog4ports 1 . 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 dialog4ports 1 . 237.It Cm fetch-list 238Show list of files to be fetched in order to build the port. 239.It Cm fetch-recursive 240Fetch the distfiles of the port and all its dependencies. 241.It Cm fetch-recursive-list 242Show list of files that would be retrieved by 243.Cm fetch-recursive . 244.It Cm run-depends-list , build-depends-list 245Print a list of all the compile and run dependencies, and dependencies 246of those dependencies, by port directory. 247.It Cm all-depends-list 248Print a list of all dependencies for the port. 249.It Cm pretty-print-run-depends-list , pretty-print-build-depends-list 250Print a list of all the compile and run dependencies, and dependencies 251of those dependencies, by port 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 .tbz 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 420on 421.Fx 422and 423.Ox , 424and 425.Pa /usr/pkgsrc 426on 427.Nx . 428.It Va WRKDIRPREFIX 429Where to create any temporary files. 430Useful if 431.Va PORTSDIR 432is read-only (perhaps mounted from a CD-ROM). 433.It Va DISTDIR 434Where to find/put distfiles, normally 435.Pa distfiles/ 436in 437.Va PORTSDIR . 438.It Va SU_CMD 439Command used to elevate privilege to configure and install a port. 440The unprivileged user must have write access to 441.Va WRKDIRPREFIX 442and 443.Va DISTDIR . 444The default is 445.Ql /usr/bin/su root -c 446.It Va PACKAGES 447Used only for the 448.Cm package 449target; the base directory for the packages tree, normally 450.Pa packages/ 451in 452.Va PORTSDIR . 453If this directory exists, the package tree will be (partially) constructed. 454This directory does not have to exist; if it does not, packages will be 455placed into the current directory, or you can define one of 456.Bl -tag -width ".Va PKGREPOSITORY" 457.It Va PKGREPOSITORY 458Directory to put the package in. 459.It Va PKGFILE 460The full path to the package. 461.El 462.It Va LOCALBASE 463Where existing things are installed and where to search for files when 464resolving dependencies (usually 465.Pa /usr/local ) . 466.It Va PREFIX 467Where to install this port (usually set to the same as 468.Va LOCALBASE ) . 469.It Va MASTER_SITES 470Primary sites for distribution files if not found locally. 471.It Va PATCH_SITES 472Primary locations for distribution patch files if not found 473locally. 474.It Va MASTER_SITE_FREEBSD 475If set, go to the master 476.Fx 477site for all files. 478.It Va MASTER_SITE_OVERRIDE 479Try going to these sites for all files and patches, first. 480.It Va MASTER_SITE_BACKUP 481Try going to these sites for all files and patches, last. 482.It Va RANDOMIZE_MASTER_SITES 483Try the download locations in a random order. 484.It Va MASTER_SORT 485Sort the download locations according to user supplied pattern. 486Example: 487.Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net 488.It Va MASTER_SITE_INDEX 489Where to get 490.Pa INDEX 491source built on 492.Fx 493cluster (for 494.Cm fetchindex 495target). 496Defaults to 497.Pa https://www.FreeBSD.org/ports/ . 498.It Va FETCHINDEX 499Command to get 500.Pa INDEX 501(for 502.Cm fetchindex 503target). 504Defaults to 505.Dq Li "fetch -am" . 506.It Va NOCLEANDEPENDS 507If defined, do not let 508.Cm clean 509recurse to dependencies. 510.It Va FETCH_CMD 511Command to use to fetch files. 512Normally 513.Xr fetch 1 . 514.It Va FORCE_PKG_REGISTER 515If set, overwrite any existing package registration on the system. 516.It Va MOTIFLIB 517Location of 518.Pa "libXm\&." Ns Brq Pa a , Ns Pa so . 519.It Va INTERACTIVE 520If defined, only operate on a port if it requires interaction. 521.It Va BATCH 522If defined, only operate on a port if it can be installed 100% automatically. 523.It Va DISABLE_VULNERABILITIES 524If defined, disable check for security vulnerabilities using 525.Xr pkg-audit 8 526when installing new ports. 527.It Va NO_IGNORE 528If defined, allow installation of ports marked as 529.Aq Va FORBIDDEN . 530The default behavior of the Ports framework is to abort when the 531installation of a forbidden port is attempted. 532Of course, these ports may not work as expected, but if you really know 533what you are doing and are sure about installing a forbidden port, then 534.Va NO_IGNORE 535lets you do it. 536.It Va NO_CHECKSUM 537If defined, skip verifying the port's checksum. 538.It Va TRYBROKEN 539If defined, attempt to build a port even if it is marked as 540.Aq Va BROKEN . 541.It Va PORT_DBDIR 542Directory where the results of configuring 543.Va OPTIONS 544are stored. 545Defaults to 546.Pa /var/db/ports . 547Each port where 548.Va OPTIONS 549have been configured will have a uniquely named sub-directory, containing a 550single file 551.Pa options . 552.El 553.Sh MAKE VARIABLES 554The following list provides a name and short description for many of the 555variables that are used when building ports. 556More information on these and other related variables may be found in 557.Pa ${PORTSDIR}/Mk/* 558and the 559.Fx 560Porter's Handbook. 561.Bl -tag -width "WITH_CCACHE_BUILD" 562.It Va WITH_DEBUG 563.Pq Vt bool 564If set, debugging symbols are installed for ports binaries. 565.It Va WITH_DEBUG_PORTS 566A list of origins for which to set 567.Va WITH_DEBUG_PORTS . 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.El 623.Sh SEE ALSO 624.Xr make 1 , 625.Xr make.conf 5 , 626.Xr development 7 , 627.Xr pkg 7 628.Pp 629Additional developer documentation: 630.Bl -dash -width "" -offset indent 631.It 632.Xr portlint 1 633.It 634.Pa /usr/ports/Mk/bsd.port.mk 635.El 636.Pp 637Additional user documentation: 638.Bl -dash -width "" -offset indent 639.It 640.Xr pkg 8 641.It 642.Lk "https://www.FreeBSD.org/ports" "Searchable index of all ports" 643.El 644.Sh HISTORY 645The Ports Collection 646appeared in 647.Fx 1.0 . 648It has since spread to 649.Nx 650and 651.Ox . 652.Sh AUTHORS 653.An -nosplit 654This manual page was originated by 655.An David O'Brien . 656.Sh BUGS 657Ports documentation is split over four places \(em 658.Pa /usr/ports/Mk/bsd.port.mk , 659.%B "The Porter's Handbook" , 660the 661.Dq "Packages and Ports" 662chapter of 663.%B "The FreeBSD Handbook" , 664and 665this manual page. 666