Annotation of www/ports.html, Revision 1.107
1.47 naddy 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
1.11 deraadt 2: <html>
1.25 deraadt 3: <head>
1.88 nick 4: <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
1.25 deraadt 5: <meta name="resource-type" content="document">
1.47 naddy 6: <meta name="description" content="The OpenBSD Ports and Packages Collection">
1.25 deraadt 7: <meta name="keywords" content="openbsd,ports">
8: <meta name="distribution" content="global">
1.105 nick 9: <meta name="copyright" content="copyright 1997-2010 by OpenBSD.">
1.27 brad 10: <title>OpenBSD Ports and Packages</title>
1.47 naddy 11: <link rev="made" href="mailto:www@openbsd.org">
1.43 jufi 12: </head>
1.25 deraadt 13:
14: <body text="#000000" bgcolor="#FFFFFF" link="#23238E">
15:
1.88 nick 16: <a href="index.html"><img alt="[OpenBSD]" height="30" width="141" src="images/smalltitle.gif" border="0"></a>
1.30 espie 17:
1.88 nick 18: <h2><font color="#e00000">The Ports & Packages collection</font></h2>
1.25 deraadt 19:
1.47 naddy 20: <hr>
21:
1.88 nick 22: <h3><font color="#0000e0">Index</font></h3>
1.53 naddy 23: <ul>
1.88 nick 24: <li><a href="#Motivation">Motivation</a></li>
25: <li><a href="#Get">Getting Packages</a></li>
26: <li><a href="#stable">Ports and Packages Update for an OpenBSD Release</a></li>
27: <li><a href="#Manage">Managing Installed Packages</a></li>
28: <li><a href="#Use">Using Ports</a></li>
29: <li><a href="#Life">Life Cycle of the Ports Tree</a></li>
30: <li><a href="#X">Ports and the X Window System</a></li>
31: <li><a href="#Example">Example Use of the Ports Tree</a></li>
32: <li><a href="#Advanced">Advanced Usage of the Ports Tree</a></li>
33: <li><a href="#Create">Creating New Ports</a></li>
34: <li><a href="#Lag">When a Port Is Lagging Behind the Mainstream Version</a></li>
35: <li><a href="#Help">Problems and Contacts</a></li>
1.53 naddy 36: </ul>
37:
38: <hr>
39:
1.88 nick 40: <h3><font color="#0000e0"><a name="Motivation">Motivation</a></font></h3>
1.25 deraadt 41:
1.88 nick 42: OpenBSD is a fairly complete system of its own, but still there is a lot
43: of software that one might want to see added. However, there is the problem
44: of where to draw the line as to what to include, as well as the occasional
45: licensing and export restriction problems. As OpenBSD is supposed to be
46: a small stand-alone UNIX-like operating system, some things just can't be
47: shipped with the system.
1.25 deraadt 48:
49: <p>
1.47 naddy 50: <strong><font color="#e00000">
1.98 ian 51: The ports & packages collection does NOT go through the thorough security audit that the OpenBSD
52: base system does.
1.88 nick 53: Although we strive to keep the quality of the packages collection high, we just do not have enough human
54: resources to ensure the same level of robustness and security.
1.31 espie 55: </font></strong>
1.25 deraadt 56:
57: <p>
1.88 nick 58: The port collection, originally borrowed from
1.98 ian 59: <a href="http://www.freebsd.org/">FreeBSD</a> and significantly rewritten, fills this gap.
1.88 nick 60: The concept is to have, for each third-party software, a Makefile that
61: controls
1.25 deraadt 62: <ul>
1.88 nick 63: <li>where to fetch it,
64: <li>how to do the fetch,
65: <li>what it depends upon (if anything),
66: <li>how to alter the sources (if needed),
67: <li>and how to configure, build and install it.
1.25 deraadt 68: </ul>
1.88 nick 69: This information is kept in a directory hierarchy under the
70: /usr/ports directory.
1.31 espie 71:
72: <p>
1.88 nick 73: Packages are the binary equivalent of ports. A compiled port becomes
1.98 ian 74: a package that can be easily installed and registered into the system using
1.63 rohee 75: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=pkg_add&sektion=1&format=html">pkg_add(1)</a>
1.31 espie 76:
77: <p>
1.47 naddy 78: <strong><font color="#e00000">
1.88 nick 79: Packages look like simple <code>.tgz</code> bundles, but they should
80: always be added using
81: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=pkg_add&sektion=1&format=html">pkg_add(1)</a>,
82: as there might be some extra information that only
83: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=pkg_add&sektion=1&format=html">pkg_add(1)</a>
84: knows how to handle.</font></strong>
85: Tip: you can distinguish between packages and <strong>.tgz</strong> bundles
86: using
87: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=pkg_info&sektion=1&format=html">pkg_info(1)</a>.
1.31 espie 88:
1.88 nick 89: <h3><font color="#0000e0"><a name="Get">Getting Packages</a></font></h3>
1.31 espie 90:
1.88 nick 91: A large collection of pre-compiled packages is available for most common
1.98 ian 92: architectures:
1.31 espie 93: <ul>
1.88 nick 94: <li>On the CD-Rom (that you can order <a href="orders.html">here</a>),
95: <li>On the <a href=ftp.html>ftp mirror sites</a>.
1.31 espie 96: </ul>
97:
1.44 espie 98:
1.88 nick 99: Adding a package is as easy as
1.96 landry 100: <code>pkg_add pkgname</code>.
1.88 nick 101: If you are grabbing packages from a single source (a package repository),
102: set PKG_PATH to that repository URL, in order to grab dependencies.
1.31 espie 103:
104: <p>
1.98 ian 105: For instance, to install the Gimp package (and any needed dependencies)
1.105 nick 106: for the 4.7 release on an i386 machine from the ftp site, do:
1.31 espie 107:
108: <pre>
1.105 nick 109: # export PKG_PATH=ftp://ftp.openbsd.org/pub/OpenBSD/4.7/packages/i386/
1.96 landry 110: # pkg_add gimp
1.31 espie 111: </pre>
112:
1.88 nick 113: <h3><font color="#0000e0"><a name="stable">Ports and Packages Update for an OpenBSD Release</a></font></h3>
1.45 espie 114: <p>
1.105 nick 115: There is a <a href="faq/faq5.html#Flavors">stable branch</a> for the
116: ports tree.
117:
1.45 espie 118: <p>
1.105 nick 119: For instance, to grab the stable branch for the 4.7 release:
1.45 espie 120: <pre>
121: $ cd /usr/ports
1.105 nick 122: $ cvs -q -d anoncvs@some.anon.server:/cvs up -r OPENBSD_4_7 -Pd
1.45 espie 123: </pre>
124: <p>
1.105 nick 125: Selected binary packages are also made available.
1.88 nick 126: If you want to receive security announcements, you can subscribe
127: to the ports-security mailing list.
1.105 nick 128:
1.45 espie 129: <p>
1.88 nick 130: Package names are <strong>always</strong> changed in case of a package
131: update, to avoid any risk of confusion between a package from the release
132: and a bug-fixed package.
1.45 espie 133: </p>
134:
1.88 nick 135: <h3><font color="#0000e0"><a name="Manage">Managing Installed Packages</a></font></h3>
1.31 espie 136:
1.88 nick 137: The <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=packages&sektion=7&format=html">packages(7)</a>
138: manual page holds useful information about ways to manage
139: installed packages, solve conflicts (files that already exist) and handle
140: dependencies.
1.31 espie 141: <p>
1.96 landry 142: Starting with OpenBSD 3.9, an update mechanism is provided by
143: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=pkg_add&sektion=1&format=html">pkg_add(1)</a>.
144: To update a package (and its dependencies) you must set PKG_PATH to a
145: repository URL which contains updates, and use
146: <code>pkg_add -ui pkgname</code>.
1.31 espie 147:
1.88 nick 148: <h3><font color="#0000e0"><a name="Use">Using Ports</a></font></h3>
1.31 espie 149:
1.88 nick 150: If a given package does not exist for your architecture, you may still
151: be able to compile the port. Besides, some users will want to compile
152: everything from source for various reasons.
153:
154: <p>
155: You can ftp the release version from the pub/OpenBSD/[version] (where
156: [version] is the release number) directory on any of the
157: <a href=ftp.html>ftp mirror sites</a>.
158: The release versions are the ones we ship on our CDROM, and have gone
159: through more testing than any snapshot.
160: Further information is available in the
161: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=ports&sektion=7&format=html">ports(7)</a> man page.
162:
163: <h3><font color="#0000e0"><a name="Life">Life Cycle of the Ports Tree</a></font></h3>
164:
165: <p>
166: The ports tree, like the rest of OpenBSD, is constantly changing.
167: <p>
168: The current ports tree <strong>may not</strong> be used with the previous
169: release. This is due to changes, typically with the port make process,
170: that require code based upon the OpenBSD-current source tree.
171: <p>The ports tree works as a single entity. Updating a single directory is
172: not guaranteed to work, as package dependencies may force you to update
173: and recompile vast portions of the ports tree.
174: It is strongly suggested that people don't track ports-current unless
175: they're prepared to deal with various problems.
176: <a href=mail.html>Mailing lists</a> such as
177: <code>ports-changes@openbsd.org</code> or
178: <code>tech@openbsd.org</code> will probably be invaluable.
179:
180: <p>You are advised to track ports-stable on a production machine:
181: we will try to keep the stable ports tree up-to-par with respect to
182: problems, and to provide timely binary updates as well.
183:
184: <p>Note that vanishing distfiles is not an issue, as
185: ftp.openbsd.org holds the complete repository. Even changing checksums is
186: not an issue: you can issue the command
1.59 espie 187: <pre>
188: make checksum REFETCH=true
189: </pre>
1.88 nick 190: to make sure you are grabbing the correct distfile for your ports tree.
1.59 espie 191:
1.88 nick 192: For definitions of <i>current</i> and <i>stable</i>, see the
193: <a href="faq/faq5.html#Flavors">OpenBSD's flavors</a>.
1.59 espie 194:
195:
1.88 nick 196: <p>A list of <a href="portsplus/index.html">daily changes</a> to ports
197: and ports-current is available.
1.47 naddy 198:
1.27 brad 199: <p>
1.88 nick 200: The ports-current tree can be retrieved via:
1.25 deraadt 201: <ul>
1.88 nick 202: <li><a href=anoncvs.html>Anonymous CVS</a> (see link). The command is
203: essentially <strong>cvs get ports</strong>.
204: <li>Anonymous ftp from
205: <a href="ftp://ftp.openbsd.org/pub/OpenBSD/snapshots/ports.tar.gz">
206: ftp://ftp.openbsd.org/pub/OpenBSD/snapshots/ports.tar.gz</a>.
207: This archive is updated nightly.
208: <li><a href="cvsup.html">CVSup</a>. See the example for using CVSup in
209: <a href="cvsup.html#checkout">checkout mode</a>.
210: <li>Your web browser using the
211: <a href="http://www.openbsd.org/cgi-bin/cvsweb/ports/">CVS
212: web interface</a>.
1.25 deraadt 213: </ul>
214:
1.88 nick 215: <h3><font color="#0000e0"><a name="X">Ports and the X Window System</a></font></h3>
216: There is some special magic in the OpenBSD X configuration files
217: that allows the ports tree to install imake-based applications under
218: /usr/local.
1.35 espie 219:
1.88 nick 220: <h3><a name="Example"></a><font color="#0000e0">Example Use of the Ports Tree</font></h3>
1.54 lebel 221:
222: <p>
1.88 nick 223: Let's say you managed to get a ports tree and you want to compile and
224: install the archiving utility <strong>unzip</strong>. You should be able to
225: do something like this:
1.31 espie 226:
1.11 deraadt 227: <pre>
1.31 espie 228: % cd /usr/ports/archivers/unzip
229: % su
1.96 landry 230: # make install clean
1.31 espie 231: # exit
1.11 deraadt 232: </pre>
1.25 deraadt 233:
1.88 nick 234: Easy, huh ? Especially considering all that happened in the background:
1.31 espie 235: <ul>
1.88 nick 236: <li>Fetch unzip sources from an ftp site,
237: <li>Check the source archive integrity,
238: <li>Extract the unzip source,
239: <li>Apply OpenBSD specific patches,
240: <li>Configure and build the program,
241: <li>Create a binary package under /usr/ports/packages,
242: <li>Install that package.
1.31 espie 243: </ul>
1.25 deraadt 244:
245: <p>
1.88 nick 246: With OpenBSD 3.0, almost all ports automatically build
247: packages when installing.
1.31 espie 248:
249: <p>
1.88 nick 250: As ports get built, the /usr/ports/distfiles directory gets filled with
251: program sources, and /usr/ports/packages gets filled with binary packages.
252: Users with low connectivity may refer to
253: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=mirroring-ports&sektion=7&format=html">mirroring-ports(7)</a> for
254: an efficient way to grab all distfiles at once. In OpenBSD-current, you
255: can use the script /usr/ports/infrastructure/fetch/clean-old to track
256: old distfiles.
257: Note that the OpenBSD CD only includes the ports tree and selected packages.
258: If you wish to have the distfiles, you will have to get them through an
259: independent way.
260:
261: <h3><font color="#0000e0"><a name="Advanced"></a>Advanced Usage of the Ports Tree</font></h3>
262:
263: <p>
264: Ports tree has many features for the advanced user that make it a valuable
265: tool beyond basic installation. Advanced users may wish to tamper with
266: the makefiles (you should read the
1.63 rohee 267: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=make&sektion=1&format=html">make(1)</a>
1.88 nick 268: manual page first) or set various variables from the make command-line or in
269: <tt>/etc/mk.conf</tt>. These variables are described in detail in the
1.63 rohee 270: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=bsd.port.mk&sektion=5&format=html">bsd.port.mk(5)</a>
1.88 nick 271: manual page, and the porting documents below.
1.55 heko 272: </p>
273:
1.88 nick 274: <h3><font color="#0000e0"><a name="Create">Creating New Ports</a></font></h3>
1.25 deraadt 275: <p>
1.88 nick 276: If you are interested in helping to expand the OpenBSD ports tree
1.106 steven 277: you should first read the <a href="faq/ports/index.html">Porter's Handbook</a>.
1.88 nick 278: That page references the
1.66 jufi 279: <a href="http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/index.html">
280: FreeBSD Porter's Handbook</a>
1.88 nick 281: as well as OpenBSD specific policies and hints.
1.56 heko 282:
1.88 nick 283: <h3><font color="#0000e0"><a name="Lag">When a Port Is Lagging Behind the Mainstream Version</a></font></h3>
1.56 heko 284:
285: <p>
1.88 nick 286: The ports collection is a volunteer project. Sometimes the project simply
287: doesn't have the developer resources to keep everything up-to-date.
288: Developers pretty much pick up what they consider interesting and can
289: test in their environment. Your <a href="goals.html#funding">donations</a>
290: count for what platforms the ports can be tested on.
1.56 heko 291: </p>
292:
293: <p>
1.88 nick 294: Some individual ports may lag behind the mainstream versions because of this.
295: The ports collection may have a version back of a program from January while a new
296: version of the program has been released by its developers in May three months ago.
297: Often this is a conscious decision; the new version may have problems in it on
298: OpenBSD that the maintainer is trying to solve, or that have simply made the
299: application worse than the old version: OpenBSD may have different
300: <a href="goals.html">goals</a> than the mainstream developers in other projects,
301: which sometimes results in features and design or implementation choices
302: that are undesirable from OpenBSD developers' point of view. The update may also be
303: postponed because the new version is not considered a crucial update.
1.56 heko 304: </p>
305:
306: <p>
1.88 nick 307: If you really need a new version of a port, you should ask the <tt>MAINTAINER</tt>
308: of the port to update the port (see <a href="#Help">below</a> on how to find out who
309: the maintainer is); if you can send patches for this, all the better. To create proper
1.106 steven 310: patches, you should refer to the <a href="faq/ports/index.html">documentation on building
1.88 nick 311: ports</a>.
1.56 heko 312: </p>
1.25 deraadt 313:
1.88 nick 314: <h3><font color="#0000e0"><a name="Help">Problems and Contacts</a></font></h3>
1.25 deraadt 315:
316: <p>
1.88 nick 317: If you have trouble with an existing port, please send e-mail to the
318: port maintainer. To see who is the maintainer of the port, type, for
319: example:
1.54 lebel 320: <pre>
321: % cd /usr/ports/archivers/unzip
1.74 xsa 322: % make show=MAINTAINER
1.54 lebel 323: </pre>
1.88 nick 324: Alternatively, if there is no maintainer, or you can't reach
325: him/her, send mail to the OpenBSD
326: ports mailing list, <a href="mailto:ports@openbsd.org">ports@openbsd.org</a>.
327: Please don't use the misc@openbsd.org mailing list for questions about ports.
328: Corrections are always welcome, but in any case do please provide:
1.25 deraadt 329: <ul>
1.88 nick 330: <li>The output of <code>uname -a</code>,
331: <li>Your OpenBSD version, including any patches you may have applied,
332: <li>A complete description of the problem.
1.45 espie 333: </ul>
1.88 nick 334: For ports that don't build correctly, a complete build transcript is almost
335: always required. You can use the portslogger script, found in
336: /usr/ports/infrastructure/build, for this. A sample run of portslogger
337: might be:
1.54 lebel 338:
339: <pre>
340: % cd /usr/ports/archivers/unzip
341: % su
342: # mkdir -p ~/portslogs
1.107 ! jasper 343: # make clean install 2>&1 | /usr/ports/infrastructure/bin/portslogger \
1.54 lebel 344: ~/portslogs
345: </pre>
346:
1.88 nick 347: After this, you should have a logfile of the build in your ~/portslogs directory
348: that you can send to the port maintainer. Also, make sure you are not using
349: any special options in your build, for example in /etc/mk.conf.
1.54 lebel 350:
351: <p>
1.88 nick 352: Alternatively, you can
1.45 espie 353: <ul>
1.88 nick 354: <li>Use <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=script&sektion=1&format=html">script(1)</a> to create a complete build transcript. Don't remove the configure information.
355: <li>Attach the output of <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=pkg_info&sektion=1&format=html">pkg_info(1)</a> if it seems even remotely relevant.
356: <li><a href="http://www.openbsd.org/cgi-bin/man.cgi?query=gcc&sektion=1&format=html">gcc(1)</a> internal compiler errors do ask you to report the bug to
357: the gcc mailing-list. It does save time if you follow their direction, and
358: provide at least the various files produced by <tt>gcc -save-temps</tt>.
1.25 deraadt 359: </ul>
360:
361: <hr>
1.88 nick 362: <a href="index.html"><img height=24 width=24 src=back.gif border=0 alt=OpenBSD></a>
1.47 naddy 363: <a href="mailto:www@openbsd.org">www@openbsd.org</a>
1.107 ! jasper 364: <br><small>$OpenBSD: ports.html,v 1.106 2010/07/29 05:29:30 steven Exp $</small>
1.25 deraadt 365: </body>
1.11 deraadt 366: </html>