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