(no commit message)
[ikiwiki.git] / docs / howtos / HowToPkgsrc.mdwn
1 [[!toc levels=3 ]]�
2 ## History and Overview 
3 Pkgsrc (http://www.pkgsrc.org) is a packaging system that was originally created by NetBSD (http://www.netbsd.org). It has also been ported to DragonFly, and many of the applications that are currently supported by pkgsrc are in the process of being built.
4
5 Pkgsrc is very alike to FreeBSD's ports mechanism, which was in use under NetBSD before pkgsrc, and is also used in OpenBSD and MirBSD.
6
7 ## Installing pkgsrc 
8
9 In order for pkgsrc to be able to install applications, it must first be "bootstrapped" on the machine it is to run. This is basically equivalent to building the applications it requires to use. Since the 1.4 release, a 
10 binary bootstrap is provided with the system. However, you still need to download the pkgsrc tree if you
11 want to build any applications. This can be done in one of two ways: through NetBSD's anonymous CVS access; or by downloading the pkgsrc tarball, which is updated weekly.
12
13 ### Quick & Dirty Way 
14
15 As of the 1.10 release, you can use the UsrMakefile to checkout & update the pkgsrc tree quickly.
16
17 as root:
18
19     # cd /usr
20     # make pkgsrc-create
21
22 to fetch the intial pkgsrc repository from the net, or
23
24     # cd /usr
25     # make pkgsrc-update
26
27 to update.
28
29 Please do edit the makefile to use an appropriately speedy CVS mirror for your location and to reduce
30 load on the main pkgsrc cvs server.
31
32 ### 'Custom' Way 
33
34 In those cases where you wish to checkout pkgsrc manually, for example to track a specific pkgsrc branch,
35 a custom checkout may be desired.
36
37 It is almost always faster for a first-time "whole source" checkout to FTP the tarballs and untar them locally because that makes best use of the network link. After that, using cvs checkout/update works to minimize the number of bytes coming over by sending only the changes.
38
39 The commands to fetch and install the tarball:
40
41     # fetch -o /tmp/pkgsrc.tar.gz ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc.tar.gz
42     # cd /usr; tar -xzf /tmp/pkgsrc.tar.gz; chown -R root:wheel pkgsrc
43
44
45 The commands to install via CVS:
46
47     # cd /usr
48     # cvs -d anoncvs@anoncvs.us.netbsd.org:/cvsroot co pkgsrc
49
50 *Note*, you will have to be root in order for this to work.
51
52 Please check [NetBSD anoncvs mirrors](http://www.netbsd.org/mirrors/#anoncvs) for faster server.
53
54 Either of these command sets will download the pkgsrc source tree to your local machine into the /usr/pkgsrc directory.
55
56 If you wish to perform your own bootstrap of pkgsrc (not needed since the 1.4 release), for example
57 to customize some of the pkgsrc default settings, use the following commands:
58
59     # cd /usr/pkgsrc/bootstrap
60     # ./bootstrap --pkgdbdir /var/db/pkg --prefix /usr/pkg
61
62 The directory you pass in for pkgdbdir will contain the list of applications you have installed on the system. The directory you supply to prefix is used as the root path for the applications you installed. The ports/packages of FreeBSD used a pkgdbdir of /var/db/pkg and a prefix of /usr/local. However, the ports system is deprecated for DragonFly and prebuilt packages will assume /var/db/pkg; so it is not recommended that the pkgdbdir be changed or that pkgsrc packages be used in combination with FreeBSD packages unless you really know what you are doing.
63
64 Note: The 1.4 errata http://www.dragonflybsd.org/community/errata1_4.cgi contains an example /etc/mk.conf file. It is recommend that you use that file instead of the ones generated by the following step on a 1.4 system.
65
66 After the bootstrapping tools have been built, there will be a sample mk.conf file based on your system settings. This should be copied to /etc. The command for this is:
67
68     # cp work/mk.conf.example /usr/pkg/etc/mk.conf
69
70 You are also strongly recommended to adjust the default path on your DragonFly machine to reflect the location of the bootstrapping tools. This is imperative as the program that makes/installs ports/packages from Free/DragonFly BSD are not compatible with pkgsrc (and vice-versa). To do this, you will need to add both /usr/pkg/bin and /usr/pkg/sbin to the front of your PATH environment variable. This is usually done by going to the line of your shell's startup configuration file and adding the appropriate directories to the front of the PATH line. It is also recommened that you adjust the appropriate files in /usr/share/skel/ so future users will also have to correct settings. After you have edited these files, you will need to get your shell to re-read the configurations. This is done by either calling source/export on the appropriate file, or by logging out and then back in.
71
72 Note: This path alteration step is still required on a 1.4_REL CD
73
74 ## Building packages 
75 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.
76
77     # cd /usr/pkgsrc/misc/screen
78     # bmake install clean
79
80 The above bmake command will build the package with its default compile-time options. Before building a package it is wise to first find out what compile-time options that package supports. To do this, use this bmake command.
81
82     # bmake show-options
83
84 This will return back a message similar to the following...
85
86     Any of the following general options may be selected:
87       option1
88       option2 Option2 description
89       option3 Option3 description
90     These options are enabled by default:
91      option1
92     These options are currently enabled:
93  option3
94
95 If you are happy with the defaults, type bmake install clean. However, if you wish to make a change, you need to issue a make command similar to the following:
96
97     # bmake PKG_OPTIONS.<package_name>="-option1 option2" install clean
98
99 A minus sign '-' before an option removes that option from the compilation. To enable an option, you should list just the option name. <package_name> should be substituted with name of the package you are installing, 'screen' for this example.
100
101 To add these to the /usr/pkg/etc/mk.conf (the file pkgsrc uses to track which options to enable during a build), you would insert a line similar to:
102
103      . PKG_OPTIONS.<package_name>=-option1 option2
104     
105     If you want to install and create binary packages (default location of built binary package is in /usr/pkgsrc/packages/All) which can then be later installed to another machine. issue the following commands.
106     
107     # cd /usr/pkgsrc/misc/screen
108     # bmake package clean
109
110 Packages are usually placed into an appropriate category. To find out where the package you are seeking to build is located, try this command:
111
112     # cd /usr/pkgsrc/
113     # bmake search key='NameOfPackageYouWishToFind'
114
115 ## Pre-built pkgsrc packages 
116 The pkgsrc section of the download page (http://www.dragonflybsd.org/main/download.cgi) contains a list of sites providing binary packages.
117
118 Binary packages can be installed either by using the full URL
119
120     # pkg_add ftp://packages.stura.uni-rostock.de/pkgsrc-current/DragonFly/DEVELOPMENT/i386/All/xorg-6.8.2nb1.tgz
121
122
123 or by setting PKG_PATH (example for csh)
124
125     # setenv PKG_PATH ftp://packages.stura.uni-rostock.de/pkgsrc-current/DragonFly/DEVELOPMENT/i386/All
126     # pkg_add xorg
127
128 Also note that the version can be omitted, in which case the newest package will be chosen.
129
130 ## Other pkgsrc commands 
131 This section will cover the commands in pkgsrc that will allow a user to perform the suggested action.
132
133 ### Get latest list of packages 
134 To update the pkgsrc source hierarchy, you need to first change to the directory where you checked out the pkgsrc tree. Then, issue the command:
135
136     # cvs up -dP
137
138 This will instruct the CVS program to download the latest version of pkgsrc from NetBSD. This will also update all of pkgsrc's build skeleton files. If you installed the pkgsrc from the tarball, you will need to manually download and extract new versions.
139
140 There's also a RSS feed "NetBSD - Fresh Packages" available: http://www.netbsd.org/Changes/rss-netbsd-pkgs.xml
141
142 ### Tracking the stable branch 
143
144 If you don't want to go to the lastest, but get "actual" applications, you can track the stable branch. There are four releases per year; you can get the latest stable release from ["pkgsrc site"](http://www.pkgsrc.org) (www.pkgsrc.org), or you can update your pkgsrc directory:
145
146     # cd /usr/pkgsrc
147     # cvs up -rpkgsrc-200XQY -dPA
148
149 Where 'X' is the year and 'Y' is the revision, with a number from 1 to 4 (for example -rpkgsrc-2006Q2).
150
151 The stable branch will update the buggy applications, so update it frequently.
152
153 More information in the official documentation: ["uptodate-cvs"](http://www.netbsd.org/Documentation/pkgsrc/getting.html#uptodate-cvs)  (www.netbsd.org/Documentation/pkgsrc/getting.html#uptodate-cvs)
154
155 ### List all installed packages 
156 To obtain a list of all the packages that are installed on your system, the user can perform the following command:
157
158     # pkg_info
159
160 The output from pkg_info can also be piped to other commands such as more/less, and grep. The latter is useful to see which version of a particular package has been installed. For example:
161
162     # pkg_info | grep xorg
163
164 will return a list of all the xorg related packages installed on the system.
165
166 ### Search available packages 
167 Packages can be found using one of two ways. You can issue the command
168
169     # bmake search key='package you are looking for'
170
171 from the /usr/pkgsrc directory.
172
173 There is also the pkglocate tool that comes with pkgsrc. It is invoked in the following manner:
174
175     # /usr/pkgsrc/pkglocate 'package name'
176
177 You can also utilize the UNIX file finding commands (whereis, locate, or find).
178
179 ### Upgrade all Installed packages 
180
181 Note: Up to date information about this can be found in this web page: http://wiki.netbsd.se/index.php/How_to_upgrade_packages
182
183 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:
184
185 Make initial list of installed packages:
186
187     # pkg_chk -g
188
189 Remove all packages that are not up to date and packages that depend on them:
190
191     # pkg_chk -r
192
193 Install all missing packages (use binary packages, this is the default):
194
195     # pkg_chk -a
196
197 Install all missing packages (build from source):
198
199     pkg_chk -as
200
201 If you want to see a list of upgradeable packages, you can use the pkglint tool. Install the package pkgtools/pkglint and do a:
202
203     lintpkgsrc -i
204
205 It will list the packages, which could be updated.
206
207
208 ### Quick binary upgrades with pkgsrc 
209 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.
210
211 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:
212
213 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.
214
215     
216     pkg_chk -P ftp://binary/url -abg 
217
218 This command downloads all the binary packages needed to upgrade pkgsrc.
219
220     
221     pkg_chk -P ftp://binary/url -abf  
222
223 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.
224
225     
226     pkg_chk -P /wherever/previous/step/put/binaries -abu 
227
228
229 Note that ftp://binary/url represents the URL to an online binary pkgsrc repository, such as in the PKG_PATH example on this page.
230
231 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.
232
233 ## Deinstall a package 
234 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:
235
236     # bmake deinstall
237
238 ### Remove associated files needed for building a package 
239 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.
240
241 ## Additional mk.conf notes 
242 To specify where the rc.d scripts from the installed packages should go:
243
244     RCD_SCRIPTS_DIR=/etc/rc.d
245
246 To enable the automatic installation of rc.d scripts into the $RCD_SCRIPTS_DIR directory:
247
248     PKG_RCD_SCRIPTS=YES
249
250 This option can be set in the environment to activate it for binary packages.
251
252 If you have already partially downloaded a file, this option makes it resume the transfer:
253
254     PKG_RESUME_TRANSFERS=YES
255
256 If the checksum is not correct, automatically download from the next download site:
257
258     FAILOVER_FETCH=YES
259
260 To enable suffixing work directories with the machine's hostname (needed for PKGSRC_LOCKTYPE):
261
262     OBJHOSTNAME=
263
264 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)):
265  
266     PKGSRC_LOCKTYPE=sleep
267
268 To enable sending of MESSAGE file upon installation of a package to a specific user:
269
270     PKGSRC_MESSAGE_RECIPIENTS=username
271
272 To clean easly the dependencies after compiling:
273
274     CLEANDEPENDS=YES
275
276 ## Speed up compilation with ccache 
277 It is possible to speed up the recompilation of packages by using ccache.
278 The first thing is to install ccache:
279
280     # cd /usr/pkgsrc/devel/ccache && bmake install
281
282 To use it the PKGSRC_COMPILER option must be set in your mk.conf must be set:
283
284     PKGSRC_COMPILER = ccache gcc # if you are using gcc
285
286 It's also a good idea to set a high enough size for your cache:
287     
288     # ccache -M 5G
289
290 More infomration can be found in [ccaches manual page](http://ccache.samba.org/ccache-man.html) and the [pkgsrc Guide](http://www.netbsd.org/docs/pkgsrc/configuring.html#selecting-the-compiler).
291
292 ## Where is my http://pkgsrc.se/wip dir? 
293 [[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.
294
295 ## Where to go for more help 
296
297 * The NetBSD pkgsrc developers have a lot of pkgsrc documentation on this website (http://www.netbsd.org/Documentation/pkgsrc/).
298
299
300 * To find packages or updates, look at http://www.pkgsrc.se.
301
302
303 * To query and/or report bugs against packages in pkgsrc, look at http://www.netbsd.org/support/send-pr.html category 'pkg'.
304
305
306 * To get and update wip, look at http://pkgsrc-wip.sourceforge.net.
307
308
309 * This wiki has a list of some quick pkgsrc hacks to get the one or the other package building.
310
311
312 * The pkgsrc IRC channel on Freenode (http://www.freenode.net) (#pkgsrc) is another resource for pkgsrc users and devleopers.
313
314
315 * The DragonFlyBSD IRC channel on EFnet (http://www.efnet.org) (#dragonflybsd) is frequented by DragonFly users and developers using pkgsrc.
316
317
318 * Google (http://www.google.com/search?q#pkgsrc&sourceidopera&num=0&ie=utf-8&oe=utf-8) also has a wealth of information.
319
320 ----
321 CategoryHowTo