Clean up
[ikiwiki.git] / docs / howtos / HowToPkgsrc.mdwn
0e759494 1# pkgsrc on DragonFly
b790f880 2
70d69e8b 3DragonFly uses a specially crafted Makefile in /usr and a git mirror
4of the official pkgsrc repository to make pkgsrc distribution more user-friendly.
226e0836 5
6The basics of the pkgsrc system can be found in NetBSD's [Pkgsrc Guide](, and can be considered the canonical resource.
cf1e9a79 8
fbfe8925 9[[!toc levels=3 ]]
0e759494 10
11## Overview
cf1e9a79 12
13### History
670d4043 14[Pkgsrc]( 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.
b790f880 15
cf1e9a79 16### Overview
10f56950 18The 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.
cf1e9a79 19
20Pkgsrc 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.
22 **Binary Package Benefits**
24* A compressed package tarball is typically smaller than the compressed tarball containing the source code for the application.
26* 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.
28* Packages do not require any understanding of the process involved in compiling software on DragonFly.
31**Pkgsrc source Benefits**
34* 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.
36* 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.
38* The licensing conditions of some software distributions forbid binary distribution. They must be distributed as source code.
40* 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.
42* If you have local patches, you will need the source in order to apply them.
10f56950 44* Some people like having code around, so they can read it if they get bored, hack it, debug crashes, borrow from it (license permitting, of course), and so on.
cf1e9a79 45
10f56950 46To keep track of pkgsrc releases subscribe to the [NetBSD pkgsrc users mailing list]( and the [NetBSD pkgsrc users mailing list]( It's also useful to watch the [DragonFly User related mailing list]( as errors with pkgsrc on DragonFly should be reported there.
cf1e9a79 47
48 **Warning:** Before installing any application, you should check for security issues related to your application.
50Audit-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.
28a42a9d 52**Note:** Binary packages and source packages are effectively the same software and can be manipulated with the same pkg_* tools.
54## Installing pkgsrc
670d4043 56The 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.
b790f880 57
c2939664 58Set GITHOST in /etc/make.conf or set it as an environment variable to select a different download location, if desired. See mirrors page for available mirrors.
67c26dc0 59
10f56950 60This downloads the stable version of the pkgsrc tree from the default mirror, if you didn't set GITHOST. As root:
b790f880 61
b790f880 62 # cd /usr
7cbb018c 63 # make pkgsrc-create
b790f880 64
7cbb018c 65to fetch the intial pkgsrc repository from the net, or
b790f880 66
67 # cd /usr
68 # make pkgsrc-update
70to update.
104e5928 72**Note**: If your DragonFly install is not up to date, you might have ended up with an old release of the pkgsrc tree.
74 # cd /usr/pkgsrc
75 # git branch
77will show what release you are on. See Tracking the stable branch for more information.
21111be0 79### Tracking the stable branch
cf1e9a79 80
9c57941a 81There 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.
67c26dc0 82
4dbe296a 83To see the available remote branches:
cf1e9a79 84
ca873322 85 # cd /usr/pkgsrc
4dbe296a 86 # git pull
ca873322 87 # git branch -r
cf1e9a79 88
21111be0 89To create a local branch, tracking the remote quarterly release:
cf1e9a79 90
ca873322 91 # cd /usr/pkgsrc
92 # git branch pkgsrc-2010Q4 origin/pkgsrc-2010Q4
cf1e9a79 93
104e5928 94Branch naming format is 'pkgsrc-YYYYQX', where YYYY is the year and QX is quarters 1-4 of the year. Check []( to see the name of the latest stable branch.
cf1e9a79 95
21111be0 96After adding a new branch, it can be downloaded with:
cf1e9a79 97
ca873322 98 # cd /usr/pkgsrc
99 # git checkout pkgsrc-2010Q4
100 # git pull
cf1e9a79 101
a9f482bf 102## Dealing with pkgsrc packages
cf1e9a79 103
a9f482bf 104The following section explains how to find, install and remove pkgsrc packages.
106### Finding Your Application
cf1e9a79 107
a9f482bf 108Before 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:
cf1e9a79 109
a9f482bf 110Since DragonFly 1.11 [pkg_search(1)]( is included in the base system. [pkg_search(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)]( file.
cf1e9a79 111
112 # pkg_search fvwm
113 fvwm-2.4.20nb1 Newer version of X11 Virtual window manager
114 fvwm-2.5.24 Development version of X11 Virtual window manager
115 fvwm-themes-0.6.2nb8 Configuration framework for fvwm2 with samples
116 fvwm-wharf-1.0nb1 Copy of AfterStep's Wharf compatible with fvwm2
117 fvwm1-1.24rnb1 Virtual window manager for X
119 # pkg_search -v fvwm-2.5
120 Name : fvwm-2.5.24-50
121 Dir : wm/fvwm-devel
122 Desc : Development version of X11 Virtual window manager
123 URL : any
124 Deps : perl>#5.0 gettext-lib>0.14.5 [...]
126Its also possible to issue the command
128 # cd /usr/pkgsrc/
129 # bmake search key='package you are looking for'
a9f482bf 131from the `/usr/pkgsrc` directory.
cf1e9a79 132
a9f482bf 133It's also possible to browse website that show all the available pkgsrc packages, such as []( .
1cd7a23a 134
28a42a9d 135### Installing applications
137Downloading 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.
139The `bin-install` target on DragonFly (with pkgsrc from 2011/02/07 and later) will do just that:
141 # cd /usr/pkgsrc/misc/screen
142 # bmake bin-install clean
144This will download and install the appropriate `screen` binary package if it exists, and try building from source if it can't complete the download.
146### Installing applications, source only
1cd7a23a 147
a9f482bf 148Packages 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.
b790f880 149
150 # cd /usr/pkgsrc/misc/screen
151 # bmake install clean
670d4043 153To find out the options that can affect how a program is built:
b790f880 154
155 # bmake show-options
670d4043 157To change options:
b790f880 158
159 # bmake PKG_OPTIONS.<package_name>="-option1 option2" install clean
670d4043 161Listing an option enables it. Listing an option with a "-" before it disables the option.
b790f880 162
a9f482bf 163To make these option changes permanent for every future build or upgrade of this package, put a similar line in `/usr/pkg/etc/mk.conf`:
165 . PKG_OPTIONS.<package_name>=-option1 option2
28a42a9d 167### Installing applications, binary only
b790f880 168
a9f482bf 169Binary packages can be installed using *pkg_radd*:
b790f880 170
670d4043 171 # pkg_radd screen
b790f880 172
2e8be716 173This 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.
b790f880 174
2e8be716 175You can manually set `BINPKG_BASE` and use *pkg_add* to get the same effect, using a different server.
b790f880 176
2e8be716 177 # setenv BINPKG_BASE
670d4043 178 # pkg_add screen
b790f880 179
28a42a9d 180
2e8be716 181#### Issues with pre-built packages
b790f880 182
2e8be716 183* The default remote repository for binary packages tracks quarterly pkgsrc releases, so your local install of pkgsrc should be the same quarterly release.
184* 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.
185* 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.
b790f880 186
b790f880 187
0e759494 188### List all installed applications
670d4043 189
190To obtain a list of all the packages that are installed on your system:
b790f880 191
192 # pkg_info
2e8be716 194To 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:
b790f880 195
196 # pkg_info | grep xorg
a9f482bf 198### Removing packages
b790f880 199
cf1e9a79 200If a program was installed as a package:
b790f880 201
cf1e9a79 202 # pkg_delete packagename
b790f880 203
cf1e9a79 204If a package was installed from the source files, you can also change to the directory they were installed from and issue the command:
b790f880 205
cf1e9a79 206 # bmake deinstall
b790f880 207
c1e30046 208Note that these methods are effectively interchangeable. Either will work whether the package was originally installed from source or binary.
a9f482bf 210#### Remove associated files needed for building a package
b790f880 211
cf1e9a79 212To remove the work file from building a package, and the package's dependencies:
b790f880 213
cf1e9a79 214 # bmake clean clean-depends
670d4043 215
cf1e9a79 216This can be combined with other steps:
b790f880 217
cf1e9a79 218 # bmake install clean clean-depends
b790f880 219
cf1e9a79 220## Upgrading packages
b790f880 221
30ceb822 222There'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.
224### Update pkgsrc system packages
226**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.
228 # cd /usr/pkgsrc/devel/bmake
2822e5b0 229 or
b734238f 230 # cd /usr/pkgsrc/pkgtools/pkg_install
2822e5b0 231 or
b734238f 232 # cd /usr/pkgsrc/pkgtools/bootstrap-mk-files
2822e5b0 233
30ceb822 234 # env USE_DESTDIR=yes bmake package
235 # bmake clean-depends clean
237And go to the packages directory and install the binary package with
239 # cd /usr/pkgsrc/packages/All
240 # pkg_add -u <pkg_name> (i.e. the name of the .tgz file).
b790f880 242
f5e66381 243### bmake replace
244Performed in the `/usr/pkgsrc` directory that correlates with the installed package, the software is first built and then replaced.
246 # cd /usr/pkgsrc/chat/ircII
247 # bmake replace
cf1e9a79 249### pkg_rolling-replace
b790f880 250
30ceb822 251*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.
b790f880 252
cf1e9a79 253 # cd /usr && make pkgsrc-update
254 # pkg_rolling-replace -u
b790f880 255
cf1e9a79 256### pkgin
b790f880 257
a9f482bf 258Downloads 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.
fa94fcaa 259
cf1e9a79 260 # pkgin update
261 # pkgin full-upgrade
fa94fcaa 262
cf1e9a79 263### pkg_chk
b790f880 264
a9f482bf 265It 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.
b790f880 266
a9f482bf 267 # pkg_chk -g # make initial list of installed packages
cf1e9a79 268 # pkg_chk -r # remove all packages that are not up to date and packages that depend on them
269 # pkg_chk -a # install all missing packages (use binary packages, this is the default)
270 # pkg_chk -as # install all missing packages (build from source)
b790f880 271
cf1e9a79 272The 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.
b790f880 273
cf1e9a79 274### pkg_add -u
b790f880 275
cf1e9a79 276Point at a local or online binary archive location to download and update packages.
b790f880 277
d3b97f72 278### rpkgmanager
849487e3 280This requires that you've set up rpkgmanager first. Read more about rpkgmanager [[here|docs/howtos/rpkgmanager/]].
d3b97f72 281
849487e3 282 # yes | rpkgmanager.rb
d3b97f72 283
a9f482bf 284## Start pkgsrc applications on system startup
286Packages 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:
b790f880 287
1cd7a23a 288 RCD_SCRIPTS_DIR=/etc/rc.d
b790f880 290
0e759494 291This 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`.
a9f482bf 292
293Many other options can be set in this file; see `/usr/pkgsrc/mk/defaults/mk.conf` for examples.
295## Miscellaneous topics
297### Post-installation Activities
299After 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.
300 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:
302Use [pkg_info(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
304 # pkg_info -L foopackage-1.0.0 | less
306will 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
308 # pkg_info | grep -i foopackage
2e8be716 310will find all the installed packages that have *foopackage* in the package name. Replace *foopackage* in your command line as necessary.
a9f482bf 311
312Once you have identified where the application's manual pages have been installed, review them using [man(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
314 # pkg_info foopackage-1.0.0
a9f482bf 316A `WWW:` line, if present, should provide a URL for the application's web site.
318### Dealing with Broken Packages
320If you come across a package that does not work for you, there are a few things you can do, including:
322 1. Fix it! The [pkgsrc Guide]( includes detailed information on the ***pkgsrc®*** infrastructure so that you can fix the occasional broken package or even submit your own!
324 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]( .
b790f880 325
a9f482bf 326 1. Grab a pre-built package from an [[mirror|mirrors]] site near you.
07601fb9 327
a9f482bf 328### What is WIP?
b790f880 329
40741f0e 330Packages that can be built within the pkgsrc framework but are not yet necessarily ready for production use can be found in []( These packages need to be downloaded separately; check the website for details. Packages in this collection are in development and may not build successfully.
b790f880 331
a9f482bf 332### Links
b790f880 333
83f36747 334* More information: The pkgsrc guide [](
b790f880 335
83f36747 336* Web interface for searching packages: [](
b790f880 337
83f36747 338* Ways to upgrade packages [](
b5456305 339
1cd7a23a 340* To search and/or report bugs against packages in pkgsrc, look at []( - use category 'pkg'.
b790f880 341
1cd7a23a 342* The #pkgsrc IRC channel on Freenode
b790f880 343
1cd7a23a 344* The #dragonflybsd IRC channel on EFnet