87bc7bb02234e9f0389a78796d0bd8e48bd67c8f
[ikiwiki.git] / docs / howtos / HowToPkgsrc.mdwn
1 # pkgsrc on DragonFly
2
3 DragonFly uses a specially crafted Makefile in /usr and a git mirror
4 of the official pkgsrc repository to make pkgsrc distribution more user-friendly.
5
6 The basics of the pkgsrc system can be found in NetBSD's [Pkgsrc Guide](http://www.netbsd.org/docs/pkgsrc/), and can be considered the canonical resource.
7
8
9 [[!toc levels=3 ]]
10
11 ## Overview 
12
13 ### History 
14 [Pkgsrc](http://www.pkgsrc.org) is a packaging system that was originally created for NetBSD. It has been ported to DragonFly, along with other operating systems.  Pkgsrc is very similar to FreeBSD's ports mechanism.
15
16 ### Overview
17
18 If you have used a UNIX® system before you will know that the typical procedure for installing third party software goes something like this:
19
20   1. Download the software, which might be distributed in source code format, or as a binary.
21
22   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)).
23
24   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.
25
26   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.
27
28   1. Test and install the software.
29
30 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 10,000 third party applications have been made available in this way.
31
32 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. Installing a new application can be carried out with a single command.
33
34 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.
35
36 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.
37
38  **Binary Package Benefits** 
39
40 * A compressed package tarball is typically smaller than the compressed tarball containing the source code for the application.
41
42 * 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.
43
44 * Packages do not require any understanding of the process involved in compiling software on DragonFly.
45
46
47 **Pkgsrc source Benefits** 
48
49
50 * 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.
51
52 * 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.
53
54 * The licensing conditions of some software distributions forbid binary distribution. They must be distributed as source code.
55
56 * 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.
57
58 * If you have local patches, you will need the source in order to apply them.
59
60 * 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.
61
62 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.
63
64  **Warning:** Before installing any application, you should check http://www.pkgsrc.org/ for security issues related to your application.
65
66 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.
67
68 **Note:** Binary packages and source packages are effectively the same software and can be manipulated with the same pkg_* tools.  
69
70 ## Installing pkgsrc 
71
72 The basic pkgsrc tools are provided with every DragonFly system as part of installation.  However, you still need to download the pkgsrc tree for building applications with these tools.  
73
74 Edit GITHOST in /usr/Makefile or set it as an environment variable to select a different download location, if desired. See mirrors page for available mirrors.
75
76 This downloads the stable version of the pkgsrc tree. As root:
77
78     # cd /usr
79     # make pkgsrc-create
80
81 to fetch the intial pkgsrc repository from the net, or
82
83     # cd /usr
84     # make pkgsrc-update
85
86 to update.
87
88 **Note**: If your DragonFly install is not up to date, you might have ended up with an old release of the pkgsrc tree.
89
90     # cd /usr/pkgsrc
91     # git branch
92
93 will show what release you are on. See Tracking the stable branch for more information.
94
95 ### Tracking the stable branch
96
97 There are quarterly releases of pkgsrc that are specifically designed for stability.  You should in general follow these, rather than the bleeding edge pkgsrc. When a new branch is out you need to set up a local branch tracking that one. 'make pkgsrc-update' will not do this for you.
98
99 To see the available remote branches:
100
101     # cd /usr/pkgsrc 
102     # git pull
103     # git branch -r
104
105 To create a local branch, tracking the remote quarterly release:
106
107     # cd /usr/pkgsrc 
108     # git branch pkgsrc-2010Q4 origin/pkgsrc-2010Q4
109
110 Branch naming format is 'pkgsrc-YYYYQX', where YYYY is the year and QX is quarters 1-4 of the year.  Check [pkgsrc.org](http://www.pkgsrc.org/) to see the name of the latest stable branch.
111
112 After adding a new branch, it can be downloaded with:
113
114     # cd /usr/pkgsrc 
115     # git checkout pkgsrc-2010Q4
116     # git pull
117
118 ## Dealing with pkgsrc packages
119
120 The following section explains how to find, install and remove pkgsrc packages.
121
122 ### Finding Your Application 
123
124 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:
125
126 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.
127
128     # pkg_search fvwm
129     fvwm-2.4.20nb1          Newer version of X11 Virtual window manager
130     fvwm-2.5.24             Development version of X11 Virtual window manager
131     fvwm-themes-0.6.2nb8    Configuration framework for fvwm2 with samples
132     fvwm-wharf-1.0nb1       Copy of AfterStep's Wharf compatible with fvwm2
133     fvwm1-1.24rnb1          Virtual window manager for X
134
135     # pkg_search -v fvwm-2.5
136     Name    : fvwm-2.5.24-50
137     Dir     : wm/fvwm-devel                                     
138     Desc    : Development version of X11 Virtual window manager 
139     URL     : any                                               
140     Deps    : perl>#5.0 gettext-lib>0.14.5 [...]
141
142 Its also possible to issue the command
143
144     # cd /usr/pkgsrc/
145     # bmake search key='package you are looking for'
146
147 from the `/usr/pkgsrc` directory.
148
149 It's also possible to browse website that show all the available pkgsrc packages, such as [http://pkgsrc.se/](http://pkgsrc.se) .
150
151 ### Installing applications
152
153 Downloading a binary package is almost always faster than building from source, but not all programs in pkgsrc can be redistributed as a binary.  In most cases, you will want to download a binary package if possible, and otherwise build from source if it's not available.  
154
155 The `bin-install` target on DragonFly (with pkgsrc from 2011/02/07 and later) will do just that:
156
157     # cd /usr/pkgsrc/misc/screen
158     # bmake bin-install clean
159
160 This will download and install the appropriate `screen` binary package if it exists, and try building from source if it can't complete the download.
161
162 ### Installing applications, source only
163
164 Packages are built by going into the appropriate directory and issuing `bmake install clean`. For example, to build the *screen* package you need to issue the following commands.
165
166     # cd /usr/pkgsrc/misc/screen
167     # bmake install clean
168
169 To find out the options that can affect how a program is built:
170
171     # bmake show-options
172
173 To change options:
174
175     # bmake PKG_OPTIONS.<package_name>="-option1 option2" install clean
176
177 Listing an option enables it.  Listing an option with a "-" before it disables the option.
178
179 To make these option changes permanent for every future build or upgrade of this package, put a similar line in `/usr/pkg/etc/mk.conf`:
180
181      . PKG_OPTIONS.<package_name>=-option1 option2
182     
183 ### Installing applications, binary only
184
185 Binary packages can be installed using *pkg_radd*:
186
187     # pkg_radd screen
188
189 This program works by setting the `PKG_PATH` environment variable to the appropriate path for the operating system and architecture to a remote repository of binary packages, and then using *pkg_add* to get packages. This will install most packages, but will not upgrade packages that are already installed.
190
191 You can manually set `BINPKG_BASE` and use *pkg_add* to get the same effect, using a different server.
192
193     # setenv BINPKG_BASE http://mirror-master.dragonflybsd.org/packages
194     # pkg_add screen
195
196
197 #### Issues with pre-built packages
198
199 * The default remote repository for binary packages tracks quarterly pkgsrc releases, so your local install of pkgsrc should be the same quarterly release.
200 * Some packages are not licensed for distribution in binary form, so they may be able to build on DragonFly but won't be available with *pkg_radd*.  If it fails, try going to that package's directory and install the package manually as described above.
201 * If you upgrade to an new DEVELOPMENT version of DragonFly very early (i.e. shortly after the branch), it might be possible that *pkg_radd* fails to install packages. This is due the fact, that it takes some time to built binary packages and thus, there are no binary packages available on the mirrors yet. Usually you'll see an announcement on the lists once the first packages for DEVELOPMENT are ready.
202
203
204 ### List all installed applications 
205
206 To obtain a list of all the packages that are installed on your system:
207
208     # pkg_info
209
210 To see if certain packages have been installed, filter for the name of the package.  This example will show all *xorg*-related packages currently installed on the system:
211
212     # pkg_info | grep xorg
213
214 ### Removing packages
215
216 If a program was installed as a package:
217
218     # pkg_delete packagename
219
220 If a package was installed from the source files, you can also change to the directory they were installed from and issue the command:
221
222     # bmake deinstall
223
224 Note that these methods are effectively interchangeable.  Either will work whether the package was originally installed from source or binary.
225
226 #### Remove associated files needed for building a package 
227
228 To remove the work file from building a package, and the package's dependencies:
229
230     # bmake clean clean-depends
231
232 This can be combined with other steps:
233
234     # bmake install clean clean-depends
235
236 ## Upgrading packages 
237
238 There's a number of ways to upgrade pkgsrc; some of these are built in and some are packages installable with pkgsrc.  This list is not necessarily comprehensive.
239
240 ### Update pkgsrc system packages
241
242 **Note**: Sometimes basic pkgsrc tools; *bmake*, *pkg_install* and *bootstrap-mk-files* need to be upgraded.  However, they can't be deleted and replaced since you need that tool to accomplish replacement.  The solution is to build a separate package before deletion, and install that package. 
243
244     # cd /usr/pkgsrc/devel/bmake
245     or
246     # cd /usr/pkgsrc/pkgtools/pkg_install
247     or 
248     # cd /usr/pkgsrc/pkgtools/bootstrap-mk-files
249     
250     # env USE_DESTDIR=yes bmake package
251     # bmake clean-depends clean
252
253 And go to the packages directory and install the binary package with
254
255     # cd /usr/pkgsrc/packages/All
256     # pkg_add -u <pkg_name> (i.e. the name of the .tgz file).
257
258
259 ### bmake replace
260 Performed in the `/usr/pkgsrc` directory that correlates with the installed package, the software is first built and then replaced.
261
262     # cd /usr/pkgsrc/chat/ircII
263     # bmake replace
264
265 ### pkg_rolling-replace
266
267 *pkg_rolling-replace* replaces packages one by one and you can use it for a better way of package management. Actually it does `bmake replace` on one package at a time, sorting the packages being replaced according to their interdependencies, which avoids most duplicate rebuilds. Once *pkg_rolling-replace* is installed you can update the packages through the following steps.
268
269     # cd /usr && make pkgsrc-update
270     # pkg_rolling-replace -u
271
272 ### pkgin
273
274 Downloads and installs binary packages.  Check the [[mirrors]] page for sites carrying binary packages to use with pkgin. You can run the following commands to get the packages updated. This assumes that *pkgin* is already configured. Please consult the documentation and the man page on how to do so.
275
276     # pkgin update
277     # pkgin full-upgrade 
278
279 ### pkg_chk
280
281 It updates packages by removing them and rebuilding them.  Warning: programs are unavailable until a rebuild finishes.  If they don't rebuild, it won't work. *pkg_chk* requires a few steps in order to work correctly. They are listed here.
282
283     # pkg_chk -g  # make initial list of installed packages
284     # pkg_chk -r  # remove all packages that are not up to date and packages that depend on them
285     # pkg_chk -a  # install all missing packages (use binary packages, this is the default)
286     # pkg_chk -as # install all missing packages (build from source)
287
288 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. 
289
290 ### pkg_add -u
291
292 Point at a local or online binary archive location to download and update packages.
293
294 ### rpkgmanager
295
296 This requires that you've set up rpkgmanager first. Read more about rpkgmanager [[here|docs/howtos/rpkgmanager/]].
297
298     # yes | rpkgmanager.rb
299
300 ## Start pkgsrc applications on system startup
301
302 Packages often install rc.d scripts to control software running on startup.  To specify where the rc.d scripts from the installed packages should go, add the following lines to your `/usr/pkg/etc/mk.conf` file:
303
304     RCD_SCRIPTS_DIR=/etc/rc.d
305     PKG_RCD_SCRIPTS=YES
306
307 This option can be set in the environment to activate it for binary packages.  These packages will still have to be enabled in `/etc/rc.conf/` to run at boot.  If these options aren't set, the rc file will be placed in `/usr/pkg/share/examples/rc.d/` and will need to be manually copied over to `/etc/rc.d`.
308
309 Many other options can be set in this file; see `/usr/pkgsrc/mk/defaults/mk.conf` for examples.
310
311 ## Miscellaneous topics
312
313 ### Post-installation Activities 
314
315 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.
316  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:
317
318 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
319
320     # pkg_info -L foopackage-1.0.0 | less
321
322 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
323
324     # pkg_info | grep -i foopackage
325
326 will find all the installed packages that have *foopackage* in the package name. Replace *foopackage* in your command line as necessary.
327
328 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. 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
329
330     # pkg_info foopackage-1.0.0
331
332 A `WWW:` line, if present, should provide a URL for the application's web site.
333
334 ### Dealing with Broken Packages 
335
336 If you come across a package that does not work for you, there are a few things you can do, including:
337
338   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!
339
340   1. 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/) .
341
342   1. Grab a pre-built package from an [[mirror|mirrors]] site near you. 
343
344 ### What is WIP? 
345
346 Packages that can be built within the pkgsrc framework but are not yet necessarily ready for production use can be found in [http://pkgsrc-wip.sourceforge.net](http://pkgsrc-wip.sourceforge.net).  These packages need to be downloaded separately; check the website for details.  Packages in this collection are in development and may not build successfully.
347
348 ### Links
349
350 * More information: The pkgsrc guide [http://www.netbsd.org/Documentation/pkgsrc/](http://www.netbsd.org/Documentation/pkgsrc/)
351
352 * Web interface for searching packages: [http://www.pkgsrc.se](http://www.pkgsrc.se)
353
354 * Ways to upgrade packages [http://wiki-static.aydogan.net/How_to_upgrade_packages](http://wiki-static.aydogan.net/How_to_upgrade_packages)
355
356 * To search and/or report bugs against packages in pkgsrc, look at [http://www.netbsd.org/support/send-pr.html](http://www.netbsd.org/support/send-pr.html) - use category 'pkg'.
357
358 * The #pkgsrc IRC channel on Freenode
359
360 * The #dragonflybsd IRC channel on EFnet