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