Fixing TOC level
[ikiwiki.git] / docs / howtos / HowToPkgsrc.mdwn
1 [[!toc levels=2 ]]
2
3 ## History and Overview 
4 [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.
5
6 ## Installing pkgsrc 
7
8 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.  
9
10 As root:
11
12     # cd /usr
13     # make pkgsrc-create
14
15 to fetch the intial pkgsrc repository from the net, or
16
17     # cd /usr
18     # make pkgsrc-update
19
20 to update.
21
22 Edit /usr/Makefile to select a different download location, if desired.
23
24 ## Installing packages from source
25 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.
26
27     # cd /usr/pkgsrc/misc/screen
28     # bmake install clean
29
30 To find out the options that can affect how a program is built:
31
32     # bmake show-options
33
34 To change options:
35
36     # bmake PKG_OPTIONS.<package_name>="-option1 option2" install clean
37
38 Listing an option enables it.  Listing an option with a "-" before it disables the option.
39
40 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:
41
42      . PKG_OPTIONS.<package_name>=-option1 option2
43     
44 ## Installing pre-built packages 
45
46 Binary packages can be installed using pkg_radd:
47
48     # pkg_radd screen
49
50 This program works by setting the PKG_PATH enviroment 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.
51
52 You can manually set PKG_PATH and use pkg_add to get the same effect, using a different server.
53
54     # setenv PKG_PATH http://avalon.dragonflybsd.org/packages/i386/DragonFly-2.7/stable
55     # pkg_add screen
56
57 This will install most packages, but will not upgrade packages that are already installed.
58
59 Note that the default remote repository for binary packages tracks quarterly pkgsrc releases, so your local install of pkgsrc should be the same quarterly release.
60
61 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 pkg_radd fails, try going to that package's directory in /usr/pkgsrc and using 'bmake install clean'.
62
63 ### Tracking the stable branch 
64
65 There are quarterly releases of pkgsrc that are specifically designed for stability.  You should in general follow the latest branch, rather than bleeding edge pkgsrc.
66
67 To see the available branches:
68
69     cd /usr/pkgsrc 
70     git branch -r
71
72 To switch to the most recent branch:
73
74     cd /usr/pkgsrc 
75     git branch pkgsrc-2010Q3 origin/pkgsrc-2010Q3
76
77 Branch naming format is 'pkgsrc-YYYYQX', where YYYY is the year and QX is quarters 1-4 of the year.
78
79 After switching to a new branch, it can be downloaded with:
80
81     cd /usr/pkgsrc 
82     git checkout vendor
83     git pull
84
85 ### List all installed packages 
86
87 To obtain a list of all the packages that are installed on your system:
88
89     # pkg_info
90
91 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:
92
93     # pkg_info | grep xorg
94
95 ### Searching available packages 
96
97 Packages can be found using one of two ways. You can issue the command
98
99     # cd /usr/pkgsrc/
100     # bmake search key='package you are looking for'
101
102 from the /usr/pkgsrc directory.
103
104 There is also the pkglocate tool that comes with pkgsrc:
105
106     # /usr/pkgsrc/pkglocate 'package name'
107
108 Normal UNIX file finding commands will work (whereis, locate, or find).
109
110 It's also possible to browse website that show all the available pkgsrc packages, such as [http://pkgsrc.se/](pkgsrc.se)
111
112 ## Upgrading packages 
113
114 Note: Up to date information about this can be found in this web page: http://wiki.netbsd.se/index.php/How_to_upgrade_packages
115
116 pkgsrc comes with a list of utilities that make package management easier. These files are located in /usr/pkgsrc/pkgtools. One of the items in this directory is pkg_chk which is similar to FreeBSD's portupgrade. Some commands that are worth noting while using pkg_chk are:
117
118 Make initial list of installed packages:
119
120     # pkg_chk -g
121
122 Remove all packages that are not up to date and packages that depend on them:
123
124     # pkg_chk -r
125
126 Install all missing packages (use binary packages, this is the default):
127
128     # pkg_chk -a
129
130 Install all missing packages (build from source):
131
132     pkg_chk -as
133
134 If you want to see a list of upgradeable packages, you can use the lintpkgsrc tool. Install the package pkgtools/lintpkgsrc and do a:
135
136     lintpkgsrc -i
137
138 It will list the packages, which could be updated.
139
140
141 ### Quick binary upgrades with pkgsrc 
142 A disadvantage of using pkg_chk is that it deletes old packages before upgrading to newer versions of those packages.  If the upgrades need to be built from source, or downloaded, this makes the packaged software unavailable during the potentially long time of the upgrade.
143
144 A solution is to download binary packages ahead of time and install from those local files, keeping downtime to a minimum.  The steps to accomplish that with pkg_chk are as follows:
145
146 This step creates the pkg_chk.conf file, which lists the packages installed on your system.  This only needs to be run the first time this process is followed.
147
148     
149     pkg_chk -P ftp://binary/url -abg 
150
151 This command downloads all the binary packages needed to upgrade pkgsrc.
152
153     
154     pkg_chk -P ftp://binary/url -abf  
155
156 This final step removes old packages and installs the already-downloaded up-to-date versions.  It is during this step that pkgsrc packages are unavailable.
157
158     
159     pkg_chk -P /wherever/previous/step/put/binaries -abu 
160
161
162 Note that ftp://binary/url represents the URL to an online binary pkgsrc repository, such as in the PKG_PATH example on this page.
163
164 If the first command returns an error, try creating a blank file called 'Makefile' in the directory where these commands are run.  'touch Makefile' will create this empty file.
165
166 ## Removing packages
167 The command pkg_delete will remove any package that has been previously installed on a system. If a package was installed from the source files, you can also change to the directory they were installed from and issue the command:
168
169     # bmake deinstall
170
171 ### Remove associated files needed for building a package 
172 To remove the temporary source/object files that are associated with a package, you can issue the bmake clean command. This can also be performed on the same stage as the installation by using the following make command bmake install clean. The latter is more commonly done for simplicity reasons.
173
174 ## Additional mk.conf notes
175
176 The default location of mk.conf is /usr/pkg/etc
177  
178 To specify where the rc.d scripts from the installed packages should go:
179
180     RCD_SCRIPTS_DIR=/etc/rc.d
181
182 To enable the automatic installation of rc.d scripts into the $RCD_SCRIPTS_DIR directory:
183
184     PKG_RCD_SCRIPTS=YES
185
186 This option can be set in the environment to activate it for binary packages.
187
188 If you have already partially downloaded a file, this option makes it resume the transfer:
189
190     PKG_RESUME_TRANSFERS=YES
191
192 If the checksum is not correct, automatically download from the next download site:
193
194     FAILOVER_FETCH=YES
195
196 To enable suffixing work directories with the machine's hostname (needed for PKGSRC_LOCKTYPE):
197
198     OBJHOSTNAME=
199
200 To enable locking (so that only one process is working on the same package at the same time - sleep means that it should sleep for 5 seconds and try again (5 seconds is by default)):
201  
202     PKGSRC_LOCKTYPE=sleep
203
204 To enable sending of MESSAGE file upon installation of a package to a specific user:
205
206     PKGSRC_MESSAGE_RECIPIENTS=username
207
208 To clean easly the dependencies after compiling:
209
210     CLEANDEPENDS=YES
211
212 ## Where is my http://pkgsrc.se/wip dir? 
213 [[http://pkgsrc.se/wip]] shows some interessting ports, especially if you are into java, but you will not find them in your default pkgsrc dir. Take a look at [[http://pkgsrc-wip.sourceforge.net]], there is a description how to get and update.
214
215 ## Where to go for more help 
216
217 * The NetBSD pkgsrc developers have a lot of pkgsrc documentation on this website (http://www.netbsd.org/Documentation/pkgsrc/).
218
219 * To find packages or updates, look at http://www.pkgsrc.se.
220
221 * To query and/or report bugs against packages in pkgsrc, look at http://www.netbsd.org/support/send-pr.html category 'pkg'.
222
223 * To get and update wip, look at http://pkgsrc-wip.sourceforge.net.
224
225 * The pkgsrc IRC channel on Freenode (http://www.freenode.net) (#pkgsrc) is another resource for pkgsrc users and devleopers.
226
227 * The DragonFlyBSD IRC channel on EFnet (http://www.efnet.org) (#dragonflybsd) is frequented by DragonFly users and developers using pkgsrc.
228
229 There's also a RSS feed "NetBSD - Fresh Packages" available: http://www.netbsd.org/Changes/rss-netbsd-pkgs.xml