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.37 2003/07/28 20:02:44 sturm Exp $ 27.\" $FreeBSD: ports.7,v 1.7 1998/06/23 04:38:50 hoek Exp $ 28.\" 29.Dd January 25, 1998 30.Dt PORTS 7 31.Os 32.Sh NAME 33.Nm ports 34.Nd contributed applications 35.Sh DESCRIPTION 36The 37.Ox 38Ports Collection 39(shamelessly stolen from the 40.Fx 41Ports Collection) offers a simple way 42for users and administrators to install applications. 43Each port contains any patches necessary to make the original 44application source code compile and run on 45.Ox . 46Compiling an application is as simple as typing 47.Ic make 48in the port directory! 49The 50.Pa Makefile 51automatically fetches the 52application source code, either from a local disk or via ftp, unpacks it 53on the local system, applies the patches, and compiles it. 54If all goes well, simply type 55.Ic sudo make install 56to install the application. 57.Pp 58For more information about using ports, see 59The 60.Ox 61Ports Mechanism 62(http://www.openbsd.org/ports.html) and the 63.Ox 64FAQ (http://www.openbsd.org/faq/). 65For information about creating new ports, see 66the 67.Ox 68Porting Checklist (http://www.openbsd.org/checklist.html). 69.Pp 70For a detailed description of the build process, see 71.Xr bsd.port.mk 5 . 72.Sh PORTS MASTER MAKEFILE 73The ports master Makefile, normally located in 74.Pa /usr/ports/Makefile 75(but see 76.Ev PORTSDIR 77below) 78offers a few useful targets. 79.Bl -tag -width configure 80.It Ar index 81rebuild the ports complete index, 82.Pa /usr/ports/INDEX 83.It Ar mirror-maker 84see 85.Xr mirroring-ports 7 , 86.It Ar print-index 87display the contents of the index in a user-friendly way, 88.It Ar search 89invoked with a key, e.g., 90.Ic make search key=foo , 91retrieve information relevant to a given port (obsolescent). 92.El 93.Sh SELECTING A SET OF PORTS 94If 95.Pa /usr/ports/INDEX 96is up to date, it is possible to select subsets by setting the following 97variables on the command line: 98.Bl -tag -width category 99.It Va key 100package name matching the given key, 101.It Va category 102port belonging to category, 103.It Va maintainer 104port maintained by a given person. 105.El 106.Pp 107For instance, to invoke clean on all ports in the x11 category, one can say: 108.Bd -literal -offset indent 109 $ make category=x11 clean 110.Ed 111.Pp 112The index search is done by a perl script, so all regular expressions from 113.Xr perlre 1 114apply. 115.Sh TARGETS 116Individual ports are controlled through a few documented targets. 117Some of these targets work recursively through subdirectories, so that 118someone can, for examples, install all of the net 119ports. 120.Pp 121In case of failure in a subdirectory, the shell fragment held in 122.Ev REPORT_PROBLEM 123is executed. 124Default behavior is to call exit, but this can be overridden on the command 125line, e.g., to avoid stopping after each problem. 126.Bd -literal -offset indent 127 $ make REPORT_PROBLEM=true 128.Ed 129.Pp 130The targets that do this are 131.Ar build , checksum , clean , configure , 132.Ar extract , fake , fetch , install , 133.Ar distclean , deinstall , reinstall , mirror-distfiles , 134.Ar obj , package , cdrom-packages , link-categories , 135.Ar unlink-categories , 136and 137.Ar ftp-packages . 138.Pp 139Target names starting with _ are private to the ports infrastructure, 140should not be invoked directly, and are liable to change without notice. 141.Pp 142In the following list, each target will run the preceding targets 143in order automatically. 144That is, 145.Ar build 146will be run 147.Pq if necessary 148by 149.Ar install , 150and so on all the way to 151.Ar fetch . 152Typical use only runs 153.Ar install 154explicitly (if root or 155.Ev SUDO 156is defined in 157.Pa /etc/mk.conf ) , 158or 159.Ar build 160(as user), then 161.Ar install 162(as root). 163.Bl -tag -width configure 164.It Ar fetch 165Fetch all of the files needed to build this port from the site(s) 166listed in 167.Ev MASTER_SITES 168and 169.Ev PATCH_SITES . 170See 171.Ev FETCH_CMD 172and 173.Ev MASTER_SITE_OVERRIDE . 174.It Ar checksum 175Verify that the fetched distfile matches the one the port was tested against. 176Defining 177.Ev NO_CHECKSUM 178to 179.Dv Yes 180will skip this step. 181Sometimes, distfiles change without warning. 182The main 183.Ox 184mirror should still hold a copy of old distfiles, indexed by checksum. 185Using 186.Bd -literal -offset indent 187 $ make checksum REFETCH=true 188.Ed 189.Pp 190will try to get a set of distfiles that match the recorded checksum. 191.It Ar depends 192Install 193.Pq or package if only compilation is necessary 194any dependencies of the current port. 195When called by the 196.Ar extract , install 197or 198.Ar fetch 199targets, this is run in scattered pieces as 200.Ar fetch-depends , lib-depends , build-depends , run-depends 201and 202.Ar misc-depends . 203Defining 204.Ev NO_DEPENDS 205to 206.Dv Yes 207will skip this step. 208.It Ar extract 209Expand the distfile into a work directory. 210.It Ar patch 211Apply any patches that are necessary for the port. 212.It Ar configure 213Configure the port. 214Some ports will ask questions during this stage. 215See 216.Ev INTERACTIVE 217and 218.Ev BATCH . 219.It Ar build 220Build the port. 221This is the same as calling the 222.Ar all 223target. 224.It Ar fake 225Pretend to install the port under a subdirectory of the work directory. 226.It Ar package 227Create a binary package from the fake installation. 228The package is a .tgz file that can be used to 229install the port on several machines with 230.Xr pkg_add 1 . 231.It Ar install 232Install the resulting package. 233.El 234.Pp 235The following targets are not run during the normal install process. 236.Bl -tag -width fetch-list 237.It Ar depends-list package-depends 238Print an ordered list of all the compile and run dependencies. 239.It Ar clean 240Remove the expanded source code. 241This does not recurse to dependencies unless 242.Ev CLEANDEPENDS 243is defined to 244.Dv Yes . 245.It Ar distclean 246Remove the port's distfile(s) and perform the 247.Ar clean 248operation. 249This does not recurse to dependencies. 250.It Ar reinstall 251Use this to restore a port after using 252.Xr pkg_delete 1 . 253.It Ar link-categories 254Populate the ports tree with symbolic links for each category the port 255belongs to. 256.It Ar unlink-categories 257Remove the symbolic links created by 258.Ar link-categories . 259.El 260.Sh BULK PACKAGE BUILDING 261The ports tree contains some mechanisms to save space when building 262large collections of packages. 263If 264.Ev BIN_PACKAGES , 265.Ev TRUST_PACKAGES , 266and 267.Ev BULK 268are set to 269.Sq Yes 270for a package build, some shortcuts are taken to allow cleaning up working 271directories on the fly. 272.Pp 273Some important caveats apply: 274the packages already built in the package repository are assumed to be 275up-to-date (BIN_PACKAGES), the database of installed packages is assumed 276to be accurate (TRUST_PACKAGES), and the bulk cookies are assumed to be 277up-to-date (BULK). 278.Pp 279This means that newer iterations of package buildings should make sure 280those conditions are met, which entails erasing old package repository, 281removing packages that need to be rebuilt from the base of installed 282packages, and cleaning up old bulk cookies. 283.Pp 284If any of these conditions is not met, the package build may run into weird 285problems. 286.Sh NETWORK CONFIGURATION 287The variables pertaining to network access have been marshalled into 288.Pa ${PORTSDIR}/infrastructure/template/network.conf.template . 289.Pp 290To customize that setup, copy that file into 291.Pa ${PORTSDIR}/infrastructure/db/network.conf 292and edit it. 293.Pp 294.Bl -tag -width MASTER_SITES 295.It Ev MASTER_SITE_OPENBSD 296If set to 297.Dv Yes , 298include the master 299.Ox 300site when fetching files. 301.It Ev MASTER_SITE_FREEBSD 302If set to 303.Dv Yes , 304include the master 305.Fx 306site when fetching files. 307.It Ev MASTER_SITE_OVERRIDE 308Go to this site first for all files. 309.El 310.Sh FLAVORS 311The 312.Ox 313ports tree comes with a mechanism called 314.Ic FLAVORS . 315Thanks to this mechanism, users can select specific options provided by 316a given port. 317.Pp 318If a port is "flavored", there should be a terse description of 319available flavors in the 320.Pa pkg/DESCR 321file. 322.Pp 323For example, the shells/bash port comes with a flavor called 324.Ic static . 325This changes the building process so a statically compiled version of 326the program will be built. 327To avoid confusion with other packages or flavors, 328the package name will be extended with a dash-separated list of 329the selected flavors. 330.Pp 331In this instance, the corresponding package will be called 332.Ic bash-1.14.7p1-static . 333.Pp 334To build a port with a specific flavor, just pass 335.Ev FLAVOR 336in the environment of the 337.Xr make 1 338command: 339.Pp 340.Bd -literal -offset indent 341$ env FLAVOR="static" make package 342.Ed 343.Pp 344and of course, use the same settings for the subsequent invocations of make: 345.Bd -literal -offset indent 346$ env FLAVOR="static" make package 347$ env FLAVOR="static" make clean 348.Ed 349.Pp 350More than one flavor may be specified: 351.Bd -literal -offset indent 352$ cd /usr/ports/mail/exim 353$ env FLAVOR="mysql ldap" make package 354.Ed 355.Pp 356Specifying a flavor that does not exist is an error. 357Additionally, some ports impose some further restrictions on flavor 358combinations, when such combinations do not make sense. 359.Pp 360Lots of ports can be built without X11 requirement and accordingly 361have a 362.Ic no_x11 363flavor. 364.Pp 365Flavor settings are not propagated to dependencies. 366If a specific combination is needed, careful hand-building of the 367required set of packages is still necessary. 368.Sh PORT VARIABLES 369These can be changed in the environment, or in 370.Pa /etc/mk.conf 371for persistence. 372They can also be set on make's command line, e.g., 373.Ic make VAR_FOO=foo 374.Pp 375Boolean variables should be set to 376.Dv Yes 377instead of simply being defined, for uniformity and future compatibility. 378.Pp 379Variable names starting with _ are private to the ports infrastructure, 380should not be changed by the user, and are liable to change without notice. 381.Pp 382.Bl -tag -width MASTER_SITES 383.It Ev PORTSDIR 384Location of the ports tree 385.Po 386usually 387.Pa /usr/ports 388.Pc 389.It Ev DISTDIR 390Where to find/put distfiles, normally 391.Pa distfiles/ 392in 393.Ev PORTSDIR . 394.It Ev PACKAGES 395Used only for the 396.Ar package 397target; the base directory for the packages tree, normally 398.Pa packages/${MACHINE_ARCH} 399in 400.Ev PORTSDIR . 401If this directory exists, the package tree will be (partially) constructed. 402This directory does not have to exist; if it doesn't, packages will be 403placed into the current directory, or define one of 404.Bl -tag -width PKGREPOSITORY 405.It Ev PKGREPOSITORY 406Directory to put the package in. 407.It Ev PKGFILE 408The full path to the package. 409.El 410.It Ev BULK_COOKIES_DIR 411During bulk package building, used to store cookies for already built 412packages to avoid rebuilding them, since the actual 413working directory will already have been cleaned out. 414Defaults to bulk/${MACHINE_ARCH} under 415.Ev PORTSDIR . 416.It Ev LOCALBASE 417Where to install things in general 418.Po 419usually 420.Pa /usr/local 421.Pc 422.It Ev MASTER_SITES 423Primary sites for distribution files if not found locally. 424.It Ev PATCH_SITES 425Primary location(s) for distribution patch files if not found 426locally. 427.It Ev CLEANDEPENDS 428If set to 429.Dv Yes , 430let 431.Sq clean 432recurse to dependencies. 433.It Ev NOCLEANDEPENDS 434If defined, don't let 435.Sq clean 436recurse to dependencies (deprecated, use 437.Ev CLEANDEPENDS 438instead). 439.It Ev FETCH_CMD 440Command to use to fetch files. 441Normally 442.Xr ftp 1 . 443.It Ev FORCE_PKG_REGISTER 444If set, overwrite any existing package registration on the system. 445.Po 446Not recommended. 447.Pc 448.It Ev PATCH_DEBUG 449If defined, display verbose output when applying each patch. 450.It Ev INTERACTIVE 451If defined, only operate on a port if it requires interaction. 452.It Ev BATCH 453If defined, only operate on a port if it can be installed 100% automatically. 454.It Ev USE_SYSTRACE 455Set to 456.Sq Yes 457to protect the 458.Ar configure , build , 459and 460.Ar fake 461targets with 462.Xr systrace 1 . 463This way it is ensured that ports do not make any network connections 464during build or write outside some well defined directories. 465The filter list is stored in 466.Pa ${PORTSDIR}/infrastructure/db/systrace.filter . 467.El 468.Sh USING A READ-ONLY PORTS TREE 469Select read-write partition(s) that can accommodate working directories, the 470distfiles repository, and the built packages. 471Set 472.Ev WRKOBJDIR , 473.Ev PACKAGES , 474.Ev BULK_COOKIES_DIR 475and 476.Ev DISTDIR 477in 478.Pa /etc/mk.conf 479accordingly. 480.Sh FILES 481.Bl -tag -width /usr/ports/xxxxxxxx -compact 482.It Pa /usr/ports 483The default ports directory. 484.It Pa /usr/ports/Makefile 485Ports master Makefile. 486.It Pa /usr/ports/INDEX 487Ports index. 488.It Pa /usr/ports/infrastructure/mk/bsd.port.mk 489The ports main engine. 490.It Pa /usr/ports/infrastructure/templates/network.conf.template 491Network configuration defaults. 492.It Pa /usr/ports/infrastructure/db/network.conf 493Local network configuration. 494.It Pa /usr/ports/infrastructure/db/systrace.filter 495Filter list for systrace. 496.It Pa /usr/ports/infrastructure/db/user.list 497List of users and groups created by ports. 498.El 499.Sh SEE ALSO 500.Xr make 1 , 501.Xr pkg_add 1 , 502.Xr pkg_create 1 , 503.Xr pkg_delete 1 , 504.Xr pkg_info 1 , 505.Xr bsd.port.mk 5 , 506.Xr packages 7 507.Pp 508The 509.Ox 510Ports Mechanism: http://www.openbsd.org/ports.html 511.Pp 512The 513.Ox 514Porting Checklist: http://www.openbsd.org/checklist.html 515.Sh HISTORY 516.Nm The Ports Collection 517appeared in 518.Fx 1.0 . 519It was introduced in 520.Ox 521by Ejovi Nuwere, with much initial effort by Angelos D. Keromytis. 522Maintenance passed then to Marco S. Hyman, and then to Christopher Turan. 523It is currently managed by Marc Espie, Brad Smith, and Christian Weisgerber, 524along with a host of others found at ports@openbsd.org. 525.Sh AUTHORS 526This man page was originated by 527David O'Brien, from the 528.Fx 529project. 530.Sh BUGS 531Ports documentation is split over several places --- 532.Xr bsd.port.mk 5 , 533the 534.Dq Ports Collection 535section of the 536.Fx 537handbook, the 538.Dq Porting Existing Software 539section of the 540.Fx 541handbook, 542and some man pages. 543.Ox 544adds a few web pages to further confuse the issue. 545