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.\" $OpenBSD: ports.7,v 1.130 2022/07/20 16:37:50 espie Exp $ 27.\" $FreeBSD: ports.7,v 1.7 1998/06/23 04:38:50 hoek Exp $ 28.\" 29.Dd $Mdocdate: July 20 2022 $ 30.Dt PORTS 7 31.Os 32.Sh NAME 33.Nm ports 34.Nd contributed applications 35.Sh DESCRIPTION 36The 37.Ox 38Ports Collection 39is the infrastructure used to create binary packages for third party 40applications. 41.Pp 42For normal usage refer to 43.Xr packages 7 , 44as most ports produce binary packages which are available from 45the official HTTP mirrors. 46.Pp 47Each port contains any patches necessary to make the original 48application source code compile and run on 49.Ox . 50Compiling an application is as simple as typing 51.Ic make 52in the port directory! 53The 54.Pa Makefile 55automatically fetches the 56application source code, either from a local disk or via HTTP, unpacks it 57on the local system, applies the patches, and compiles it. 58If all goes well, simply type 59.Ic doas make install 60to install the application. 61.Pp 62For more information about using ports, see 63.Lk https://www.openbsd.org/faq/ports/ports.html "Working with Ports" . 64For information about creating new ports, see 65.Lk https://www.openbsd.org/faq/ports/ "The OpenBSD Porter's Handbook" . 66.Pp 67For a detailed description of the build process, see 68.Xr bsd.port.mk 5 . 69.Sh PORTS MASTER MAKEFILE 70The ports master Makefile, normally located in 71.Pa /usr/ports/Makefile 72(but see 73.Ev PORTSDIR 74below) 75offers a few deprecated targets for the time being. 76.Bl -tag -width print-index 77.It Cm print-index 78display the contents of the index in a 79.Sq user-friendly 80way, 81.It Cm search 82invoked with a key, e.g., 83.Ic make search key=foo , 84retrieve information relevant to a given port (obsolescent). 85.El 86.Pp 87Starting in 88.Ox 4.0 , 89there is a port, 90.Pa databases/sqlports , 91that builds an sqlite database containing most information relevant to 92every port in the ports tree. 93This database can be searched using any tool able to manipulate such 94databases, for instance sqlitebrowser, or a script language with an 95sqlite interface, e.g., perl, python, ocaml, lua, php. 96.Pp 97All static index generating information has now been superseded by the 98.Pa sqlports , 99.Pa portslist 100or 101.Pa pkglocatedb 102packages, which contain 103similar information to the old INDEX file, but are frequently updated. 104See 105.Pa databases/sqlports 106.Pa databases/pkglocatedb 107and 108.Xr pkg_mklocatedb 1 109for details. 110.Sh SELECTING A SET OF PORTS 111One can define 112.Ev SUBDIRLIST 113to point to a file that contains a list of 114.Ev FULLPKGPATHs , 115one per line, to build stuff only in some directories. 116.Pp 117If 118.Pa portslist 119is up to date, it is possible to select subsets by setting the following 120variables on the command line: 121.Bl -tag -width category 122.It Va key 123package name matching the given key, 124.It Va category 125port belonging to category, 126.It Va maintainer 127port maintained by a given person. 128.El 129.Pp 130For instance, to invoke 131.Cm clean 132on all ports in the x11 category, one can say: 133.Bd -literal -offset indent 134$ make category=x11 clean 135.Ed 136.Pp 137The index search is done by a perl script, so all regular expressions from 138.Xr perlre 1 139apply. 140.Sh TARGETS 141Individual ports are controlled through a few documented targets. 142Some of these targets work recursively through subdirectories, so that 143someone can, for example, install all of the net 144ports. 145.Pp 146The variable 147.Ev SKIPDIR 148can hold a set of package directories to avoid during recursion. 149These are always specified relative to the root of the ports tree, 150and can contain a flavor or subpackage part 151.Po 152see 153.Xr packages-specs 7 154.Pc . 155.Ev SKIPDIR 156is handled by a 157.Ic case 158statement, and so can contain simple wildcards 159.Po 160see 161.Xr sh 1 162.Dq File name patterns 163.Pc , 164e.g., SKIPDIR='editors/openoffice*'. 165.Pp 166The variable 167.Ev STARTDIR 168can hold the path to a starting directory. 169The recursion will skip all directories up to that package path. 170This can be used to resume a full build at some specific point without having 171to go through thousands of directories first. 172.Pp 173The variable 174.Ev STARTAFTER 175can hold the path to a starting directory. 176The recursion will skip all directories up to and including that package path. 177This can be used to resume a full build after some specific point without having 178to go through thousands of directories first. 179.Pp 180In case of failure in a subdirectory, the shell fragment held in 181.Ev REPORT_PROBLEM 182is executed. 183Default behavior is to call exit, but this can be overridden on the command 184line, e.g., to avoid stopping after each problem. 185.Bd -literal -offset indent 186$ make REPORT_PROBLEM=true 187.Ed 188.Pp 189If 190.Ev REPORT_PROBLEM_LOGFILE 191is non empty, then 192.Ev REPORT_PROBLEM 193will default to: 194.Bd -literal -offset indent 195echo $$subdir ($@) >>$${REPORT_PROBLEM_LOGFILE} 196.Ed 197.Pp 198That is, any failure will append the faulty directory name together 199with the target that failed to 200.Pa ${REPORT_PROBLEM_LOGFILE} 201and proceed. 202.Pp 203Some targets that do this are 204.Cm all , build , checksum , clean , 205.Cm configure , extract , fake , 206.Cm fetch , install , distclean , 207.Cm deinstall , reinstall , package , prepare , 208.Cm link-categories , unlink-categories , 209.Cm describe , show , regress , 210.Cm lib-depends-check , homepage-links , manpages-check , 211.Cm license-check , all-dir-depends , build-dir-depends , 212.Cm run-dir-depends 213and 214.Cm readmes . 215.Pp 216Target names starting with 217.Sq _ 218are private to the ports infrastructure, 219should not be invoked directly, and are liable to change without notice. 220.Pp 221In the following list, each target will run the preceding targets 222in order automatically. 223That is, 224.Cm build 225will be run 226.Pq if necessary 227by 228.Cm install , 229and so on all the way to 230.Cm fetch . 231In typical use, one will only run 232.Cm install 233explicitly (as normal user, with 234.Ev SUDO 235defined in 236.Pa /etc/mk.conf ) , 237or 238.Cm build 239(as user), then 240.Cm install 241(as root). 242.Bl -tag -width configure 243.It Cm fetch 244Fetch all of the files needed to build this port from the site(s) 245listed in 246.Ev MASTER_SITES . 247See 248.Ev FETCH_CMD . 249Use 250.Xr dpb 1 251with option 252.Fl F 253to quickly fetch distfiles for a subtree. 254.It Cm checksum 255Verify that the fetched distfile matches the one the port was tested against. 256Defining 257.Ev NO_CHECKSUM 258to 259.Dv Yes 260will skip this step. 261Sometimes, distfiles change without warning. 262The main 263.Ox 264mirror should still hold a copy of old distfiles, indexed by checksum. 265Using 266.Bd -literal -offset indent 267$ make checksum REFETCH=true 268.Ed 269.Pp 270will try to get a set of distfiles that match the recorded checksum. 271.It Cm prepare 272Install 273any build dependencies of the current port. 274Defining 275.Ev NO_DEPENDS 276to 277.Dv Yes 278will skip this step. 279.It Cm extract 280Expand the distfile into a work directory. 281.It Cm patch 282Apply any patches that are necessary for the port. 283.It Cm gen 284Recreate configure machinery if needed, mainly used by GNU based software 285that wants autogen/autoconf/automake. 286.It Cm configure 287Configure the port. 288Some ports will ask questions during this stage. 289See 290.Ev INTERACTIVE 291and 292.Ev BATCH . 293.It Cm build 294Build the port. 295This is the same as calling the 296.Cm all 297target. 298.It Cm fake 299Pretend to install the port under a subdirectory of the work directory. 300.It Cm generate-readmes 301Create READMEs and rc scripts under the fake subdirectory. 302.It Cm package 303Create a binary package from the fake installation. 304The package is a .tgz file that can be used to 305install the port with 306.Xr pkg_add 1 . 307.It Cm install 308Install the resulting package. 309.El 310.Pp 311The following targets are not run during the normal install process 312.Po 313exception 314.Cm clean 315is run for dependencies with the default settings of 316.Ev BULK Ns = Ns Dv Auto 317.Pc . 318.Bl -tag -width fetch-list 319.It Cm print-build-depends , print-run-depends 320Print an ordered list of all the compile and run dependencies. 321.It Cm clean 322Remove the expanded source code. 323This does not recurse to dependencies unless 324.Ev CLEANDEPENDS 325is defined to 326.Dv Yes . 327.It Cm distclean 328Remove the port's distfile(s). 329This does not recurse to dependencies. 330.It Cm regress 331Runs the ports regression tests. 332Usually needs a completed build. 333.It Cm reinstall 334Use this to restore a port after using 335.Xr pkg_delete 1 . 336.It Cm update 337Alternative target to 338.Cm install . 339Does not install new packages, but updates existing ones. 340.It Cm link-categories 341Populate the ports tree with symbolic links for each category the port 342belongs to. 343.It Cm unlink-categories 344Remove the symbolic links created by 345.Cm link-categories . 346.It Cm homepage-links 347creates an html list of links for each port 348.Ev HOMEPAGE . 349.El 350.Sh LOCK INFRASTRUCTURE 351The ports tree can be used concurrently for building several ports at the 352same time, thanks to a locking mechanism. 353By default, locks are stored under 354.Pa /tmp/portslocks . 355Defining 356.Ev LOCKDIR 357will point them elsewhere, or disable the mechanism if set to an empty value. 358.Pp 359All locks will be stored in 360.Pa ${LOCKDIR} . 361.Ev LOCK_CMD 362should be used to acquire a lock, and 363.Ev UNLOCK_CMD 364should be used to release it. 365.Pp 366Locks are named 367.Pa ${LOCKDIR}/${FULLPKGNAME}.lock , 368or 369.Pa ${LOCKDIR}/${DISTFILE}.lock 370for distfiles fetching. 371.Pp 372The default values of 373.Ev LOCK_CMD 374and 375.Ev UNLOCK_CMD 376are appropriate for most uses. 377.Pp 378The locking protocol follows a big-lock model: each top-level target 379in a port directory will acquire the corresponding lock, complete its job, 380then release the lock, e.g., running 381.Bd -literal -offset indent 382$ make build 383.Ed 384.Pp 385will acquire the lock, run the port 386through 387.Cm fetch , 388.Cm checksum , 389.Cm extract , 390.Cm patch , 391.Cm configure , 392.Cm build , 393then release the lock. 394If dependencies are involved, they will invoke top-level targets in other 395directories, and thus acquire some other locks as well. 396.Pp 397The infrastructure contains some protection against acquiring the same lock 398twice, thus recursive locking is not needed for 399.Ev LOCK_CMD . 400.Pp 401Starting with 402.Ox 4.3 , 403the infrastructure supports manual locking: the targets 404.Cm lock 405and 406.Cm unlock 407can be used to acquire and release individual locks. 408Both these targets output a shell command that must be used to update 409environment variables. 410Manual locking can be used to protect a directory against interference 411by an automated build job, while the user is looking at or modifying a 412given port. 413.Sh UPDATING PACKAGES 414Instead of deinstalling each package and rebuilding from scratch, the 415ports tree can be used to update installed packages. 416The 417.Cm update 418target will replace an installed package using 419.Xr pkg_add 1 420in replacement mode. 421If 422.Ev FORCE_UPDATE 423is set to 424.Dv Yes , 425dependencies will also be updated first, and packages will always be updated, 426even if there is no difference between the old and the new packages. 427.Pp 428Updates use a mechanism similar to bulk cookies and deposit cookies in 429the 430.Ev UPDATE_COOKIES_DIR . 431See the next section for more details, since most of the fine points of 432bulk package building also apply to updates. 433.Pp 434However, also note that 435.Li make update 436is not guaranteed to work, see 437.Sx CAVEATS 438below. 439.Sh BULK PACKAGE BUILDING 440Building any significant number of packages from the ports tree should use 441.Xr dpb 1 , 442a tool located inside the ports tree proper 443.Po 444normally as 445.Pa /usr/ports/infrastructure/bin/dpb 446.Pc . 447In particular, it can take advantage of machine clusters (same architecture 448and same installation), and of multi-core machines. 449.Pp 450For more detailed information, see 451.Xr bulk 8 . 452.Sh FLAVORS 453The 454.Ox 455ports tree comes with a mechanism called 456.Ic FLAVORS . 457Thanks to this mechanism, users can select specific options provided by 458a given port. 459.Pp 460If a port is 461.Qq flavored , 462there should be a terse description of available flavors in the 463.Pa pkg/DESCR 464file. 465.Pp 466For example, the 467.Pa misc/screen 468port comes with a flavor called 469.Ic static . 470This changes the building process so a statically compiled version of 471the program will be built. 472To avoid confusion with other packages or flavors, 473the package name will be extended with a dash-separated list of 474the selected flavors. 475.Pp 476In this instance, the corresponding package will be called 477.Ic screen-4.0.2-static . 478.Pp 479To see the flavors of a port, use the 480.Cm show 481target: 482.Bd -literal -offset indent 483$ make show=FLAVORS 484.Ed 485.Pp 486To build a port with a specific flavor, just pass 487.Ev FLAVOR 488in the environment of the 489.Xr make 1 490command: 491.Bd -literal -offset indent 492$ env FLAVOR="static" make package 493.Ed 494.Pp 495and of course, use the same settings for the subsequent invocations of make: 496.Bd -literal -offset indent 497$ env FLAVOR="static" make install 498$ env FLAVOR="static" make clean 499.Ed 500.Pp 501More than one flavor may be specified: 502.Bd -literal -offset indent 503$ cd /usr/ports/mail/exim 504$ env FLAVOR="mysql ldap" make package 505.Ed 506.Pp 507Specifying a flavor that does not exist is an error. 508Additionally, some ports impose some further restrictions on flavor 509combinations, when such combinations do not make sense. 510.Pp 511Lots of ports can be built without X11 requirement and accordingly 512have a 513.Ic no_x11 514flavor. 515.Pp 516Flavor settings are not propagated to dependencies. 517If a specific combination is needed, careful hand-building of the 518required set of packages is still necessary. 519.Sh MULTI_PACKAGES 520The 521.Ox 522ports tree comes with a mechanism called 523.Ic MULTI_PACKAGES . 524This mechanism is used when a larger package is broken down into 525several smaller components referred to as subpackages. 526.Pp 527If a port is 528.Qq subpackaged , 529each subpackage will have a corresponding description in the 530.Pa pkg/DESCR-subpackage 531file. 532.Pp 533For example, the 534.Pa databases/mariadb 535port comes with subpackages called 536.Ic -main , 537.Ic -tests 538and 539.Ic -server . 540.Pp 541In this instance, the build will yield multiple packages, one 542corresponding to each subpackage. 543In the case of our mariadb example, 544the packages will be called 545.Ic mariadb-client-<version> , 546.Ic mariadb-tests-<version> , 547and 548.Ic mariadb-server-<version> . 549.Pp 550To install/deinstall a specific subpackage of a port, you may 551.Xr pkg_add 1 552them manually, or alternatively, you may set 553.Ev SUBPACKAGE 554in the environment of the 555.Xr make 1 556command during the install/deinstall phase: 557.Bd -literal -offset indent 558$ env SUBPACKAGE="-server" make install 559$ env SUBPACKAGE="-server" make deinstall 560.Ed 561.Sh PORT VARIABLES 562These can be changed in the environment, or in 563.Pa /etc/mk.conf 564for persistence. 565They can also be set on make's command line, e.g., 566.Ic make VAR_FOO Ns = Ns Dv foo 567.Pp 568Boolean variables should be set to 569.Dv Yes 570instead of simply being defined, for uniformity and future compatibility. 571.Pp 572Variable names starting with 573.Sq _ 574are private to the ports infrastructure, 575should not be changed by the user, and are liable to change without notice. 576.Bl -tag -width MASTER_SITES 577.It Ev PORTS_PRIVSEP 578If set to 579.Sq Yes , 580all operations will happen as restricted users 581.Ar _pfetch 582and 583.Ar _pbuild . 584.It Ev PORTSDIR 585Location of the ports tree 586(usually 587.Pa /usr/ports ) . 588.It Ev DISTDIR 589Where to find/put distfiles, normally 590.Pa ${PORTSDIR}/distfiles . 591.It Ev PACKAGE_REPOSITORY 592Used only for the 593.Cm package 594target; the base directory for the packages tree, normally 595.Pa ${PORTSDIR}/packages . 596If this directory exists, the package tree will be (partially) constructed. 597.It Ev BULK_COOKIES_DIR 598During bulk package building, used to store cookies for already built 599packages to avoid rebuilding them, since the actual 600working directory will already have been cleaned out. 601Defaults to 602.Pa ${PORTSDIR}/bulk/${MACHINE_ARCH} . 603.It Ev UPDATE_COOKIES_DIR 604Used to store cookies for package updates, defaults to 605.Pa ${PORTSDIR}/update/${MACHINE_ARCH} . 606If set to empty, it will revert to a file under 607.Pa ${WRKDIR} . 608.It Ev LOCALBASE 609Where to install things in general 610(usually 611.Pa /usr/local ) . 612.It Ev MASTER_SITES 613Primary sites for distribution files if not found locally. 614.It Ev CLEANDEPENDS 615If set to 616.Dv Yes , 617let 618.Cm clean 619recurse to dependencies. 620.It Ev FETCH_CMD 621Command to use to fetch files. 622Normally 623.Xr ftp 1 . 624.It Ev FETCH_PACKAGES 625If set, 626try to use as options to 627.Xr pkg_add 1 628to install missing packages from 629.Ev PKG_PATH . 630.Xr bsd.port.mk 5 631does not set 632.Ev FETCH_PACKAGES , 633so even an empty value amounts to setting the variable. 634.Pp 635For instance, to run 636.Xr pkg_add 1 637with default options : 638.Bd -literal -offset indent 639make FETCH_PACKAGES= 640.Ed 641.Pp 642or, to use the snapshots directory during the final beta period: 643.Bd -literal -offset indent 644make FETCH_PACKAGES=-Dsnap 645.Ed 646.It Ev PATCH_DEBUG 647If defined, display verbose output when applying each patch. 648.It Ev INTERACTIVE 649If defined, only operate on a port if it requires interaction. 650.It Ev BATCH 651If defined, only operate on a port if it can be installed 100% automatically. 652.El 653.Sh USING A READ-ONLY PORTS TREE 654Select read-write partition(s) that can accommodate working directories, the 655distfiles repository, and the built packages. 656Set 657.Ev WRKOBJDIR , 658.Ev PACKAGE_REPOSITORY , 659.Ev BULK_COOKIES_DIR , 660.Ev UPDATE_COOKIES_DIR , 661.Ev DISTDIR , 662and 663.Ev PLIST_REPOSITORY 664in 665.Pa /etc/mk.conf 666accordingly. 667.Sh FILES 668.Bl -tag -width /usr/ports/xxxxxxxx -compact 669.It Pa /usr/ports 670The default ports directory. 671.It Pa /usr/ports/Makefile 672Ports master Makefile. 673.It Pa /usr/local/share/ports-INDEX 674Ports index, part of the 675.Pa portlist 676package. 677.It Pa /usr/ports/pobj 678Build directories. 679A number of insecurely coded ports require a dedicated file system with the 680.Cm wxallowed 681.Xr mount 8 682option. 683.It Pa /usr/ports/infrastructure/mk/bsd.port.mk 684The ports main engine. 685.It Pa /usr/ports/infrastructure/db/network.conf 686Network configuration. 687.It Pa /usr/ports/infrastructure/db/user.list 688List of users and groups created by ports. 689.El 690.Sh SEE ALSO 691.Xr dpb 1 , 692.Xr make 1 , 693.Xr pkg_add 1 , 694.Xr pkg_create 1 , 695.Xr pkg_delete 1 , 696.Xr pkg_info 1 , 697.Xr bsd.port.mk 5 , 698.Xr port-modules 5 , 699.Xr mirroring-ports 7 , 700.Xr packages 7 701.Pp 702The 703.Ox 704Ports System: 705.Lk https://www.openbsd.org/faq/ports/ports.html 706.Pp 707The 708.Ox 709Porter's Handbook: 710.Lk https://www.openbsd.org/faq/ports/ 711.Sh HISTORY 712.Nm The Ports Collection 713appeared in 714.Fx 1.0 . 715It was introduced in 716.Ox 717by Ejovi Nuwere, with much initial effort by Angelos D. Keromytis. 718Maintenance passed then to Marco S. Hyman, and then to Christopher Turan. 719It is currently managed by Marc Espie, Christian Weisgerber, 720along with a host of others found at 721.Mt ports@openbsd.org . 722.Sh AUTHORS 723This man page was originated by 724.An David O'Brien , 725from the 726.Fx 727project. 728.Sh CAVEATS 729Building a new version of an already installed package is not guaranteed 730to work. 731.Pp 732The safer way would be to create a sandbox for building the updated port 733using 734.Xr proot 1 735.Po see also 736.Xr bulk 8 737.Pc , 738and then update the installed package. 739.Pp 740Specifically: most software expects building in a virgin environment 741with only the required dependency. 742As a result, lots of time, libraries and headers under 743.Pa /usr/local 744will be favored over the currently building version. 745