sync
[bitrig.git] / share / man / man7 / ports.7
blob99de0a3e7a60b4e602c59cf4c8321c80c1fed806
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.95 2013/06/19 08:59:02 espie Exp $
27 .\" $FreeBSD: ports.7,v 1.7 1998/06/23 04:38:50 hoek Exp $
28 .\"
29 .Dd $Mdocdate: June 19 2013 $
30 .Dt PORTS 7
31 .Os
32 .Sh NAME
33 .Nm ports
34 .Nd contributed applications
35 .Sh DESCRIPTION
36 The
37 .Ox
38 Ports Collection
39 is the infrastructure used to create binary packages for third party
40 applications.
41 .Pp
42 For normal usage refer to
43 .Xr packages 7 ,
44 as most ports produce binary packages which are available from
45 the official CD-ROM, or on a neighborly FTP mirror.
46 .Pp
47 Each port contains any patches necessary to make the original
48 application source code compile and run on
49 .Ox .
50 Compiling an application is as simple as typing
51 .Ic make
52 in the port directory!
53 The
54 .Pa Makefile
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
59 .Ic sudo make install
60 to install the application.
61 .Pp
62 For more information about using ports, see
63 The
64 .Ox
65 Ports System
66 .Pq Lk http://www.openbsd.org/faq/ports/ports.html .
67 For information about creating new ports, see
68 the
69 .Ox
70 Porter's Handbook
71 .Pq Lk http://www.openbsd.org/faq/ports/ .
72 .Pp
73 For a detailed description of the build process, see
74 .Xr bsd.port.mk 5 .
75 .Sh PORTS MASTER MAKEFILE
76 The ports master Makefile, normally located in
77 .Pa /usr/ports/Makefile
78 (but see
79 .Ev PORTSDIR
80 below)
81 offers a few useful targets.
82 .Bl -tag -width configure
83 .It Ar index
84 rebuild the ports complete index,
85 .Pa /usr/ports/INDEX
86 .It Ar mirror-maker
87 see
88 .Xr mirroring-ports 7 ,
89 .It Ar pkglocatedb
90 build a
91 .Xr pkg_mklocatedb 1
92 database file and place it in
93 .Pa ${PORTSDIR}/packages/${MACHINE_ARCH}/ftp ,
94 for use by
95 .Xr locate 1 ,
96 .It Ar print-index
97 display the contents of the index in a user-friendly way,
98 .It Ar search
99 invoked with a key, e.g.,
100 .Ic make search key=foo ,
101 retrieve information relevant to a given port (obsolescent).
104 Starting in
105 .Ox 4.0 ,
106 there is a port,
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
114 One can define
115 .Ev SUBDIRLIST
116 to point to a file that contains a list of
117 .Ev FULLPKGPATHs ,
118 one per line, to build stuff only in some directories.
121 .Pa /usr/ports/INDEX
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
125 .It Va key
126 package name matching the given key,
127 .It Va category
128 port belonging to category,
129 .It Va maintainer
130 port maintained by a given person.
133 For instance, to invoke
134 .Ar clean
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
141 .Xr perlre 1
142 apply.
143 .Sh TARGETS
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
147 ports.
149 The variable
150 .Ev SKIPDIR
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
156 .Xr packages-specs 7
157 .Pc .
158 .Ev SKIPDIR
159 is handled by a
160 .Ic case
161 statement, and so can contain simple wildcards
164 .Xr sh 1
165 .Dq File name patterns
166 .Pc ,
167 e.g., SKIPDIR='editors/openoffice*' .
169 The variable
170 .Ev STARTDIR
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.
176 The variable
177 .Ev STARTAFTER
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
184 .Ev REPORT_PROBLEM
185 is executed.
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
194 is non empty, then
195 .Ev REPORT_PROBLEM
196 will default to:
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}
204 and proceed.
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 ,
215 .Ar run-dir-depends
217 .Ar readmes .
219 Target names starting with
220 .Sq _
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.
226 That is,
227 .Ar build
228 will be run
229 .Pq if necessary
231 .Ar install ,
232 and so on all the way to
233 .Ar fetch .
234 In typical use, one will only run
235 .Ar install
236 explicitly (as normal user, with
237 .Ev SUDO
238 defined in
239 .Pa /etc/mk.conf ) ,
241 .Ar build
242 (as user), then
243 .Ar install
244 (as root).
245 .Bl -tag -width configure
246 .It Ar fetch
247 Fetch all of the files needed to build this port from the site(s)
248 listed in
249 .Ev MASTER_SITES .
251 .Ev FETCH_CMD
253 .Ev MASTER_SITE_OVERRIDE .
255 .Xr dpb
256 with option
257 .Fl F
258 to quickly fetch distfiles for a subtree.
259 .It Ar checksum
260 Verify that the fetched distfile matches the one the port was tested against.
261 Defining
262 .Ev NO_CHECKSUM
264 .Dv Yes
265 will skip this step.
266 Sometimes, distfiles change without warning.
267 The main
269 mirror should still hold a copy of old distfiles, indexed by checksum.
270 Using
271 .Bd -literal -offset indent
272 $ make checksum REFETCH=true
275 will try to get a set of distfiles that match the recorded checksum.
276 .It Ar prepare
277 Install
278 any build dependencies of the current port.
279 Defining
280 .Ev NO_DEPENDS
282 .Dv Yes
283 will skip this step.
284 .It Ar extract
285 Expand the distfile into a work directory.
286 .It Ar patch
287 Apply any patches that are necessary for the port.
288 .It Ar configure
289 Configure the port.
290 Some ports will ask questions during this stage.
292 .Ev INTERACTIVE
294 .Ev BATCH .
295 .It Ar build
296 Build the port.
297 This is the same as calling the
298 .Ar all
299 target.
300 .It Ar fake
301 Pretend to install the port under a subdirectory of the work directory.
302 .It Ar package
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
306 .Xr pkg_add 1 .
307 .It Ar install
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.
315 .It Ar clean
316 Remove the expanded source code.
317 This does not recurse to dependencies unless
318 .Ev CLEANDEPENDS
319 is defined to
320 .Dv Yes .
321 .It Ar distclean
322 Remove the port's distfile(s).
323 This does not recurse to dependencies.
324 .It Ar regress
325 Runs the ports regression tests.
326 Usually needs a completed build.
327 .It Ar reinstall
328 Use this to restore a port after using
329 .Xr pkg_delete 1 .
330 .It Ar update
331 Alternative target to
332 .Ar install .
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
336 belongs to.
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
342 .Ev HOMEPAGE .
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 .
349 Defining
350 .Ev LOCKDIR
351 will point them elsewhere, or disable the mechanism if set to an empty value.
353 All locks will be stored in
354 .Pa ${LOCKDIR} .
355 .Ev LOCK_CMD
356 should be used to acquire a lock, and
357 .Ev UNLOCK_CMD
358 should be used to release it.
360 Locks are named
361 .Pa ${LOCKDIR}/${FULLPKGNAME}.lock ,
363 .Pa ${LOCKDIR}/${DISTFILE}.lock
364 for distfiles fetching.
366 The default values of
367 .Ev LOCK_CMD
369 .Ev UNLOCK_CMD
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
376 $ make build
379 will acquire the lock, run the port
380 through
381 .Ar fetch ,
382 .Ar checksum ,
383 .Ar extract ,
384 .Ar patch ,
385 .Ar configure ,
386 .Ar build ,
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
393 .Ev LOCK_CMD .
395 Starting with
396 .Ox 4.3 ,
397 the infrastructure supports manual locking: the targets
398 .Ar lock
400 .Ar unlock
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
406 given port.
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.
411 .Ar update
412 target will replace an installed package using
413 .Xr pkg_add 1
414 in replacement mode.
416 .Ev FORCE_UPDATE
417 is set to
418 .Dv Yes ,
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
430 ones.
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
436 .Xr dpb 1 ,
437 a tool located inside the ports tree proper
439 normally as
440 .Pa /usr/ports/infrastructure/bin/dpb
441 .Pc .
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
446 .Bl -bullet
448 The default limits in
449 .Xr login.conf 5
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
454 .Ar datasize
455 over 1G.
457 cluster builds should have shared
458 .Ev PORTSDIR
459 and local
460 .Ev WRKOBJDIR .
461 If possible, dedicated
462 .Ev WRKOBJDIR
463 partitions mounted
464 .Sq noatime,async
465 will help.
467 as far as possible, the log directory should be local to the machine running
468 .Xr dpb 1 .
470 a full bulk will fetch over 20G of distfiles, create over 17G of packages.
471 The largest work directories are about 10G each.
473 Take notice of
474 .Ev CHECKSUM_PACKAGES
476 .Xr bsd.port.mk 5 .
477 This can be set to
478 .Sq ftp
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
492 and edit it.
493 .Bl -tag -width MASTER_SITES
494 .It Ev MASTER_SITE_OPENBSD
495 If set to
496 .Dv Yes ,
497 include the master
499 site when fetching files.
500 .It Ev MASTER_SITE_FREEBSD
501 If set to
502 .Dv Yes ,
503 include the master
505 site when fetching files.
506 .It Ev MASTER_SITE_OVERRIDE
507 Go to this site first for all files.
509 .Sh FLAVORS
512 ports tree comes with a mechanism called
513 .Ic FLAVORS .
514 Thanks to this mechanism, users can select specific options provided by
515 a given port.
517 If a port is
518 .Qq flavored ,
519 there should be a terse description of available flavors in the
520 .Pa pkg/DESCR
521 file.
523 For example, the
524 .Pa misc/screen
525 port comes with a flavor called
526 .Ic static .
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
537 .Ar show
538 target:
539 .Bd -literal -offset indent
540 $ make show=FLAVORS
543 To build a port with a specific flavor, just pass
544 .Ev FLAVOR
545 in the environment of the
546 .Xr make 1
547 command:
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
569 have a
570 .Ic no_x11
571 flavor.
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.
576 .Sh MULTI_PACKAGES
579 ports tree comes with a mechanism called
580 .Ic MULTI_PACKAGES .
581 This mechanism is used when a larger package is broken down into
582 several smaller components referred to as subpackages.
584 If a port is
585 .Qq subpackaged ,
586 each subpackage will have a corresponding description in the
587 .Pa pkg/DESCR-subpackage
588 file.
590 For example, the
591 .Pa database/mysql
592 port comes with subpackages called
593 .Ic -main ,
594 .Ic -tests
596 .Ic -server .
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
608 .Xr pkg_add 1
609 them manually, or alternatively, you may set
610 .Ev SUBPACKAGE
611 in the environment of the
612 .Xr make 1
613 command during the install/deinstall phase:
614 .Bd -literal -offset indent
615 $ env SUBPACKAGE="-server" make install
616 $ env SUBPACKAGE="-server" make deinstall
618 .Sh PORT VARIABLES
619 These can be changed in the environment, or in
620 .Pa /etc/mk.conf
621 for persistence.
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
626 .Dv Yes
627 instead of simply being defined, for uniformity and future compatibility.
629 Variable names starting with
630 .Sq _
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
634 .It Ev PORTSDIR
635 Location of the ports tree
636 (usually
637 .Pa /usr/ports ) .
638 .It Ev DISTDIR
639 Where to find/put distfiles, normally
640 .Pa ${PORTSDIR}/distfiles
641 .It Ev PACKAGE_REPOSITORY
642 Used only for the
643 .Ar package
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.
651 Defaults to
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
657 .Pa ${WRKDIR} .
658 .It Ev LOCALBASE
659 Where to install things in general
660 (usually
661 .Pa /usr/local ) .
662 .It Ev MASTER_SITES
663 Primary sites for distribution files if not found locally.
664 .It Ev CLEANDEPENDS
665 If set to
666 .Dv Yes ,
668 .Ar clean
669 recurse to dependencies.
670 .It Ev FETCH_CMD
671 Command to use to fetch files.
672 Normally
673 .Xr ftp 1 .
674 .It Ev FETCH_PACKAGES
675 If set to
676 .Dv Yes ,
677 try to use
678 .Xr pkg_add 1
679 to install the missing packages from
680 .Ev PKG_PATH .
681 .It Ev PATCH_DEBUG
682 If defined, display verbose output when applying each patch.
683 .It Ev INTERACTIVE
684 If defined, only operate on a port if it requires interaction.
685 .It Ev BATCH
686 If defined, only operate on a port if it can be installed 100% automatically.
687 .It Ev USE_SYSTRACE
688 Set to
689 .Dv Yes
690 to protect the
691 .Ar configure , build ,
693 .Ar fake
694 targets with
695 .Xr systrace 1 .
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.
705 .Ev WRKOBJDIR ,
706 .Ev PACKAGE_REPOSITORY ,
707 .Ev BULK_COOKIES_DIR ,
708 .Ev UPDATE_COOKIES_DIR ,
709 .Ev DISTDIR ,
711 .Ev PLIST_DB
713 .Pa /etc/mk.conf
714 accordingly.
715 .Sh FILES
716 .Bl -tag -width /usr/ports/xxxxxxxx -compact
717 .It Pa /usr/ports
718 The default ports directory.
719 .It Pa /usr/ports/Makefile
720 Ports master Makefile.
721 .It Pa /usr/ports/INDEX
722 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.
734 .Sh SEE ALSO
735 .Xr dpb 1 ,
736 .Xr make 1 ,
737 .Xr pkg_add 1 ,
738 .Xr pkg_create 1 ,
739 .Xr pkg_delete 1 ,
740 .Xr pkg_info 1 ,
741 .Xr bsd.port.mk 5 ,
742 .Xr port-modules 5 ,
743 .Xr packages 7
747 Ports System:
748 .Lk http://www.openbsd.org/faq/ports/ports.html
752 Porter's Handbook:
753 .Lk http://www.openbsd.org/faq/ports/
754 .Sh HISTORY
755 .Nm The Ports Collection
756 appeared in
757 .Fx 1.0 .
758 It was introduced in
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.
764 .Sh AUTHORS
765 This man page was originated by
766 David O'Brien, from the
768 project.