2 .\" Copyright (c) 1997 David E. O'Brien
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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.
26 .\" $OpenBSD: ports.7,v 1.95 2013/06/19 08:59:02 espie Exp $
27 .\" $FreeBSD: ports.7,v 1.7 1998/06/23 04:38:50 hoek Exp $
29 .Dd $Mdocdate: June 19 2013 $
34 .Nd contributed applications
39 is the infrastructure used to create binary packages for third party
42 For normal usage refer to
44 as most ports produce binary packages which are available from
45 the official CD-ROM, or on a neighborly FTP mirror.
47 Each port contains any patches necessary to make the original
48 application source code compile and run on
50 Compiling an application is as simple as typing
52 in the port directory!
55 automatically fetches the
56 application source code, either from a local disk or via ftp, unpacks it
57 on the local system, applies the patches, and compiles it.
58 If all goes well, simply type
60 to install the application.
62 For more information about using ports, see
66 .Pq Lk http://www.openbsd.org/faq/ports/ports.html .
67 For information about creating new ports, see
71 .Pq Lk http://www.openbsd.org/faq/ports/ .
73 For a detailed description of the build process, see
75 .Sh PORTS MASTER MAKEFILE
76 The ports master Makefile, normally located in
77 .Pa /usr/ports/Makefile
81 offers a few useful targets.
82 .Bl -tag -width configure
84 rebuild the ports complete index,
88 .Xr mirroring-ports 7 ,
92 database file and place it in
93 .Pa ${PORTSDIR}/packages/${MACHINE_ARCH}/ftp ,
97 display the contents of the index in a user-friendly way,
99 invoked with a key, e.g.,
100 .Ic make search key=foo ,
101 retrieve information relevant to a given port (obsolescent).
107 .Pa databases/sqlports
108 that builds an sqlite database containing most information relevant to
109 every port in the ports tree.
110 This database can be searched using any tool able to manipulate such
111 databases, for instance sqlitebrowser, or a script language with an
112 sqlite interface, e.g., perl, python, ocaml, lua, php5.
113 .Sh SELECTING A SET OF PORTS
116 to point to a file that contains a list of
118 one per line, to build stuff only in some directories.
122 is up to date, it is possible to select subsets by setting the following
123 variables on the command line:
124 .Bl -tag -width category
126 package name matching the given key,
128 port belonging to category,
130 port maintained by a given person.
133 For instance, to invoke
135 on all ports in the x11 category, one can say:
136 .Bd -literal -offset indent
137 $ make category=x11 clean
140 The index search is done by a perl script, so all regular expressions from
144 Individual ports are controlled through a few documented targets.
145 Some of these targets work recursively through subdirectories, so that
146 someone can, for example, install all of the net
151 can hold a set of package directories to avoid during recursion.
152 These are always specified relative to the root of the ports tree,
153 and can contain a flavor or subpackage part
161 statement, and so can contain simple wildcards
165 .Dq File name patterns
167 e.g., SKIPDIR='editors/openoffice*' .
171 can hold the path to a starting directory.
172 The recursion will skip all directories up to that package path.
173 This can be used to resume a full build at some specific point without having
174 to go through thousands of directories first.
178 can hold the path to a starting directory.
179 The recursion will skip all directories up to and including that package path.
180 This can be used to resume a full build after some specific point without having
181 to go through thousands of directories first.
183 In case of failure in a subdirectory, the shell fragment held in
186 Default behavior is to call exit, but this can be overridden on the command
187 line, e.g., to avoid stopping after each problem.
188 .Bd -literal -offset indent
189 $ make REPORT_PROBLEM=true
193 .Ev REPORT_PROBLEM_LOGFILE
197 .Bd -literal -offset indent
198 echo $$d ($@) >$${REPORT_PROBLEM_LOGFILE}
201 That is, any failure will append the faulty directory name together
202 with the target that failed to
203 .Pa ${REPORT_PROBLEM_LOGFILE}
206 Some targets that do this are
207 .Ar all , build , checksum , clean ,
208 .Ar configure , extract , fake ,
209 .Ar fetch , install , distclean ,
210 .Ar deinstall , reinstall , package , prepare ,
211 .Ar link-categories , unlink-categories ,
212 .Ar describe , show , regress ,
213 .Ar lib-depends-check , homepage-links , manpages-check ,
214 .Ar license-check , all-dir-depends , build-dir-depends ,
219 Target names starting with
221 are private to the ports infrastructure,
222 should not be invoked directly, and are liable to change without notice.
224 In the following list, each target will run the preceding targets
225 in order automatically.
232 and so on all the way to
234 In typical use, one will only run
236 explicitly (as normal user, with
245 .Bl -tag -width configure
247 Fetch all of the files needed to build this port from the site(s)
253 .Ev MASTER_SITE_OVERRIDE .
258 to quickly fetch distfiles for a subtree.
260 Verify that the fetched distfile matches the one the port was tested against.
266 Sometimes, distfiles change without warning.
269 mirror should still hold a copy of old distfiles, indexed by checksum.
271 .Bd -literal -offset indent
272 $ make checksum REFETCH=true
275 will try to get a set of distfiles that match the recorded checksum.
278 any build dependencies of the current port.
285 Expand the distfile into a work directory.
287 Apply any patches that are necessary for the port.
290 Some ports will ask questions during this stage.
297 This is the same as calling the
301 Pretend to install the port under a subdirectory of the work directory.
303 Create a binary package from the fake installation.
304 The package is a .tgz file that can be used to
305 install the port with
308 Install the resulting package.
311 The following targets are not run during the normal install process.
312 .Bl -tag -width fetch-list
313 .It Ar print-build-depends , print-run-depends
314 Print an ordered list of all the compile and run dependencies.
316 Remove the expanded source code.
317 This does not recurse to dependencies unless
322 Remove the port's distfile(s).
323 This does not recurse to dependencies.
325 Runs the ports regression tests.
326 Usually needs a completed build.
328 Use this to restore a port after using
331 Alternative target to
333 Does not install new packages, but updates existing ones.
334 .It Ar link-categories
335 Populate the ports tree with symbolic links for each category the port
337 .It Ar unlink-categories
338 Remove the symbolic links created by
339 .Ar link-categories .
340 .It Ar homepage-links
341 creates an html list of links for each port
344 .Sh LOCK INFRASTRUCTURE
345 The ports tree can be used concurrently for building several ports at the
346 same time, thanks to a locking mechanism.
347 By default, locks are stored under
348 .Pa /tmp/portslocks .
351 will point them elsewhere, or disable the mechanism if set to an empty value.
353 All locks will be stored in
356 should be used to acquire a lock, and
358 should be used to release it.
361 .Pa ${LOCKDIR}/${FULLPKGNAME}.lock ,
363 .Pa ${LOCKDIR}/${DISTFILE}.lock
364 for distfiles fetching.
366 The default values of
370 are appropriate for most uses.
372 The locking protocol follows a big-lock model: each top-level target
373 in a port directory will acquire the corresponding lock, complete its job,
374 then release the lock, e.g., running
375 .Bd -literal -offset indent
379 will acquire the lock, run the port
387 then release the lock.
388 If dependencies are involved, they will invoke top-level targets in other
389 directories, and thus acquire some other locks as well.
391 The infrastructure contains some protection against acquiring the same lock
392 twice, thus recursive locking is not needed for
397 the infrastructure supports manual locking: the targets
401 can be used to acquire and release individual locks.
402 Both these targets output a shell command that must be used to update
403 environment variables.
404 Manual locking can be used to protect a directory against interference
405 by an automated build job, while the user is looking at or modifying a
407 .Sh UPDATING PACKAGES
408 Instead of deinstalling each package and rebuilding from scratch, the
409 ports tree can be used to update installed packages.
412 target will replace an installed package using
419 dependencies will also be updated first, and packages will always be updated,
420 even if there is no difference between the old and the new packages.
422 Updates use a mechanism similar to bulk cookies and deposit cookies in
424 .Ev UPDATE_COOKIES_DIR .
425 See the next section for more details, since most of the fine points of
426 bulk package building also apply to updates.
428 There are bugs in the ports tree, most related to libtool, which make some
429 updates prefer the already installed libraries instead of the newly built
431 This shows up as undefined references in libraries, in which case there
432 is no choice but to proceed the old way: deinstall the offending package
433 and everything built on top of it, build and install new packages.
434 .Sh BULK PACKAGE BUILDING
435 Building any significant number of packages from the ports tree should use
437 a tool located inside the ports tree proper
440 .Pa /usr/ports/infrastructure/bin/dpb
442 In particular, it can take advantage of machine clusters (same architecture
443 and same installation), and of multi-core machines.
445 A few remarks may save a lot of time
448 The default limits in
450 are inappropriate for bulk builds.
451 .Ar maxproc , openfiles , datasize
452 should be cranked way up, especially for parallel builds.
453 For instance, a lot of C++-based ports will require a
457 cluster builds should have shared
461 If possible, dedicated
467 as far as possible, the log directory should be local to the machine running
470 a full bulk will fetch over 20G of distfiles, create over 17G of packages.
471 The largest work directories are about 10G each.
474 .Ev CHECKSUM_PACKAGES
479 during official package builds to compute partial sha256 checksum files.
481 At the end of the build, just
482 .Bd -literal -offset indent
483 cd ${PORTSDIR}/packages/${MACHINE_ARCH}/cksums && cat * >sha256
486 .Sh NETWORK CONFIGURATION
487 The variables pertaining to network access have been marshalled into
488 .Pa ${PORTSDIR}/infrastructure/templates/network.conf.template .
490 To customize that setup, copy that file into
491 .Pa ${PORTSDIR}/infrastructure/db/network.conf
493 .Bl -tag -width MASTER_SITES
494 .It Ev MASTER_SITE_OPENBSD
499 site when fetching files.
500 .It Ev MASTER_SITE_FREEBSD
505 site when fetching files.
506 .It Ev MASTER_SITE_OVERRIDE
507 Go to this site first for all files.
512 ports tree comes with a mechanism called
514 Thanks to this mechanism, users can select specific options provided by
519 there should be a terse description of available flavors in the
525 port comes with a flavor called
527 This changes the building process so a statically compiled version of
528 the program will be built.
529 To avoid confusion with other packages or flavors,
530 the package name will be extended with a dash-separated list of
531 the selected flavors.
533 In this instance, the corresponding package will be called
534 .Ic screen-4.0.2-static .
536 To see the flavors of a port, use the
539 .Bd -literal -offset indent
543 To build a port with a specific flavor, just pass
545 in the environment of the
548 .Bd -literal -offset indent
549 $ env FLAVOR="static" make package
552 and of course, use the same settings for the subsequent invocations of make:
553 .Bd -literal -offset indent
554 $ env FLAVOR="static" make install
555 $ env FLAVOR="static" make clean
558 More than one flavor may be specified:
559 .Bd -literal -offset indent
560 $ cd /usr/ports/mail/exim
561 $ env FLAVOR="mysql ldap" make package
564 Specifying a flavor that does not exist is an error.
565 Additionally, some ports impose some further restrictions on flavor
566 combinations, when such combinations do not make sense.
568 Lots of ports can be built without X11 requirement and accordingly
573 Flavor settings are not propagated to dependencies.
574 If a specific combination is needed, careful hand-building of the
575 required set of packages is still necessary.
579 ports tree comes with a mechanism called
581 This mechanism is used when a larger package is broken down into
582 several smaller components referred to as subpackages.
586 each subpackage will have a corresponding description in the
587 .Pa pkg/DESCR-subpackage
592 port comes with subpackages called
598 In this instance, the build will yield multiple packages, one
599 corresponding to each subpackage.
600 In the case of our mysql example,
601 the packages will be called
602 .Ic mysql-client-<version> ,
603 .Ic mysql-tests-<version> ,
605 .Ic mysql-server-<version> .
607 To install/deinstall a specific subpackage of a port, you may
609 them manually, or alternatively, you may set
611 in the environment of the
613 command during the install/deinstall phase:
614 .Bd -literal -offset indent
615 $ env SUBPACKAGE="-server" make install
616 $ env SUBPACKAGE="-server" make deinstall
619 These can be changed in the environment, or in
622 They can also be set on make's command line, e.g.,
623 .Ic make VAR_FOO Ns = Ns Dv foo
625 Boolean variables should be set to
627 instead of simply being defined, for uniformity and future compatibility.
629 Variable names starting with
631 are private to the ports infrastructure,
632 should not be changed by the user, and are liable to change without notice.
633 .Bl -tag -width MASTER_SITES
635 Location of the ports tree
639 Where to find/put distfiles, normally
640 .Pa ${PORTSDIR}/distfiles
641 .It Ev PACKAGE_REPOSITORY
644 target; the base directory for the packages tree, normally
645 .Pa ${PORTSDIR}/packages .
646 If this directory exists, the package tree will be (partially) constructed.
647 .It Ev BULK_COOKIES_DIR
648 During bulk package building, used to store cookies for already built
649 packages to avoid rebuilding them, since the actual
650 working directory will already have been cleaned out.
652 .Pa ${PORTSDIR}/bulk/${MACHINE_ARCH} .
653 .It Ev UPDATE_COOKIES_DIR
654 Used to store cookies for package updates, defaults to
655 .Pa ${PORTSDIR}/update/${MACHINE_ARCH} .
656 If set to empty, it will revert to a file under
659 Where to install things in general
663 Primary sites for distribution files if not found locally.
669 recurse to dependencies.
671 Command to use to fetch files.
674 .It Ev FETCH_PACKAGES
679 to install the missing packages from
682 If defined, display verbose output when applying each patch.
684 If defined, only operate on a port if it requires interaction.
686 If defined, only operate on a port if it can be installed 100% automatically.
691 .Ar configure , build ,
696 This way it is ensured that ports do not make any network connections
697 during build or write outside some well defined directories.
698 The filter list is stored in
699 .Pa ${PORTSDIR}/infrastructure/db/systrace.filter .
701 .Sh USING A READ-ONLY PORTS TREE
702 Select read-write partition(s) that can accommodate working directories, the
703 distfiles repository, and the built packages.
706 .Ev PACKAGE_REPOSITORY ,
707 .Ev BULK_COOKIES_DIR ,
708 .Ev UPDATE_COOKIES_DIR ,
716 .Bl -tag -width /usr/ports/xxxxxxxx -compact
718 The default ports directory.
719 .It Pa /usr/ports/Makefile
720 Ports master Makefile.
721 .It Pa /usr/ports/INDEX
723 .It Pa /usr/ports/infrastructure/mk/bsd.port.mk
724 The ports main engine.
725 .It Pa /usr/ports/infrastructure/templates/network.conf.template
726 Network configuration defaults.
727 .It Pa /usr/ports/infrastructure/db/network.conf
728 Local network configuration.
729 .It Pa /usr/ports/infrastructure/db/systrace.filter
730 Filter list for systrace.
731 .It Pa /usr/ports/infrastructure/db/user.list
732 List of users and groups created by ports.
748 .Lk http://www.openbsd.org/faq/ports/ports.html
753 .Lk http://www.openbsd.org/faq/ports/
755 .Nm The Ports Collection
760 by Ejovi Nuwere, with much initial effort by Angelos D. Keromytis.
761 Maintenance passed then to Marco S. Hyman, and then to Christopher Turan.
762 It is currently managed by Marc Espie, Christian Weisgerber,
763 along with a host of others found at ports@openbsd.org.
765 This man page was originated by
766 David O'Brien, from the