switch /etc/mk.conf to /usr/pkg/etc/mk.conf to reflect current practice
[ikiwiki.git] / docs / newhandbook / pkgsrc / index.mdwn
1 # Installing Applications using NetBSD's pkgsrc framework 
2
3 [[!toc  levels=3]]
4 <!-- XXX: possibly also mention pkgin and other fancy stuff. -->
5
6
7
8 ## Overview of Software Installation 
9
10 If you have used a UNIX® system before you will know that the typical procedure for installing third party software goes something like this:
11
12
13   1. Download the software, which might be distributed in source code format, or as a binary.
14
15   1. Unpack the software from its distribution format (typically a tarball compressed with [compress(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=compress&section1), [gzip(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=gzip&section=1), or [bzip2(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=bzip2&section=1)).
16
17   1. Locate the documentation (perhaps an `INSTALL` or `README` file, or some files in a `doc/` subdirectory) and read up on how to install the software.
18
19   1. If the software was distributed in source format, compile it. This may involve editing a `Makefile`, or running a `configure` script, and other work.
20
21   1. Test and install the software.
22
23
24 And that is only if everything goes well. If you are installing a software package that was not deliberately ported to DragonFly you may even have to go in and edit the code to make it work properly. Should you want to, you can continue to install software the ***traditional*** way with DragonFly. However, DragonFly provides technology from NetBSD, which can save you a lot of effort: pkgsrc. At the time of writing, over 8,000 third party applications have been made available in this way.
25
26
27 For any given application, the DragonFly Binary package for that application is a single file which you must download. The package contains pre-compiled copies of all the commands for the application, as well as any configuration files or documentation. A downloaded package file can be manipulated with DragonFly package management commands, such as [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_add&section1), [pkg_delete(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_delete&section=1), [pkg_info(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_info&section=1), and so on. Installing a new application can be carried out with a single command.
28
29
30
31 In addition the pkgsrc collection supplies a collection of files designed to automate the process of compiling an application from source code. Remember that there are a number of steps you would normally carry out if you compiled a program yourself (downloading, unpacking, patching, compiling, installing). The files that make up a pkgsrc source collection contain all the necessary information to allow the system to do this for you. You run a handful of simple commands and the source code for the application is automatically downloaded, extracted, patched, compiled, and installed for you. In fact, the pkgsrc source subsystem can also be used to generate packages which can later be manipulated with `pkg_add` and the other package management commands that will be introduced shortly.
32
33
34 Pkgsrc understands ***dependencies***. Suppose you want to install an application that depends on a specific library being installed. Both the application and the library have been made available through the pkgsrc collection. If you use the `pkg_add` command or the pkgsrc subsystem to add the application, both will notice that the library has not been installed, and automatically install the library first. You might be wondering why pkgsrc® bothers with both. Binary packages and the source tree both have their own strengths, and which one you use will depend on your own preference.
35
36
37
38  **Binary Package Benefits** 
39
40
41
42
43 * A compressed package tarball is typically smaller than the compressed tarball containing the source code for the application.
44
45
46 * Packages do not require any additional compilation. For large applications, such as ***Mozilla***, ***KDE***, or ***GNOME*** this can be important, particularly if you are on a slow system.
47
48
49 * Packages do not require any understanding of the process involved in compiling software on DragonFly.
50
51
52
53 **Pkgsrc source Benefits** 
54
55
56
57
58 * Binary packages are normally compiled with conservative options, because they have to run on the maximum number of systems. By installing from the source, you can tweak the compilation options to (for example) generate code that is specific to a Pentium IV or Athlon processor.
59
60
61 * Some applications have compile time options relating to what they can and cannot do. For example, <i>Apache</i> can be configured with a wide variety of different built-in options. By building from the source you do not have to accept the default options, and can set them yourself. In some cases, multiple packages will exist for the same application to specify certain settings. For example, <i>vim</i> is available as a `vim` package and a `vim-gtk` package, depending on whether you have installed an X11 server. This sort of rough tweaking is possible with packages, but rapidly becomes impossible if an application has more than one or two different compile time options.
62
63
64 * The licensing conditions of some software distributions forbid binary distribution. They must be distributed as source code.
65
66
67 * Some people do not trust binary distributions. With source code, it is possible to check for any vulnerabilities built into the program before installing it to an otherwise secure system. Few people perform this much review, however.
68
69
70 * If you have local patches, you will need the source in order to apply them.
71
72
73 * Some people like having code around, so they can read it if they get bored, hack it, borrow from it (license permitting, of course), and so on.
74
75
76
77 To keep track of updated pkgsrc releases subscribe to the [NetBSD pkgsrc users mailing list](http://www.netbsd.org/MailingLists/pkgsrc-users) and the [NetBSD pkgsrc users mailing list](http://www.netbsd.org/MailingLists/tech-pkgsrc). It's also useful to watch the [DragonFly User related mailing list](http://leaf.dragonflybsd.org/mailarchive/) as errors with pkgsrc on DragonFly should be reported there.
78
79
80
81  **Warning:** Before installing any application, you should check http://www.pkgsrc.org/ for security issues related to your application.
82
83
84
85 Audit-packages will automatically check all installed applications for known vulnerabilities, a check will be also performed before any application build. Meanwhile, you can use the command `audit-packages -d` after you have installed some packages.
86
87
88
89
90 ## Finding Your Application 
91
92
93
94 Before you can install any applications you need to know what you want, and what the application is called. DragonFly's list of available applications is growing all the time. Fortunately, there are a number of ways to find what you want:
95
96 Since DragonFly 1.11 [pkg_search(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_search&section1) is included in the base system.  [pkg_search(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_search&section=1) searches an already installed pkgsrc® INDEX for for a given package name.  If pkgsrc® is not installed or the INDEX file is missing, it fetches the [pkg_summary(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_summary&section=5) file.
97
98  **Example. Find a Package** 
99
100     # pkg_search fvwm
101     fvwm-2.4.20nb1          Newer version of X11 Virtual window manager
102     fvwm-2.5.24             Development version of X11 Virtual window manager
103     fvwm-themes-0.6.2nb8    Configuration framework for fvwm2 with samples
104     fvwm-wharf-1.0nb1       Copy of AfterStep's Wharf compatible with fvwm2
105     fvwm1-1.24rnb1          Virtual window manager for X
106
107     
108
109     # pkg_search -v fvwm-2.5
110     Name    : fvwm-2.5.24-50
111     Dir     : wm/fvwm-devel                                     
112     Desc    : Development version of X11 Virtual window manager 
113     URL     : any                                               
114     Deps    : perl>#5.0 gettext-lib>0.14.5 png>=1.2.4 libXext>=0.99.0 libX11>=1.1 libXau>=1.0 libXdmcp>=0.99 libX11>=0.99 libXft>=2.1.10 fontconfig>=2.2 freetype2>=2.1.8 
115     freetype2>=2.1.3 expat>=1.95.7 expat>=1.95.4 freetype2>=2.1.10nb1 expat>=2.0.0nb1 fontconfig>=2.4.2 fontconfig>=2.1nb2 libXrender>=0.9.2 libXpm>=3.5.4.2 libXt>=1.0.0 
116     libSM>=0.99.2 libICE>=0.99.1 png>=1.2.9nb2
117
118
119 To get more verbose information about a package (dependencies, path in `/usr/pkgsrc`, Description) use the `-v` switch.
120
121 There is a pkgsrc® related web site that maintains an up-to-date searchable list of all the available applications, at [http://pkgsrc.se](http://pkgsrc.se). The packages and the corresponding source tree are divided into categories, and you may either search for an application by name (if you know it), or see all the applications available in a category.
122
123 ## Get the description of a package 
124
125 To get a more verbose description of the package use pkg_search's `-s` switch with the exact package name (e.g. as given by a normal query):
126
127     # pkg_search -s fvwm-2.5.24
128     Fvwm is a very famous window manager for X, which provides a
129     virtual/multiple disjoint desktop, a 3-D look for windows decorations,
130     shaped/color icons. It gives a very good emulation of mwm. A nice
131     button-bar can be used to provide convenient access to frequently used
132     functions or programs.
133
134     This package is based on the unstable 2.5.x series of fvwm.  Do not
135     use it unless comfortable running beta software.
136
137
138  **Note:**  To use the `-s` switch you need a complete pkgsrc tree installed.
139
140
141  
142 ## Using the Binary Packages System 
143
144 ***DragonFly customizations contributed by Chern Lee and Adrian Nida. ***
145
146
147
148 ### Installing a Binary Package 
149
150 You can use the [pkg_add(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_add&section=1) utility to install a pkgsrc® software package from a local file or from a server on the network.
151
152 The [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_radd&section=1) tool conveniently fetches and installs the requested package from one of DragonFly's pkg servers without having to know the full URL to it.
153
154 <!-- XXX: put in pkg_radd example, it's more meaningful; also check the url below (ftp.pkgsrc-box.org) -->
155
156
157 Binary package files are distributed in `.tgz` formats. You can find them at the default location ftp://ftp.pkgsrc-box.org/packages/, among other sites. The layout of the packages is similar to that of the `/usr/pkgsrc` tree. Each category has its own directory, and every package can be found within the `All` directory.
158
159
160
161 The directory structure of the binary package system matches the source tree layout; they work with each other to form the entire package system.
162
163 #### Using pkg_radd 
164
165 Since DragonFly 1.11 you can use [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_radd&section=1) to install binary packages without having to set `PACKAGESITE` or providing the complete URL.  [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_radd&section=1) will handle that for you:
166
167     
168
169     # pkg_radd host
170     #
171
172
173 ### Dealing with different package versions 
174
175 Due to the fact that the official packages are only build for the RELEASE-Version of DragonFly, it is possible that you see a warning when installing binary packages on a DEVELOPMENT-version of DragonFly.  The warning could look like this:
176
177     pkg_add: Warning: package `vim-gtk2-7.1.116.tgz' was built for a different version of the OS:
178     pkg_add: DragonFly/i386 1.10.1 (pkg) vs. DragonFly/i386 1.11.0 (this host)
179
180 You can safely ignore this warning.  Normally all packages build for RELEASE run fine on DEVELOPMENT unless a major API-breakage was introduced.  In this case you would see a message from the developers on the appropriate mailing list.
181
182 ### Managing Packages 
183
184 [pkg_info(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_info&section=1) is a utility that lists and describes the various packages installed.
185
186
187
188     # pkg_info
189     digest-20050731     Message digest wrapper utility
190     screen-4.0.2nb4     Multi-screen window manager
191     ...
192
193 [pkg_version(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_version&section=1) is a utility that summarizes the versions of all installed packages. It compares the package version to the current version found in the ports tree.
194
195 ### Deleting a Package 
196
197 To remove a previously installed software package, use the [pkg_delete(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_delete&section=1) utility.
198
199
200     # pkg_delete screen-4.0.3.tgz
201
202 ### Miscellaneous 
203
204 All package information is stored within the `/var/db/pkg` directory. The installed file list and descriptions of each package can be found within subdirectories of this directory.
205
206
207
208 ## Using the pkgsrc® Source Tree 
209
210 The following sections provide basic instructions on using the pkgsrc source tree to install or remove programs from your system.
211
212 ### Obtaining the pkgsrc Source Tree 
213
214 Before you can install pkgsrc® packages from source, you must first obtain the pkgsrc source tree--which is essentially a set of `Makefiles`, patches, and description files placed in `/usr/pkgsrc`.
215
216 #### CVS 
217
218 The primary method to obtain and keep your pkgsrc collection up to date is by using  **CVS**. This is a quick method for getting the pkgsrc collection using  **CVS** .
219
220 Run `cvs`:
221
222     # cd /usr
223     # cvs -d anoncvs@anoncvs.us.netbsd.org:/cvsroot co pkgsrc
224
225  
226 Running the following command later will download and apply all the recent changes to your source tree.
227
228     # cd /usr/pkgsrc
229     # cvs up
230
231   
232 #### The DragonFly Way 
233
234 As of the 1.10 release, you can use the `/usr/Makefile` to checkout & update the pkgsrc tree quickly.
235
236 as root:
237
238
239     # cd /usr
240     # make pkgsrc-create
241
242 to checkout from git repository, or
243
244
245     # cd /usr
246     # make pkgsrc-update
247
248 to update. **NOTE**: If you use CVS instead of git please do edit the Makefile to use an appropriately speedy CVS mirror for your location and to reduce load on the main pkgsrc CVS server.
249
250 ## Installing Packages from Source
251
252 The first thing that should be explained when it comes to the source tree is what is actually meant by a ***skeleton***. In a nutshell, a source skeleton is a minimal set of files that tell your DragonFly system how to cleanly compile and install a program. Each source skeleton should include:
253
254 * A `Makefile`. The `Makefile` contains various statements that specify how the application should be compiled and where it should be installed on your system.
255
256
257 * A `distinfo` file. This file contains information about the files that must be downloaded to build the port and their checksums, to verify that files have not been corrupted during the download using [md5(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=md5&section=1).
258
259
260 * A `files` directory. This directory contains the application specific files that are needed for the programs appropriate run-time configuration.
261
262   This directory may also contain other files used to build the port.
263
264
265 * A `patches` directory. This directory contains patches to make the program compile and install on your DragonFly system. Patches are basically small files that specify changes to particular files. They are in plain text format, and basically say <i>Remove line 10</i> or <i>Change line 26 to this ...</i>. Patches are also known as <i>diffs</i> because they are generated by the [diff(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#diff&section1) program.
266
267
268 * A `DESCR` file. This is a more detailed, often multiple-line, description of the program.
269
270
271 * A `PLIST` file. This is a list of all the files that will be installed by the port. It also tells the pkgsrc system what files to remove upon deinstallation.
272
273
274
275 Some pkgsrc source skeletons have other files, such as `MESSAGE`. The pkgsrc system uses these files to handle special situations. If you want more details on these files, and on pkgsrc in general, check out [The pkgsrc guide](http://www.netbsd.org/Documentation/pkgsrc/), available at the [NetBSD website](http://www.netbsd.org/).
276
277
278
279 Now that you have enough background information to know what the pkgsrc source tree is used for, you are ready to install your first compiled package. There are two ways this can be done, and each is explained below. 
280
281 Another way to find a particular source tree is by using the pkgsrc collection's built-in search mechanism. To use the search feature, you will need to be in the `/usr/pkgsrc` directory. Once in that directory, run `bmake search key=program-name` where `program-name` is the name of the program you want to find. This searches packages names, comments, descriptions and dependencies and can be used to find packages which relate to a particular subject if you don't know the name of the program you are looking for. For example, if you were looking for `apache2`:
282
283
284     # cd /usr/pkgsrc
285     # bmake search key="apache2"
286     Extracting complete dependency database.  This may take a while...
287     ....................................................................................................
288     100
289     ....................................................................................................
290     200
291     <Snip />
292     5800
293     ....................................................................................................
294     5900
295     .................................................................................................Reading database file
296     Flattening dependencies
297     Flattening build dependencies
298     Generating INDEX file
299     Indexed 5999 packages
300     <Snip />
301     Pkg:    apache-2.2.6nb2
302     Path:   www/apache22
303     Info:   Apache HTTP (Web) server, version 2
304     Maint:  tron@NetBSD.org
305     Index:  www
306     B-deps: perl>#5.0 apr-util>1.2.8 apr>=1.2.8 libtool-base>=1.5.22nb1 pkg-config>=0.19 expat>=1.95.7 gmake>=3.78 gettext-lib>=0.14.5 
307     {gettext-tools>=0.14.5,gettext>=0.10.36<0.14.5} expat>=1.95.4 expat>=2.0.0nb1 apr-util>=1.2.8nb1
308     R-deps: perl>#5.0 apr-util>1.2.8 apr>=1.2.8 expat>=1.95.7 expat>=1.95.4 expat>=2.0.0nb1 apr-util>=1.2.8nb1
309     Arch:   any
310
311
312 The part of the output you want to pay particular attention to is the <i>Path</i> line, since that tells you where to find the source tree for the requested application. The other information provided is not needed in order to install the package, so it will not be covered here.
313
314 The search string is case-insensitive. Searching for <i>APACHE</i> will yield the same results as searching for <i>apache</i>.
315
316
317
318  **Note:** It should be noted that <i>Extracting [the] complete dependency database</i> does indeed take a while.
319
320
321
322  **Note:** You must be logged in as `root` to install packages.
323
324
325
326 Now that you have found an application you would like to install, you are ready to do the actual installation. The source package includes instructions on how to build source code, but does not include the actual source code. You can get the source code from a CD-ROM or from the Internet. Source code is distributed in whatever manner the software author desires. Frequently this is a tarred and gzipped file, but it might be compressed with some other tool or even uncompressed. The program source code, whatever form it comes in, is called a ***distfile***. You can get the distfile from a CD-ROM or from the Internet.
327
328
329
330  **Warning:** Before installing any application, you should be sure to have an up-to-date source tree and you should check http://www.pkgsrc.org/ for security issues related to your port.
331
332
333 A security vulnerabilities check can be automatically done by  **audit-packages**  before any new application installation. This tool can be found in the pkgsrc collection ([security/audit-packages](http://pkgsrc.se/security/audit-packages)). Consider running `auditpackages -d` before installing a new package, to fetch the current vulnerabilities database. A security audit and an update of the database will be performed during the daily security system check. For more informations read the audit-packages and [periodic(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#periodic&section8) manual pages.
334
335
336
337  **Note:** It should be noted that the current setup of DragonFly requires the use of `bmake` instead of `make`. This is because the current version of make on DragonFly does not support all the parameters that NetBSD's does.
338
339
340
341  **Note:** You can save an extra step by just running `bmake install` instead of `bmake` and `bmake install` as two separate steps.
342
343
344
345  **Note:** Some shells keep a cache of the commands that are available in the directories listed in the `PATH` environment variable, to speed up lookup operations for the executable file of these commands. If you are using one of these shells, you might have to use the `rehash` command after installing a package, before the newly installed commands can be used. This is true for both shells that are part of the base-system (such as `tcsh`) and shells that are available as packages (for instance, [shells/zsh](http://pkgsrc.se/shells/zsh)).
346
347 <!-- XXX: mention the stuff about the pkgsrc security audit thingie -->
348
349
350 ### Installing Packages from the Internet 
351
352 As with the last section, this section makes an assumption that you have a working Internet connection. If you do not, you will need to put a copy of the distfile into `/usr/pkgsrc/distfiles` manually. Installing a package from the Internet is done exactly the same way as it would be if you already had the distfile. The only difference between the two is that the distfile is downloaded from the Internet on demand.
353
354
355 Here are the steps involved:
356
357
358     # cd /usr/pkgsrc/chat/ircII
359     # bmake install clean
360     => ircii-20040820.tar.bz2 doesn't seem to exist on this system.
361     => Attempting to fetch ircii-20040820.tar.bz2 from ftp://ircii.warped.com/pub/ircII/.
362     => [559843 bytes]
363     [FTP transfer snipped]
364     150 Opening BINARY mode data connection for 'ircii-20040820.tar.bz2' (559843 bytes).
365     100% |***************************************|   550 KB  110.34 KB/s   00:00 ETA
366     226 Transfer complete.
367     [FTP transfer snipped]
368     221 Thank you for using the FTP service on bungi.sjc.warped.net.
369     => Checksum SHA1 OK for ircii-20040820.tar.bz2.
370     => Checksum RMD160 OK for ircii-20040820.tar.bz2.
371     work -> /usr/obj/pkgsrc/chat/ircII/work
372     ##=> Extracting for ircII-20040820
373     #########################################################################=
374     The supported build options for this package are:
375
376     socks4 socks5
377
378     You can select which build options to use by setting PKG_DEFAULT_OPTIONS
379     or the following variable.  Its current value is shown:
380
381     
382     PKG_OPTIONS.ircII (not defined)
383
384     #########################################################################=
385     #########################################################################=
386     The following variables will affect the build process of this package,
387     ircII-20040820.  Their current value is shown below:
388
389     USE_INET6 = YES
390
391     You may want to abort the process now with CTRL-C and change their value
392     before continuing.  Be sure to run `/usr/pkg/bin/bmake clean' after
393     the changes.
394     #########################################################################=
395     ##=> Patching for ircII-20040820
396     ##=> Applying pkgsrc patches for ircII-20040820
397     ##=> Overriding tools for ircII-20040820
398     ##=> Creating toolchain wrappers for ircII-20040820
399     ##=> Configuring for ircII-20040820
400     ...
401     [configure output snipped]
402     ...
403     ##=>  Building for ircII-20040820
404     ...
405     [compilation output snipped]
406     ...
407     ##=>  Installing for ircII-20040820
408     ...
409     [installation output snipped]
410     ...
411     ##=> [Automatic manual page handling]
412     ##=> Registering installation for ircII-20040820
413     ##=> Cleaning for ircII-20040820
414     #
415
416
417
418 <!-- XXX: mention /usr/pkg/etc/mk.conf for options, etc -->
419
420 As you can see, the only difference are the lines that tell you where the system is fetching the package's distfile from.
421
422
423
424 The pkgsrc system uses [ftp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ftp&section=1) to download the files, which honors various environment variables, including `FTP_PASSIVE_MODE`, `FTP_PROXY`, and `FTP_PASSWORD`. You may need to set one or more of these if you are behind a firewall, or need to use an FTP/HTTP proxy. See [ftp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ftp&section=1) for the complete list. 
425
426
427
428 For users which cannot be connected all the time, the `bmake fetch` option is provided. Just run this command at the top level directory (`/usr/pkgsrc`) and the required files will be downloaded for you. This command will also work in the lower level categories, for example: `/usr/pkgsrc/net`. Note that if a package depends on libraries or other packages this will ***not*** fetch the distfiles of those packages as well.
429
430
431
432  **Note:** You can build all the packages in a category or as a whole by running `bmake` in the top level directory, just like the aforementioned `bmake `fetch*** method. This is dangerous, however, as some applications cannot co-exist. In other cases, some packages can install two different files with the same filename.
433
434
435
436 In some rare cases, users may need to acquire the tarballs from a site other than the `MASTER_SITES` (the location where files are downloaded from). You can override the `MASTER_SORT`, `MASTER_SORT_REGEX` and `INET_COUNTRY` options either within the `/usr/pkg/etc/mk.conf`.
437
438
439
440  **Note:** Some packages allow (or even require) you to provide build options which can enable/disable parts of the application which are unneeded, certain security options, and other customizations. A few which come to mind are [`www/mozilla`](http://pkgsrc.se/www/mozilla), [`security/gpgme`](http://pkgsrc.se/security/gpgme), and [`mail/sylpheed-claws`](http://pkgsrc.se/mail/sylpheed-claws). To find out what build options the application you are installing requires type:
441
442
443
444     
445
446     # bmake show-options
447
448
449
450
451
452  To change the build process, either change the values of PKG_DEFAULT_OPTIONS or PKG_OPTIONS.`***PackageName***` in `/usr/pkg/etc/mk.conf` or on the commandline as so:
453
454
455
456     
457
458     # bmake PKG_OPTIONS.ircII="-ssl"
459
460
461
462
463
464  An option is enabled if listed. It is disabled if it is prefixed by a minus sign.
465
466
467
468 #### Dealing with imake 
469
470
471
472 Some applications that use `imake` (a part of the X Window System) do not work well with `PREFIX`, and will insist on installing under `/usr/X11R6`. Similarly, some Perl ports ignore `PREFIX` and install in the Perl tree. Making these applications respect `PREFIX` is a difficult or impossible job.
473
474
475
476 ### Removing Installed Packages 
477
478
479
480 Now that you know how to install packages, you are probably wondering how to remove them, just in case you install one and later on decide that you installed the wrong program. We will remove our previous example (which was `ircII` for those of you not paying attention). As with installing packages, the first thing you must do is change to the package directory, `/usr/pkgsrc/chat/ircII`. After you change directories, you are ready to uninstall `ircII`. This is done with the `bmake deinstall` command:
481
482     
483
484     # cd /usr/pkgsrc/chat/ircII
485     # make deinstall
486     ##=>  Deinstalling for ircII-20040820
487
488
489 That was easy enough. You have removed `ircII` from your system. If you would like to reinstall it, you can do so by running `bmake reinstall` from the `/usr/pkgsrc/chat/ircII` directory.
490
491
492
493 The `bmake deinstall` and `bmake reinstall` sequence does not work once you have run `bmake clean`. If you want to deinstall a package after cleaning, use [pkg_delete(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_delete&section=1) as discussed in the [pkgsrc-using.html Pkgsrc section of the Handbook].
494
495
496
497 ### Packages and Disk Space 
498
499
500
501 Using the pkgsrc collection can definitely eat up your disk space. For this reason you should always remember to clean up the work directories using `bmake clean`. This will remove the `work` directory after a package has been built, and installed. You can also remove the tar files from the `distfiles` directory, and remove the installed package when their use has delimited.
502
503
504
505 ### Upgrading Packages
506
507
508  **Note:** Once you have updated your pkgsrc collection, before attempting a package upgrade, you should check the `/usr/pkgsrc/UPDATING` file. This file describes various issues and additional steps users may encounter and need to perform when updating a port.
509
510 There are multiple ways to upgrade your installed packages.
511
512  **Traditional way:** 
513
514 Keeping your packages up to date can be a tedious job. For instance, to upgrade a package you would go to the package directory, build the package, deinstall the old package , install the new package, and then clean up after the build. Imagine doing that for five packages, tedious right? This was a large problem for system administrators to deal with, and now we have utilities which do this for us. For instance the `pkg_chk` utility will do everything for you!
515
516  **Using `pkg_chk` utility:** (from both _source_ & _binary_ packages)
517
518 pkg_chk requires a few steps in order to work correctly. They are listed here.
519
520     # pkg_chk -g # make initial list of installed packages
521     # pkg_chk -r  # remove all packages that are not up to date and packages that depend on them
522     # pkg_chk -a  # install all missing packages (use binary packages, this is the default)
523     # pkg_chk -as # install all missing packages (build from source)
524
525 The above process removes all packages at once and installs the missing packages one by one.This can cause longer disruption of services when the removed package has to wait a long time for its turn to get installed. 
526
527  **Using `pkg_rolling-replace` utility:** (from only _source_)
528
529 "pkg_rolling-replace" replaces packages one by one and one can use it for a better way of package management. You can install "pkg_rolling-replace" by the following procedure.
530
531 Actually it does `make replace` on one package at a time, sorting the packages being replaced according to their interdependencies, which avoids most duplicate rebuilds.
532
533     # cd /usr/pkgsrc/pkgtools/pkg_rolling-replace/
534     # bmake install
535
536 Once pkg_rolling-replace is installed you can update the packages through the following steps.
537
538     # cd /usr && make pkgsrc-update
539     # pkg_rolling-replace -u
540
541 If some package like "bmake" does not get updated and throws an error during the above steps you can update it manually.
542 Inside the packages directory (/usr/pkgsrc/devel/bmake in this case)
543
544     # env USE_DESTDIR=full bmake package
545     # bmake clean-depends clean
546
547 And Go to the packages directory and install the binary package with
548
549     # pkg_add -u <pkg_name> (i.e. the name of the .tgz file).
550
551  **Using `pkgin` utility:** (from only _binary packages_)
552
553 You can also use "pkgin" to update software using binary packages just like apt or yum.
554
555     # cd /usr/pkgsrc/pkgtools/pkgin/
556     # bmake install
557
558 Once "pkgin" is installed edit "/usr/pkg/etc/pkgin/repositories.conf" to contain the line ( for i386 packages ).
559
560     http://avalon.dragonflybsd.org/packages/i386/DragonFly-2.6/stable/All
561
562 and
563
564     http://avalon.dragonflybsd.org/packages/x86_64/DragonFly-2.6/stable/All/
565
566 ( for x86_64 packages )
567
568 Then you can run the following commands to get the packages updated.
569
570     # pkgin update
571     # pkgin full-upgrade 
572
573     
574     
575     ## Post-installation Activities 
576
577
578
579 After installing a new application you will normally want to read any documentation it may have included, edit any configuration files that are required, ensure that the application starts at boot time (if it is a daemon), and so on.
580
581
582
583 The exact steps you need to take to configure each application will obviously be different. However, if you have just installed a new application and are wondering ***What now?*** these tips might help:
584
585
586
587
588 Use [pkg_info(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_info&section=1) to find out which files were installed, and where. For example, if you have just installed Foo_Package version 1.0.0, then this command
589
590     # pkg_info -L foopackage-1.0.0 | less
591
592 will show all the files installed by the package. Pay special attention to files in `man/` directories, which will be manual pages, `etc/` directories, which will be configuration files, and `doc/`, which will be more comprehensive documentation. If you are not sure which version of the application was just installed, a command like this
593
594       
595
596     pkg_info | grep -i foopackage
597
598   
599 will find all the installed packages that have <i>foopackage</i> in the package name. Replace <i>foopackage</i> in your command line as necessary.
600
601
602 Once you have identified where the application's manual pages have been installed, review them using [man(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=man&section=1). Similarly, look over the sample configuration files, and any additional documentation that may have been provided.
603
604
605 If the application has a web site, check it for additional documentation, frequently asked questions, and so forth. If you are not sure of the web site address it may be listed in the output from
606
607       
608
609     # pkg_info foopackage-1.0.0
610
611   
612 A `WWW:` line, if present, should provide a URL for the application's web site.
613
614
615 Packages that should start at boot (such as Internet servers) will usually install a sample script in `/usr/pkg/etc/rc.d`. You should review this script for correctness and edit or rename it if needed.
616
617
618
619
620
621
622 ## Dealing with Broken Packages 
623
624
625
626 If you come across a package that does not work for you, there are a few things you can do, including:
627
628
629
630   1. Fix it! The [pkgsrc Guide](http://www.netbsd.org/Documentation/pkgsrc/) includes detailed information on the ***pkgsrc®*** infrastructure so that you can fix the occasional broken package or even submit your own!
631
632   1. Gripe--***by email only***! Send email to the maintainer of the package first. Type `bmake maintainer` or read the `Makefile` to find the maintainer's email address. Remember to include the name and version of the port (send the `$NetBSD:` line from the `Makefile`) and the output leading up to the error when you email the maintainer. If you do not get a response from the maintainer, you can try [users](http://leaf.dragonflybsd.org/mailarchive/) .
633
634   1. Grab the package from an FTP site near you. The ***master*** package collection is on `packages.stura.uni-rostock.de` in the [All directory](ftp://packages.stura.uni-rostock.de/pkgsrc-current/DragonFly/RELEASE/i386/All/). These are more likely to work than trying to compile from source and are a lot faster as well. Use the [pkg_add(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_add&section=1) program to install the package on your system.
635
636
637
638
639