&os; and FreeBSD-5 section cleanup.
[dragonfly.git] / en / books / handbook / ports / chapter.sgml
CommitLineData
8abd622e
JS
1<!--
2 The FreeBSD Documentation Project
3
4 $FreeBSD: doc/en_US.ISO8859-1/books/handbook/ports/chapter.sgml,v 1.218 2004/05/06 11:37:25 den Exp $
bad269a5 5 $DragonFly: doc/en/books/handbook/ports/Attic/chapter.sgml,v 1.2 2004/07/19 15:37:52 justin Exp $
8abd622e
JS
6-->
7
8<chapter id="ports">
9 <title>Installing Applications: Packages and Ports</title>
10
11 <sect1 id="ports-synopsis">
12 <title>Synopsis</title>
13
14 <indexterm><primary>ports</primary></indexterm>
15 <indexterm><primary>packages</primary></indexterm>
bad269a5 16 <para>&os; is bundled with a rich collection of system tools as
8abd622e
JS
17 part of the base system. However, there is only so much one can
18 do before needing to install an additional third-party
bad269a5 19 application to get real work done. &os; provides two
8abd622e
JS
20 complementary technologies for installing third party software
21 on your system: the FreeBSD Ports Collection, and binary
22 software packages. Either system may be used to install the
23 newest version of your favorite applications from local media or
24 straight off the network.</para>
bad269a5
JS
25
26 <note>
27 <para>&os; currently uses the FreeBSD Ports Collection; it works in
28 most cases with no problems. In the relatively rare case that a port
29 will not build under &os;, an 'override' is created in a file
30 collection called dfports, described here. Since the ports and
31 packages systems are inherited from FreeBSD, references to both
32 &os; and FreeBSD mix throughout this chapter.</para>
33
34 <para>It's expected a new system that renders this borrowed system obsolete
35 will be built before &os; reaches version 2.0.</para>
36 </note>
37
8abd622e
JS
38 <para>After reading this chapter, you will know:</para>
39
40 <itemizedlist>
41 <listitem>
42 <para>How to install third-party binary software packages.</para>
43 </listitem>
44 <listitem>
45 <para>How to build third-party software from the ports
46 collection.</para>
47 </listitem>
48 <listitem>
bad269a5
JS
49 <para>Where to find &os;-specific changes to ports.</para>
50 </listitem>
51 <listitem>
8abd622e
JS
52 <para>How to remove previously installed packages or ports.</para>
53 </listitem>
54 <listitem>
55 <para>How to override the default values that the ports
56 collection uses.</para>
57 </listitem>
58 <listitem>
59 <para>How to upgrade your ports.</para>
60 </listitem>
bad269a5 61
8abd622e
JS
62 </itemizedlist>
63 </sect1>
64
65 <sect1 id="ports-overview">
66 <title>Overview of Software Installation</title>
67
68 <para>If you have used a &unix; system before you will know that the typical
69 procedure for installing third party software goes something like
70 this:</para>
71
72 <procedure>
73 <step>
74 <para>Download the software, which might be distributed in source code
75 format, or as a binary.</para>
76 </step>
77
78 <step>
79 <para>Unpack the software from its distribution format (typically a
80 tarball compressed with &man.compress.1;, &man.gzip.1;, or &man.bzip2.1;).</para>
81 </step>
82
83 <step>
84 <para>Locate the documentation (perhaps an <filename>INSTALL</filename> or <filename>README</filename>
85 file, or some files in a <filename>doc/</filename> subdirectory) and
86 read up on how to install the software.</para>
87 </step>
88
89 <step>
90 <para>If the software was distributed in source format, compile it.
91 This may involve editing a <filename>Makefile</filename>, or
92 running a <command>configure</command> script, and other work.</para>
93 </step>
94
95 <step>
96 <para>Test and install the software.</para>
97 </step>
98 </procedure>
99
100 <para>And that is only if everything goes well. If you are installing a
bad269a5 101 software package that was not deliberately ported to &os; you may
8abd622e
JS
102 even have to go in and edit the code to make it work properly.</para>
103
104 <para>Should you want to, you can continue to install software the
bad269a5
JS
105 <quote>traditional</quote> way with &os;. However, &os;
106 provides two technologies, inherited from FreeBSD, which can save
107 you a lot of effort: packages and ports. At the time of
108 writing, over &os.numports; third party applications have
109 been made available in this way.</para>
8abd622e 110
bad269a5 111 <para>For any given application, the &os; package for that
8abd622e
JS
112 application is a single file which you must download. The
113 package contains pre-compiled copies of all the commands for the
114 application, as well as any configuration files or
115 documentation. A downloaded package file can be manipulated
bad269a5 116 with &os; package management commands, such as
8abd622e
JS
117 &man.pkg.add.1;, &man.pkg.delete.1;, &man.pkg.info.1;, and so
118 on. Installing a new application can be carried out with a single
119 command.</para>
120
bad269a5 121 <para>A 'port' for an application is a collection of files
8abd622e
JS
122 designed to automate the process of compiling an application
123 from source code.</para>
124
125 <para>Remember that there are a number of steps you would normally
126 carry out if you compiled a program yourself (downloading,
127 unpacking, patching, compiling, installing). The files that
128 make up a port contain all the necessary information to allow
129 the system to do this for you. You run a handful of simple
130 commands and the source code for the application is
131 automatically downloaded, extracted, patched, compiled, and
132 installed for you.</para>
133
134 <para>In fact, the ports system can also be used to generate packages
135 which can later be manipulated with <command>pkg_add</command>
136 and the other package management commands that will be introduced
137 shortly.</para>
138
139 <para>Both packages and ports understand
140 <emphasis>dependencies</emphasis>. Suppose you want to install
141 an application that depends on a specific library being
142 installed. Both the application and the library have been made
bad269a5 143 available as ports and packages. If you use the
8abd622e
JS
144 <command>pkg_add</command> command or the ports system to add
145 the application, both will notice that the library has not been
146 installed, and automatically install the library first.</para>
147
148 <para>Given that the two technologies are quite similar, you might
bad269a5 149 be wondering why &os; bothers with both. Packages and ports
8abd622e
JS
150 both have their own strengths, and which one you use will depend
151 on your own preference.</para>
152
153 <itemizedlist>
154 <title>Package Benefits</title>
155
156 <listitem>
157 <para>A compressed package tarball is typically smaller than
158 the compressed tarball containing the source code for the
159 application.</para>
160 </listitem>
161
162 <listitem>
163 <para>Packages do not require any additional compilation. For
164 large applications, such as
165 <application>Mozilla</application>,
166 <application>KDE</application>, or
167 <application>GNOME</application> this can be important,
168 particularly if you are on a slow system.</para>
169 </listitem>
170
171 <listitem>
172 <para>Packages do not require any understanding of the process
bad269a5 173 involved in compiling software on &os;.</para>
8abd622e
JS
174 </listitem>
175 </itemizedlist>
176
177 <itemizedlist>
178 <title>Ports Benefits</title>
179
180 <listitem>
181 <para>Packages are normally compiled with conservative options,
182 because they have to run on the maximum number of systems. By
183 installing from the port, you can tweak the compilation options to
184 (for example) generate code that is specific to a Pentium
185 IV or Athlon processor.</para>
186 </listitem>
187
188 <listitem>
189 <para>Some applications have compile time options relating to
190 what they can and cannot do. For example,
191 <application>Apache</application> can be configured with a
192 wide variety of different built-in options. By building
193 from the port you do not have to accept the default options,
194 and can set them yourself.</para>
195
196 <para>In some cases, multiple packages will exist for the same
197 application to specify certain settings. For example,
198 <application>Ghostscript</application> is available as a
199 <filename>ghostscript</filename> package and a
200 <filename>ghostscript-nox11</filename> package, depending on
201 whether or not you have installed an X11 server. This sort
202 of rough tweaking is possible with packages, but rapidly
203 becomes impossible if an application has more than one or
204 two different compile time options.</para>
205 </listitem>
206
207 <listitem>
208 <para>The licensing conditions of some software distributions forbid
209 binary distribution. They must be distributed as source
210 code.</para>
211 </listitem>
212
213 <listitem>
bad269a5
JS
214 <para>Some people do not trust binary distributions. With source
215 code, it is possible to check for any vulnerabilities built into the
216 program before installing it to an otherwise secure system. Few
217 people perform this much review, however.</para>
8abd622e
JS
218 </listitem>
219
220 <listitem>
221 <para>If you have local patches, you will need the source in order to
222 apply them.</para>
223 </listitem>
224
225 <listitem>
226 <para>Some people like having code around, so they can read it
227 if they get bored, hack it, borrow from it (license
228 permitting, of course), and so on.</para>
229 </listitem>
230 </itemizedlist>
231
232 <para>To keep track of updated ports, subscribe to the
bad269a5
JS
233 &a.ports; and the &a.ports-bugs;. It's also useful to watch the
234 &a.bugs.name as errors with ports on DragonFly should be reported
235 there.</para>
8abd622e
JS
236
237 <warning>
238 <para>Before installing any application, you should check <ulink
239 url="http://vuxml.freebsd.org/"></ulink> for security issues
240 related to your application.</para>
241
242 <para>You can also install <filename
243 role="package">security/portaudit</filename> which will
244 automatically check all installed applications for known
245 vulnerabilities, a check will be also performed before any port
246 build. Meanwhile, you can use the command <command>portaudit
247 -F -a</command> after you have installed some
248 packages.</para>
249 </warning>
250
251 <para>The remainder of this chapter will explain how to use
252 packages and ports to install and manage third party software on
bad269a5 253 &os;.</para>
8abd622e
JS
254 </sect1>
255
256 <sect1 id="ports-finding-applications">
257 <title>Finding Your Application</title>
258
259 <para>Before you can install any applications you need to know what you
260 want, and what the application is called.</para>
261
bad269a5 262 <para>&os;'s list of available applications is growing all the
8abd622e
JS
263 time. Fortunately, there are a number of ways to find what you
264 want:</para>
265
266 <itemizedlist>
267 <listitem>
268 <para>The FreeBSD web site maintains an up-to-date searchable
269 list of all the available applications, at <ulink
270 url="&url.main;/ports/index.html">http://www.FreeBSD.org/ports/</ulink>.
271 The ports are divided into categories, and you may either
272 search for an application by name (if you know it), or see
273 all the applications available in a category.</para>
274 </listitem>
275
276 <indexterm><primary>FreshPorts</primary></indexterm>
277
278 <listitem>
279 <para>Dan Langille maintains FreshPorts, at <ulink
280 url="http://www.FreshPorts.org/"></ulink>. FreshPorts
281 tracks changes to the applications in the ports tree as they
282 happen, allows you to <quote>watch</quote> one or more
283 ports, and can send you email when they are updated.</para>
284 </listitem>
285
286 <indexterm><primary>FreshMeat</primary></indexterm>
287
288 <listitem>
289 <para>If you do not know the name of the application you want,
290 try using a site like FreshMeat (<ulink
291 url="http://www.freshmeat.net/"></ulink>) to find an
292 application, then check back at the FreeBSD site to see if
293 the application has been ported yet.</para>
294 </listitem>
295 </itemizedlist>
296 </sect1>
297
298 <sect1 id="packages-using">
299 <sect1info>
300 <authorgroup>
301 <author>
302 <firstname>Chern</firstname>
303 <surname>Lee</surname>
304 <contrib>Contributed by </contrib>
305 </author>
306 </authorgroup>
307 <!-- 30 Mar 2001 -->
308 </sect1info>
309
310 <title>Using the Packages System</title>
311
312 <sect2>
313 <title>Installing a Package</title>
314 <indexterm>
315 <primary>packages</primary>
316 <secondary>installing</secondary>
317 </indexterm>
318
319 <indexterm>
320 <primary><command>pkg_add</command></primary>
321 </indexterm>
322 <para>You can use the &man.pkg.add.1; utility to install a
323 FreeBSD software package from a local file or from a server on
324 the network.</para>
325
326 <example>
327 <title>Downloading a Package Manually and Installing It Locally</title>
328
329 <screen>&prompt.root; <userinput>ftp -a <replaceable>ftp2.FreeBSD.org</replaceable></userinput>
330Connected to ftp2.FreeBSD.org.
331220 ftp2.FreeBSD.org FTP server (Version 6.00LS) ready.
332331 Guest login ok, send your email address as password.
333230-
334230- This machine is in Vienna, VA, USA, hosted by Verio.
335230- Questions? E-mail freebsd@vienna.verio.net.
336230-
337230-
338230 Guest login ok, access restrictions apply.
339Remote system type is UNIX.
340Using binary mode to transfer files.
341<prompt>ftp></prompt> <userinput>cd /pub/FreeBSD/ports/packages/sysutils/</userinput>
342250 CWD command successful.
343<prompt>ftp></prompt> <userinput>get lsof-4.56.4.tgz</userinput>
344local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz
345200 PORT command successful.
346150 Opening BINARY mode data connection for 'lsof-4.56.4.tgz' (92375 bytes).
347100% |**************************************************| 92375 00:00 ETA
348226 Transfer complete.
34992375 bytes received in 5.60 seconds (16.11 KB/s)
350<prompt>ftp></prompt> <userinput>exit</userinput>
351&prompt.root; <userinput>pkg_add <replaceable>lsof-4.56.4.tgz</replaceable></userinput></screen>
352 </example>
353
bad269a5
JS
354 <para>If you do not have a source of local packages
355 then it will probably be easier to use the
8abd622e
JS
356 <option>-r</option> option to &man.pkg.add.1;. This will
357 cause the utility to automatically determine the correct
358 object format and release and then fetch and install the
359 package from an FTP site.
360 </para>
361
362 <indexterm>
363 <primary><command>pkg_add</command></primary></indexterm>
364 <screen>&prompt.root; <userinput>pkg_add -r <replaceable>lsof</replaceable></userinput></screen>
365
366 <para>The example above would download the correct package and
367 add it without any further user intervention.
368 If you want to specify an alternative &os; Packages Mirror,
369 instead of the main distribution site, you have to set
370 <envar>PACKAGESITE</envar> accordingly, to
371 override the default settings. &man.pkg.add.1;
372 uses &man.fetch.3; to download the files, which honors various
373 environment variables, including
374 <envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>, and
375 <envar>FTP_PASSWORD</envar>. You may need to set one or more
376 of these if you are behind a firewall, or need to use an
377 FTP/HTTP proxy. See &man.fetch.3; for the complete list.
378 Note that in the example above
379 <literal>lsof</literal> is used instead of
380 <literal>lsof-4.56.4</literal>. When the remote fetching
381 feature is used, the version number of the package must be
382 removed. &man.pkg.add.1; will automatically fetch the latest
383 version of the application.</para>
384
385 <para>Package files are distributed in <filename>.tgz</filename>
bad269a5
JS
386 and <filename>.tbz</filename> formats. You can find them at
387 the default location <ulink
388 url="ftp://goBSD.com//packages/"></ulink>,
389 among other sites. The layout of the packages is similar
390 to that of the <filename>/usr/ports</filename> tree.
391 Each category has its own directory, and every package can
392 be found within the <filename>All</filename> directory.
8abd622e
JS
393 </para>
394
395 <para>The directory structure of the package system matches the
396 ports layout; they work with each other to form the entire
397 package/port system.
398 </para>
399
400 </sect2>
401
402 <sect2>
403 <title>Managing Packages</title>
404
405 <indexterm>
406 <primary>packages</primary>
407 <secondary>managing</secondary>
408 </indexterm>
409 <para>&man.pkg.info.1; is a utility that lists and describes
410 the various packages installed.
411 </para>
412
413 <indexterm>
414 <primary><command>pkg_info</command></primary>
415 </indexterm>
416 <screen>&prompt.root; <userinput>pkg_info</userinput>
417cvsup-16.1 A general network file distribution system optimized for CV
418docbook-1.2 Meta-port for the different versions of the DocBook DTD
419...</screen>
420 <para>&man.pkg.version.1; is a utility that summarizes the
421 versions of all installed packages. It compares the package
422 version to the current version found in the ports tree.
423 </para>
424 <indexterm>
425 <primary><command>pkg_version</command></primary>
426 </indexterm>
427 <screen>&prompt.root; <userinput>pkg_version</userinput>
428cvsup =
429docbook =
430...</screen>
431
432 <para>The symbols in the second column indicate the relative age
433 of the installed version and the version available in the
434 local ports tree.</para>
435
436 <informaltable frame="none">
437 <tgroup cols="2">
438 <thead>
439 <row>
440 <entry>Symbol</entry>
441 <entry>Meaning</entry>
442 </row>
443 </thead>
444
445 <tbody>
446 <row>
447 <entry>=</entry> <entry>The version of the
448 installed package matches the one found in the
449 local ports tree.</entry>
450 </row>
451
452 <row><entry>&lt;</entry>
453 <entry>The installed version is older than the one available
454 in the ports tree.</entry>
455 </row>
456
457 <row><entry>&gt;</entry><entry>The installed version is newer
458 than the one found in the local ports tree. (The local ports
459 tree is probably out of date.)</entry></row>
460
461 <row><entry>?</entry><entry>The installed package cannot be
462 found in the ports index. (This can happen, for instance, if an
463 installed port is removed from the ports collection or
464 renamed.)</entry></row>
465
466 <row><entry>*</entry><entry>There are multiple versions of the
467 package.</entry></row>
468
469 </tbody>
470 </tgroup>
471 </informaltable>
472 </sect2>
473
474 <sect2>
475 <title>Deleting a Package</title>
476 <indexterm>
477 <primary><command>pkg_delete</command></primary>
478 </indexterm>
479 <indexterm>
480 <primary>packages</primary>
481 <secondary>deleting</secondary>
482 </indexterm>
483 <para>To remove a previously installed software package, use the
484 &man.pkg.delete.1; utility.
485 </para>
486
487 <screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat-1.7.1</replaceable></userinput></screen>
488 </sect2>
489
490 <sect2>
491 <title>Miscellaneous</title>
492 <para>All package information is stored within the
493 <filename>/var/db/pkg</filename> directory. The installed
494 file list and descriptions of each package can be found within
495 files in this directory.
496 </para>
497 </sect2>
498 </sect1>
499
500 <sect1 id="ports-using">
501 <title>Using the Ports Collection</title>
502
503 <para>The following sections provide basic instructions on using the
504 ports collection to install or remove programs from your
505 system.</para>
506
507 <sect2 id="ports-tree">
508 <title>Obtaining the Ports Collection</title>
509
510 <para>Before you can install ports, you must first obtain the
511 ports collection&mdash;which is essentially a set of
512 <filename>Makefiles</filename>, patches, and description files
bad269a5
JS
513 placed in <filename>/usr/ports</filename>. You also must obtain
514 the dfports collection, which contains overrides for any
515 FreeBSD ports that do not compile "out of the box: on &os;.
8abd622e
JS
516 </para>
517
bad269a5 518 <para>The primary method to obtain and keep your ports
8abd622e
JS
519 collection up to date is by using
520 <application>CVSup</application>. Look at the ports
521 <application>CVSup</application> file,
bad269a5 522 <filename>/usr/share/examples/cvsup/FreeBSD-ports-supfile</filename>.
8abd622e
JS
523 See <link linkend="cvsup">Using CVSup</link> (<xref
524 linkend="cvsup">) for more information on using
525 <application>CVSup</application> and this file.</para>
526
527 <procedure>
528 <title>CVSup Method</title>
529
530 <para>This is a quick method for getting the ports collection
531 using <application>CVSup</application>. If you want to keep
532 your ports tree up to date, or learn more about
533 <application>CVSup</application>, read the previously
534 mentioned sections.</para>
535
536 <step>
537 <para>Install the <filename
538 role="package">net/cvsup</filename> port. See <link
539 linkend="cvsup-install">CVSup Installation</link> (<xref
bad269a5
JS
540 linkend="cvsup-install">) for more details.
541 <application>CVSup</application> is installed by default;
542 this will already be present on a &os; system unless
543 manually removed during installation.</para>
8abd622e
JS
544 </step>
545
546 <step>
547 <para>As <username>root</username>, copy
bad269a5 548 <filename>/usr/share/examples/cvsup/FreeBSD-ports-supfile</filename>
8abd622e
JS
549 to a new location, such as <filename>/root</filename> or your
550 home directory.</para>
551 </step>
552
553 <step>
bad269a5 554 <para>Edit <filename>FreeBSD-ports-supfile</filename>.</para>
8abd622e
JS
555 </step>
556
557 <step>
558 <para>Change <replaceable>CHANGE_THIS.FreeBSD.org</replaceable> to a
559 <application>CVSup</application> server near you. See <link
560 linkend="cvsup-mirrors">CVSup Mirrors</link> (<xref
561 linkend="cvsup-mirrors">) for a complete listing of mirror
562 sites.</para>
563 </step>
564
565 <step>
566 <para>Run <command>cvsup</command>:</para>
567
bad269a5 568 <screen>&prompt.root; <userinput>cvsup -g -L 2 <replaceable>/root/FreeBSD-ports-supfile</replaceable></userinput></screen>
8abd622e
JS
569 </step>
570
571 <step>
bad269a5
JS
572 <para>To pull in dfports, run <command>cvsup</command>:</para>
573
574 <screen>&prompt.root; <userinput>cvsup -g -L 2 <replaceable>/usr/share/examples/cvsup/DragonFly-dfports-supfile</replaceable></userinput></screen>
8abd622e 575 </step>
bad269a5
JS
576
577 <step>
578 <para>Running these 2 commands later will download and apply all
579 the recent changes to your ports and dfports collections.
580 </para>
581 </step>
582
8abd622e
JS
583 </procedure>
584 </sect2>
585
586 <sect2 id="ports-skeleton">
587 <title>Installing Ports</title>
588
589 <indexterm>
590 <primary>ports</primary>
591 <secondary>installing</secondary>
592 </indexterm>
593 <para>The first thing that should be explained when it comes to
594 the ports collection is what is actually meant by a
595 <quote>skeleton</quote>. In a nutshell, a port skeleton is a
bad269a5 596 minimal set of files that tell your &os; system how to
8abd622e
JS
597 cleanly compile and install a program. Each port skeleton
598 includes:</para>
599
600 <itemizedlist>
601 <listitem>
602 <para>A <filename>Makefile</filename>. The
603 <filename>Makefile</filename> contains various statements
604 that specify how the application should be compiled and
605 where it should be installed on your system.</para>
606 </listitem>
607
608 <listitem>
609 <para>A <filename>distinfo</filename> file. This file
610 contains information about the files that must be
611 downloaded to build the port and their checksums, to
612 verify that files have not been corrupted during the
613 download using &man.md5.1;.</para>
614 </listitem>
615
616 <listitem>
617 <para>A <filename>files</filename> directory. This
618 directory contains patches to make the program compile and
bad269a5 619 install on your &os; system. Patches are basically
8abd622e
JS
620 small files that specify changes to particular files.
621 They are in plain text format, and basically say
622 <quote>Remove line 10</quote> or <quote>Change line 26 to
623 this ...</quote>. Patches are also known as
624 <quote>diffs</quote> because they are generated by the
625 &man.diff.1; program.</para>
626
627 <para>This directory may also contain other files used to build
628 the port.</para>
629 </listitem>
630
631 <listitem>
632 <para>A <filename>pkg-descr</filename> file. This is a more
633 detailed, often multiple-line, description of the program.</para>
634 </listitem>
635
636 <listitem>
637 <para>A <filename>pkg-plist</filename> file. This is a list of all
638 the files that will be installed by the port. It also tells the
639 ports system what files to remove upon deinstallation.</para>
640 </listitem>
641 </itemizedlist>
642
643 <para>Some ports have other files, such as
644 <filename>pkg-message</filename>. The ports system uses these
645 files to handle special situations. If you want more details
bad269a5
JS
646 on these files, and on ports in general, check out the
647 FreeBSD Porter's Handbook, available at the <ulink
648 url="http://www.freebsd.org/">FreeBSD website</ulink>.</para>
8abd622e
JS
649
650 <para>Now that you have enough background information to know
651 what the ports collection is used for, you are ready to
652 install your first port. There are two ways this can be done,
653 and each is explained below.</para>
654
655 <para>Before we get into that, however, you will need to choose a
656 port to install. There are a few ways to do this, with the
657 easiest method being the <ulink
bad269a5 658 url="http://www.freebsd.org/ports/index.html">ports listing on the FreeBSD
8abd622e
JS
659 web site</ulink>. You can browse through the ports listed there
660 or use the search function on the site. Each port also includes
661 a description so you can read a bit about each port before
662 deciding to install it.</para>
663
664 <para>Another method is to use the &man.whereis.1; command.
665 Simply type <command>whereis
666 <replaceable>file</replaceable></command>, where
667 <replaceable>file</replaceable> is the program you want to
668 install. If it is found on your system, you will be told
669 where it is, as follows:</para>
670
671 <screen>&prompt.root; <userinput>whereis lsof</userinput>
672lsof: /usr/ports/sysutils/lsof</screen>
673
674 <para>This tells us that <command>lsof</command> (a system
675 utility) can be found in the
676 <filename>/usr/ports/sysutils/lsof</filename>
bad269a5
JS
677 directory. <command>whereis</command> will also
678 locate the dfport overrides located in
679 <filename>/usr/dfports</filename>. Work from
680 the <filename>/usr/ports</filename> location, as the override
681 will automatically happen.</para>
8abd622e
JS
682
683 <para>Yet another way to find a particular port is by using the
684 ports collection's built-in search mechanism. To use the
685 search feature, you will need to be in the
686 <filename>/usr/ports</filename> directory. Once in that
687 directory, run <command>make search
688 name=<replaceable>program-name</replaceable></command> where
689 <replaceable>program-name</replaceable> is the name of the
690 program you want to find. For example, if you were looking
691 for <command>lsof</command>:</para>
692
693 <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
694&prompt.root; <userinput>make search name=lsof</userinput>
695Port: lsof-4.56.4
696Path: /usr/ports/sysutils/lsof
697Info: Lists information about open files (similar to fstat(1))
698Maint: obrien@FreeBSD.org
699Index: sysutils
700B-deps:
701R-deps: </screen>
702
703 <para>The part of the output you want to pay particular
704 attention to is the <quote>Path:</quote> line, since that
705 tells you where to find the port. The other information
706 provided is not needed in order to install the port, so it
707 will not be covered here.</para>
708
709 <para>For more in-depth searching you can also use <command>make
710 search key=<replaceable>string</replaceable></command> where
711 <replaceable>string</replaceable> is some text to search for.
712 This searches port names, comments, descriptions and
713 dependencies and can be used to find ports which relate to a
714 particular subject if you don't know the name of the program
715 you are looking for.</para>
716
717 <para>In both of these cases, the search string is case-insensitive.
718 Searching for <quote>LSOF</quote> will yield the same results as
719 searching for <quote>lsof</quote>.</para>
720
721 <note>
722 <para>You must be logged in as <username>root</username> to install
723 ports.</para>
724 </note>
725
726 <para>Now that you have found a port you would like to install,
727 you are ready to do the actual installation. The port
728 includes instructions on how to build source code, but does not include the
729 actual source code. You can get the source code from a CD-ROM
730 or from the Internet. Source code is distributed in whatever
731 manner the software author desires. Frequently this is a
732 tarred and gzipped file, but it might be compressed with some
733 other tool or even uncompressed. The program source code,
734 whatever form it comes in, is called a
735 <quote>distfile</quote>. You can get the distfile from a
736 CD-ROM or from the Internet.</para>
737
738 <warning>
739 <para>Before installing any port, you should be sure to have
740 an up-to-date ports collection and you should check <ulink
741 url="http://vuxml.freebsd.org/"></ulink> for security issues
742 related to your port.</para>
743
744 <para>A security vulnerabilities check can be automatically
745 done by <application>portaudit</application> before any new
746 application installation. This tool can be found in the
747 ports collection (<filename
748 role="package">security/portaudit</filename>). Consider
749 running <command>portaudit -F</command> before installing a
750 new port, to fetch the current vulnerabilities database. A
751 security audit and an update of the database will be
752 performed during the daily security system check. For more
bad269a5 753 informations read the portaudit and &man.periodic.8;
8abd622e
JS
754 manual pages.</para>
755 </warning>
756
8abd622e
JS
757 <note>
758 <para>You can save an extra step by just running <command>make
759 install</command> instead of <command>make</command> and
760 <command>make install</command> as two separate steps.</para>
761 </note>
762
763 <note>
764 <para>Some shells keep a cache of the commands that are
765 available in the directories listed in the
766 <envar>PATH</envar> environment variable, to speed up
767 lookup operations for the executable file of these
768 commands. If you are using one of these shells, you might
769 have to use the <command>rehash</command> command after
770 installing a port, before the newly installed commands can
771 be used. This is true for both shells that are part of
772 the base-system (such as <command>tcsh</command>) and
773 shells that are available as ports (for instance,
774 <filename role="package">shells/zsh</filename>).</para>
775 </note>
776
8abd622e
JS
777 <sect3 id="ports-inet">
778 <title>Installing Ports from the Internet</title>
779
780 <para>As with the last section, this section makes an
781 assumption that you have a working Internet connection. If
bad269a5 782 you do not, you will need to put a copy
8abd622e
JS
783 of the distfile into
784 <filename>/usr/ports/distfiles</filename> manually.</para>
785
786 <para>Installing a port from the Internet is done exactly the
bad269a5
JS
787 same way as it would be if you already had the distfile. The
788 only difference between the two is that the
789 distfile is downloaded from the Internet on demand.</para>
8abd622e 790
bad269a5 791 <para>Here are the steps involved:</para>
8abd622e
JS
792
793 <screen>&prompt.root; <userinput>make install</userinput>
794&gt;&gt; lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
795&gt;&gt; Attempting to fetch from ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/.
796Receiving lsof_4.57D.freebsd.tar.gz (439860 bytes): 100%
797439860 bytes transferred in 18.0 seconds (23.90 kBps)
798===&gt; Extracting for lsof-4.57
799...
800[extraction output snipped]
801...
802&gt;&gt; Checksum OK for lsof_4.57D.freebsd.tar.gz.
803===&gt; Patching for lsof-4.57
804===&gt; Applying FreeBSD patches for lsof-4.57
805===&gt; Configuring for lsof-4.57
806...
807[configure output snipped]
808...
809===&gt; Building for lsof-4.57
810...
811[compilation output snipped]
812...
813===&gt; Installing for lsof-4.57
814...
815[installation output snipped]
816...
817===&gt; Generating temporary packing list
818===&gt; Compressing manual pages for lsof-4.57
819===&gt; Registering installation for lsof-4.57
820===&gt; SECURITY NOTE:
821 This port has installed the following binaries which execute with
822 increased privileges.
823&prompt.root;</screen>
824
825 <para>As you can see, the only difference is the line that tells
826 you where the system is fetching the port distfile from.</para>
827
828 <para>The ports system uses &man.fetch.1; to download the
829 files, which honors various environment variables, including
830 <envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>,
831 and <envar>FTP_PASSWORD</envar>. You may need to set one or
832 more of these if you are behind a firewall, or need to use
833 an FTP/HTTP proxy. See &man.fetch.3; for the complete
834 list.</para>
835
836 <para>For users which cannot be connected all the time, the
837 <command>make <maketarget>fetch</maketarget></command> option is
838 provided. Just run this command at the top level directory
839 (<filename>/usr/ports</filename>) and the required files
840 will be downloaded for you. This command will also work in
841 the lower level categories, for example:
842 <filename>/usr/ports/net</filename>.
843 Note that if a port depends on libraries or other ports this will
844 <emphasis>not</emphasis> fetch the distfiles of those ports too.
845 Replace <maketarget>fetch</maketarget> with
846 <maketarget>fetch-recursive</maketarget>
847 if you want to fetch all the dependencies of a port too.</para>
848
849 <note><para>You can build all the ports in a category or as a
850 whole by running <command>make</command> in the top level
851 directory, just like the aforementioned <command>make
852 <makevar>fetch</makevar></command> method. This is
853 dangerous, however, as some ports cannot co-exist. In other
854 cases, some ports can install two different files with the
855 same filename.</para></note>
856
857 <para>In some rare cases, users may need to acquire the
858 tarballs from a site other than the
859 <makevar>MASTER_SITES</makevar> (the location where files
860 are downloaded from). You can override the
861 <makevar>MASTER_SITES</makevar> option with the following
862 command:</para>
863
864 <screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
865&prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \
866ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch</userinput></screen>
867
868 <para>In this example we change the
869 <makevar>MASTER_SITES</makevar> option to <hostid
870 role="fqdn">ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/</hostid>.</para>
871
872 <note><para>Some ports allow (or even require) you to provide build options
873 which can enable/disable parts of the application which are
874 unneeded, certain security options, and other
875 customizations. A few which come to mind are <filename
876 role="package">www/mozilla</filename>, <filename
877 role="package">security/gpgme</filename>, and <filename
878 role="package">mail/sylpheed-claws</filename>. A message
879 will be displayed when options such as these are
880 available.</para></note>
881 </sect3>
882
883 <sect3>
884 <title>Overriding the Default Ports Directories</title>
885
886 <para>Sometimes it is useful (or mandatory) to use a different
887 distfiles and ports directory. The
888 <makevar>PORTSDIR</makevar> and <makevar>PREFIX</makevar>
889 variables can override the default directories. For
890 example:</para>
891
892 <screen>&prompt.root; <userinput>make PORTSDIR=/usr/home/example/ports install</userinput></screen>
893
894 <para>will compile the port in
895 <filename>/usr/home/example/ports</filename> and install
896 everything under <filename>/usr/local</filename>.</para>
897
898 <screen>&prompt.root; <userinput>make PREFIX=/usr/home/example/local install</userinput></screen>
899
900 <para>will compile it in <filename>/usr/ports</filename> and
901 install it in
902 <filename>/usr/home/example/local</filename>.</para>
903
904 <para>And of course,</para>
905
906 <screen>&prompt.root; <userinput>make PORTSDIR=../ports PREFIX=../local install</userinput></screen>
907
908 <para>will combine the two (it is too long to completely write
909 on this page, but it should give you the general
910 idea).</para>
911
912 <para>Alternatively, these variables can also be set as part
913 of your environment. Read the manual page for your shell
914 for instructions on doing so.</para>
915 </sect3>
916
917 <sect3>
918 <title>Dealing with <command>imake</command></title>
919
920 <para>Some ports that use <command>imake</command> (a part of
921 the X Window System) do not work well with
922 <makevar>PREFIX</makevar>, and will insist on installing
923 under <filename>/usr/X11R6</filename>. Similarly, some Perl
924 ports ignore <makevar>PREFIX</makevar> and install in the
925 Perl tree. Making these ports respect
926 <makevar>PREFIX</makevar> is a difficult or impossible
927 job.</para>
928
929 </sect3>
930 </sect2>
931
932 <sect2 id="ports-removing">
933 <title>Removing Installed Ports</title>
934
935 <indexterm>
936 <primary>ports</primary>
937 <secondary>removing</secondary>
938 </indexterm>
939 <para>Now that you know how to install ports, you are probably
940 wondering how to remove them, just in case you install one and
941 later on decide that you installed the wrong port.
942 We will remove our previous example (which was
943 <command>lsof</command> for
944 those of you not paying attention). As with installing ports,
945 the first thing you must do is change to the port directory,
946 <filename>/usr/ports/sysutils/lsof</filename>. After you change
947 directories, you are ready to uninstall <command>lsof</command>.
948 This is done with
949 the <command>make deinstall</command> command:</para>
950
951 <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput>
952&prompt.root; <userinput>make deinstall</userinput>
953===&gt; Deinstalling for lsof-4.57</screen>
954
955 <para>That was easy enough. You have removed
956 <command>lsof</command>
957 from your system. If you would like to reinstall it, you can do
958 so by running <command>make reinstall</command> from the
959 <filename>/usr/ports/sysutils/lsof</filename> directory.</para>
960
961 <para>The <command>make deinstall</command> and <command>make
962 reinstall</command> sequence does not work once you have run
963 <command>make clean</command>. If you want to deinstall a
964 port after cleaning, use &man.pkg.delete.1; as
965 discussed in the <link linkend="packages-using">Packages
966 section of the Handbook</link>.</para>
967 </sect2>
968
969 <sect2 id="ports-disk-space">
970 <title>Ports and Disk Space</title>
971
972 <indexterm>
973 <primary>ports</primary>
974 <secondary>disk-space</secondary>
975 </indexterm>
bad269a5 976 <para>Using the ports collection can definitely eat up your disk
8abd622e
JS
977 space. For this reason you should always remember to clean up
978 the work directories using the <command>make
979 <makevar>clean</makevar></command> option. This will remove
980 the <filename>work</filename> directory after a port has been
981 built, and installed. You can also remove the tar files from
982 the <filename>distfiles</filename> directory, and remove the
983 installed ports when their use has delimited.</para>
984
985 <para>Some users choose to limit the port categories by placing an entry
986 in the <filename>refuse</filename> file. This way when they run the
987 <application>CVSup</application> application, it will not download the
988 files in that category.</para>
989 </sect2>
990
991 <sect2 id="ports-upgrading">
992 <title>Upgrading Ports</title>
993
994 <indexterm>
995 <primary>portupgrade</primary>
996 </indexterm>
997 <indexterm>
998 <primary>ports</primary>
999 <secondary>upgrading</secondary>
1000 </indexterm>
1001 <note>
bad269a5 1002 <para>Once you have updated your ports collection, before
8abd622e
JS
1003 attempting a port upgrade, you should check the
1004 <filename>/usr/ports/UPDATING</filename> file. This file
1005 describes various issues and additional steps users may
1006 encounter and need to perform when updating a port.</para>
1007 </note>
1008
1009 <para>Keeping your ports up to date can be a tedious job. For
1010 instance, to upgrade a port you would go to the ports
1011 directory, build the port, deinstall the old port, install the
1012 new port, and then clean up after the build. Imagine doing
1013 that for five ports, tedious right? This was a large problem
1014 for system administrators to deal with, and now we have
1015 utilities which do this for us. For instance the <filename
1016 role="package">sysutils/portupgrade</filename> utility will do
1017 everything for you! Just install it like you would any other
1018 port, using the <command>make <makevar>install
1019 clean</makevar></command> command.</para>
1020
1021 <para>Now create a database with the <command>pkgdb -F</command>
1022 command. This will read the list of installed ports and
1023 create a database file in the <filename>/var/db/pkg</filename>
1024 directory. Now when you run <command>portupgrade
1025 -a</command>, it will read this and the ports
1026 <filename>INDEX</filename> file. Finally,
1027 <application>portupgrade</application> will begin to download, build,
1028 backup, install, and clean the ports which have been updated.
1029 <application>portupgrade</application> comes with a lot of options
1030 for different use cases, the most important ones will be presented
1031 below.</para>
1032
1033 <para>If you want to upgrade only a certain application, not the
1034 complete database, use <command>portupgrade
1035 <replaceable>pkgname</replaceable></command>,
1036 include the flags <option>-r</option> if
1037 <application>portupgrade</application> should act on all
1038 those packages depending on the given package as well, and
1039 <option>-R</option> to act on all packages required by
1040 the given packages.
1041 To use packages instead of ports for installation, provide
1042 <option>-P</option> and to just fetch distfiles without
1043 building or installing anything, use <option>-F</option>.
1044 For further information see &man.portupgrade.1;.</para>
1045
1046 <note>
1047 <para>It is important to regularly update the package database using
1048 <command>pkgdb -F</command> to fix inconsistencies, especially when
1049 <application>portupgrade</application> asks you to. Do not abort
1050 <application>portupgrade</application> while it is updating the
1051 package database, this will leave you an inconsistent
1052 database.</para>
1053 </note>
1054
1055 <para>Other utilities exist which will do this, check out the
1056 <filename>ports/sysutils</filename> directory and see what you
1057 come up with.</para>
bad269a5
JS
1058
1059 <warning>
1060 <para><application>portupgrade</application> is not aware of dfports
1061 and the overrides contained there. Therefore,
1062 <application>portupgrade</application>
1063 may not always work when dealing with any port that has overrides, or
1064 depends on other ports that have overrides. Exercise caution.</para>
1065 </warning>
1066
8abd622e
JS
1067 </sect2>
1068 </sect1>
1069
1070 <sect1 id="ports-nextsteps">
1071 <title>Post-installation Activities</title>
1072
1073 <para>After installing a new application you will normally want to
1074 read any documentation it may have included, edit any
1075 configuration files that are required, ensure that the
1076 application starts at boot time (if it is a daemon), and so
1077 on.</para>
1078
1079 <para>The exact steps you need to take to configure each
1080 application will obviously be different. However, if you have
1081 just installed a new application and are wondering <quote>What
1082 now?</quote> these tips might help:</para>
1083
1084 <itemizedlist>
1085 <listitem>
1086 <para>Use &man.pkg.info.1; to find out which files were installed,
1087 and where. For example, if you have just
1088 installed FooPackage version 1.0.0, then this command</para>
1089
1090 <screen>&prompt.root; <userinput>pkg_info -L foopackage-1.0.0 | less</userinput></screen>
1091
1092 <para>will show all the files installed by the package. Pay
1093 special attention to files in <filename>man/</filename>
1094 directories, which will be manual pages,
1095 <filename>etc/</filename> directories, which will be
1096 configuration files, and <filename>doc/</filename>, which
1097 will be more comprehensive documentation.</para>
1098
1099 <para>If you are not sure which version of the application was
1100 just installed, a command like this</para>
1101
1102 <screen>&prompt.root; <userinput>pkg_info | grep -i <replaceable>foopackage</replaceable></userinput></screen>
1103
1104 <para>will find all the installed packages that have
1105 <replaceable>foopackage</replaceable> in the package name.
1106 Replace <replaceable>foopackage</replaceable> in your
1107 command line as necessary.</para>
1108 </listitem>
1109
1110 <listitem>
1111 <para>Once you have identified where the application's manual
1112 pages have been installed, review them using &man.man.1;.
1113 Similarly, look over the sample configuration files, and any
1114 additional documentation that may have been provided.</para>
1115 </listitem>
1116
1117 <listitem>
1118 <para>If the application has a web site, check it for
1119 additional documentation, frequently asked questions, and so
1120 forth. If you are not sure of the web site address it may
1121 be listed in the output from</para>
1122
1123 <screen>&prompt.root; <userinput>pkg_info <replaceable>foopackage-1.0.0</replaceable></userinput></screen>
1124
1125 <para>A <literal>WWW:</literal> line, if present, should provide a URL
1126 for the application's web site.</para>
1127 </listitem>
1128
1129 <listitem>
1130 <para>Ports that should start at boot (such as Internet
1131 servers) will usually install a sample script in
1132 <filename>/usr/local/etc/rc.d</filename>. You should
1133 review this script for correctness and edit or rename it if
1134 needed. See <link
1135 linkend="configtuning-starting-services">Starting
1136 Services</link> for more information.</para>
1137 </listitem>
1138 </itemizedlist>
1139 </sect1>
1140
1141 <sect1 id="ports-broken">
1142 <title>Dealing with Broken Ports</title>
1143
1144 <para>If you come across a port that does not work for you,
1145 there are a few things you can do, including:</para>
1146
1147 <orderedlist>
1148 <listitem>
1149 <para>Fix it! The <ulink
1150 url="../porters-handbook/index.html">Porter's
1151 Handbook</ulink> includes detailed information on the
1152 <quote>Ports</quote> infrastructure so that you can fix the occasional
1153 broken port or even submit your own!</para>
1154 </listitem>
1155
bad269a5
JS
1156 <listitem>
1157 <para>Create an override in dfports. Copy the port directory
1158 to the dfports directory, substituting 'dfport' for 'port' in any
1159 .include lines. Add any additional patches needed
1160 to make the port compile on os;, and submit it to
1161 &a.submit.name .</para>
1162 </listitem>
1163
1164
8abd622e
JS
1165 <listitem>
1166 <para>Gripe&mdash;<emphasis>by email only</emphasis>! Send
1167 email to the maintainer of the port first. Type
1168 <command>make maintainer</command> or read the
1169 <filename>Makefile</filename> to find the maintainer's
1170 email address. Remember to include the name and version
1171 of the port (send the <literal>&dollar;FreeBSD:</literal>
1172 line from the <filename>Makefile</filename>) and the
1173 output leading up to the error when you email the
1174 maintainer. If you do not get a response from the
bad269a5 1175 maintainer, you can try &a.bugs.name .</para>
8abd622e
JS
1176 </listitem>
1177
1178 <listitem>
1179 <para>Grab the package from an FTP site near you. The
1180 <quote>master</quote> package collection is on <hostid
bad269a5
JS
1181 role="fqdn">GoBSD.com</hostid> in the <ulink
1182 url="http://www.GoBSD.com/packages/">packages
1183 directory</ulink>. These are more likely to work
8abd622e
JS
1184 than trying to compile from source and are a lot faster as
1185 well. Use the &man.pkg.add.1; program to install the
1186 package on your system.</para>
1187 </listitem>
1188 </orderedlist>
1189 </sect1>
1190
1191</chapter>
1192
1193<!--
1194 Local Variables:
1195 mode: sgml
1196 sgml-declaration: "../chapter.decl"
1197 sgml-indent-data: t
1198 sgml-omittag: nil
1199 sgml-always-quote-attributes: t
1200 sgml-parent-document: ("../book.sgml" "part" "chapter")
1201 End:
1202-->