418d330b37cfa47da4479c2b39d3ba397624a763
[ikiwiki.git] / docs / handbook / handbook-pkgsrc-sourcetree-using.mdwn
1 ## Using the pkgsrc® Source Tree 
2
3 The following sections provide basic instructions on using the pkgsrc source tree to install or remove programs from your system.
4
5 ### Obtaining the pkgsrc Source Tree 
6
7 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`.
8
9 #### CVS 
10
11 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** .
12
13 Run `cvs`:
14
15     # cd /usr
16     # cvs -d anoncvs@anoncvs.us.netbsd.org:/cvsroot co pkgsrc
17
18  
19 Running the following command later will download and apply all the recent changes to your source tree.
20
21     # cd /usr/pkgsrc
22     # cvs up
23
24   
25 #### The DragonFly Way 
26
27 As of the 1.10 release, you can use the `/usr/Makefile` to checkout & update the pkgsrc tree quickly.
28
29 as root:
30
31
32     # cd /usr
33     # make pkgsrc-checkout
34
35 to checkout, or
36
37
38     # cd /usr
39     # make pkgsrc-update
40
41 to update. **NOTE**: 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.
42
43 ### Installing Packages from Source
44
45 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:
46
47 * A `Makefile`. The `Makefile` contains various statements that specify how the application should be compiled and where it should be installed on your system.
48
49
50 * 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).
51
52
53 * A `files` directory. This directory contains the application specific files that are needed for the programs appropriate run-time configuration.
54
55   This directory may also contain other files used to build the port.
56
57
58 * 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.
59
60
61 * A `DESCR` file. This is a more detailed, often multiple-line, description of the program.
62
63
64 * 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.
65
66
67
68 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/).
69
70
71
72 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. 
73
74 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`:
75
76
77     # cd /usr/pkgsrc
78     # bmake search key="apache2"
79     Extracting complete dependency database.  This may take a while...
80     ....................................................................................................
81     100
82     ....................................................................................................
83     200
84     <Snip />
85     5800
86     ....................................................................................................
87     5900
88     .................................................................................................Reading database file
89     Flattening dependencies
90     Flattening build dependencies
91     Generating INDEX file
92     Indexed 5999 packages
93     <Snip />
94     Pkg:    apache-2.2.6nb2
95     Path:   www/apache22
96     Info:   Apache HTTP (Web) server, version 2
97     Maint:  tron@NetBSD.org
98     Index:  www
99     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 
100     {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
101     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
102     Arch:   any
103
104
105 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.
106
107 The search string is case-insensitive. Searching for <i>APACHE</i> will yield the same results as searching for <i>apache</i>.
108
109
110
111  **Note:** It should be noted that <i>Extracting [the] complete dependency database</i> does indeed take a while.
112
113
114
115  **Note:** You must be logged in as `root` to install packages.
116
117
118
119 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.
120
121
122
123  **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.
124
125
126 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.
127
128
129
130  **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.
131
132
133
134  **Note:** You can save an extra step by just running `bmake install` instead of `bmake` and `bmake install` as two separate steps.
135
136
137
138  **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)).
139
140
141
142 #### Installing Packages from the Internet 
143
144
145
146 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.
147
148
149 Here are the steps involved:
150
151
152     # cd /usr/pkgsrc/chat/ircII
153     # bmake install clean
154     => ircii-20040820.tar.bz2 doesn't seem to exist on this system.
155     => Attempting to fetch ircii-20040820.tar.bz2 from ftp://ircii.warped.com/pub/ircII/.
156     => [559843 bytes]
157     [FTP transfer snipped]
158     150 Opening BINARY mode data connection for 'ircii-20040820.tar.bz2' (559843 bytes).
159     100% |***************************************|   550 KB  110.34 KB/s   00:00 ETA
160     226 Transfer complete.
161     [FTP transfer snipped]
162     221 Thank you for using the FTP service on bungi.sjc.warped.net.
163     => Checksum SHA1 OK for ircii-20040820.tar.bz2.
164     => Checksum RMD160 OK for ircii-20040820.tar.bz2.
165     work -> /usr/obj/pkgsrc/chat/ircII/work
166     ##=> Extracting for ircII-20040820
167     #########################################################################=
168     The supported build options for this package are:
169
170     socks4 socks5
171
172     You can select which build options to use by setting PKG_DEFAULT_OPTIONS
173     or the following variable.  Its current value is shown:
174
175     
176     PKG_OPTIONS.ircII (not defined)
177
178     #########################################################################=
179     #########################################################################=
180     The following variables will affect the build process of this package,
181     ircII-20040820.  Their current value is shown below:
182
183     USE_INET6 = YES
184
185     You may want to abort the process now with CTRL-C and change their value
186     before continuing.  Be sure to run `/usr/pkg/bin/bmake clean' after
187     the changes.
188     #########################################################################=
189     ##=> Patching for ircII-20040820
190     ##=> Applying pkgsrc patches for ircII-20040820
191     ##=> Overriding tools for ircII-20040820
192     ##=> Creating toolchain wrappers for ircII-20040820
193     ##=> Configuring for ircII-20040820
194     ...
195     [configure output snipped]
196     ...
197     ##=>  Building for ircII-20040820
198     ...
199     [compilation output snipped]
200     ...
201     ##=>  Installing for ircII-20040820
202     ...
203     [installation output snipped]
204     ...
205     ##=> [Automatic manual page handling]
206     ##=> Registering installation for ircII-20040820
207     ##=> Cleaning for ircII-20040820
208     #
209
210
211
212
213
214 As you can see, the only difference are the lines that tell you where the system is fetching the package's distfile from.
215
216
217
218 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. 
219
220
221
222 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.
223
224
225
226  **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.
227
228
229
230 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 `/etc/mk.conf`.
231
232
233
234  **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:
235
236
237
238     
239
240     # bmake show-options
241
242
243
244
245
246  To change the build process, either change the values of PKG_DEFAULT_OPTIONS or PKG_OPTIONS.`***PackageName***` in `/etc/mk.conf` or on the commandline as so:
247
248
249
250     
251
252     # bmake PKG_OPTIONS.ircII="-ssl"
253
254
255
256
257
258  An option is enabled if listed. It is disabled if it is prefixed by a minus sign.
259
260
261
262 #### Dealing with imake 
263
264
265
266 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.
267
268
269
270 ### Removing Installed Packages 
271
272
273
274 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:
275
276     
277
278     # cd /usr/pkgsrc/chat/ircII
279     # make deinstall
280     ##=>  Deinstalling for ircII-20040820
281
282
283 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.
284
285
286
287 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].
288
289
290
291 ### Packages and Disk Space 
292
293
294
295 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 the `bmake `clean*** option. 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.
296
297
298
299 ### Upgrading Packages 
300
301
302
303  **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.
304
305
306
307 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!
308
309
310
311 pkg_chk requires a few steps in order to work correctly. They are listed here.
312
313     # pkg_chk -g # make initial list of installed packages
314     # pkg_chk -r  # remove all packages that are not up to date and packages that depend on them
315     # pkg_chk -a  # install all missing packages (use binary packages, this is the default
316     # pkg_chk -as # install all missing packages (build from source)
317
318 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. "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.
319
320     # cd /usr/pkgsrc/pkgtools/pkg_rolling-replace/
321     # bmake install
322
323 Once pkg_rolling-replace is installed you can update the packages through the following steps.
324
325     # cd /usr && make pkgsrc-update
326     # pkg_rolling-replace -u
327
328 If some package like "bmake" does not get updated and throws an error during the above steps you can update it manually.
329 Inside the packages directory (devel/bmake in this case)
330
331     # env USE_DESTDIR=full bmake package
332     # bmake clean-depends clean
333
334 And Go to the packages directory and install the binary package with
335
336     # pkg_add -u <pkg_name> (i.e. the name of the .tgz file).
337
338 Also you can use "pkgin" to update software using binary packages just like apt or yum.
339
340     # cd /usr/pkgsrc/pkgtools/pkgin/
341     # bmake install
342
343 Once "pkgin" is installed edit "/usr/pkg/etc/pkgin/repositories.conf" to contain the line ( for i386 packages ).
344
345     http://avalon.dragonflybsd.org/packages/i386/DragonFly-2.5/stable/All
346
347 Then you can run the following commands to get the packages updated.
348
349     # pkgin update
350     # pkgin full-upgrade