1 ## Using the pkgsrc® Source Tree
3 The following sections provide basic instructions on using the pkgsrc source tree to install or remove programs from your system.
5 ### Obtaining the pkgsrc Source Tree
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`.
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** .
16 # cvs -d anoncvs@anoncvs.us.netbsd.org:/cvsroot co pkgsrc
19 Running the following command later will download and apply all the recent changes to your source tree.
25 #### The DragonFly Way
27 As of the 1.10 release, you can use the `/usr/Makefile` to checkout & update the pkgsrc tree quickly.
35 to checkout from git repository, or
41 to update. **NOTE**: If you use CVS instead of git 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.
43 ### Installing Packages from Source
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:
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.
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§ion=1).
53 * A `files` directory. This directory contains the application specific files that are needed for the programs appropriate run-time configuration.
55 This directory may also contain other files used to build the port.
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§ion1) program.
61 * A `DESCR` file. This is a more detailed, often multiple-line, description of the program.
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.
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/).
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.
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`:
78 # bmake search key="apache2"
79 Extracting complete dependency database. This may take a while...
80 ....................................................................................................
82 ....................................................................................................
86 ....................................................................................................
88 .................................................................................................Reading database file
89 Flattening dependencies
90 Flattening build dependencies
96 Info: Apache HTTP (Web) server, version 2
97 Maint: tron@NetBSD.org
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
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.
107 The search string is case-insensitive. Searching for <i>APACHE</i> will yield the same results as searching for <i>apache</i>.
111 **Note:** It should be noted that <i>Extracting [the] complete dependency database</i> does indeed take a while.
115 **Note:** You must be logged in as `root` to install packages.
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.
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.
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§ion8) manual pages.
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.
134 **Note:** You can save an extra step by just running `bmake install` instead of `bmake` and `bmake install` as two separate steps.
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)).
142 #### Installing Packages from the Internet
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.
149 Here are the steps involved:
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/.
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:
172 You can select which build options to use by setting PKG_DEFAULT_OPTIONS
173 or the following variable. Its current value is shown:
176 PKG_OPTIONS.ircII (not defined)
178 #########################################################################=
179 #########################################################################=
180 The following variables will affect the build process of this package,
181 ircII-20040820. Their current value is shown below:
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
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
195 [configure output snipped]
197 ##=> Building for ircII-20040820
199 [compilation output snipped]
201 ##=> Installing for ircII-20040820
203 [installation output snipped]
205 ##=> [Automatic manual page handling]
206 ##=> Registering installation for ircII-20040820
207 ##=> Cleaning for ircII-20040820
214 As you can see, the only difference are the lines that tell you where the system is fetching the package's distfile from.
218 The pkgsrc system uses [ftp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ftp§ion=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§ion=1) for the complete list.
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.
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.
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`.
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:
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:
252 # bmake PKG_OPTIONS.ircII="-ssl"
258 An option is enabled if listed. It is disabled if it is prefixed by a minus sign.
262 #### Dealing with imake
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.
270 ### Removing Installed Packages
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:
278 # cd /usr/pkgsrc/chat/ircII
280 ##=> Deinstalling for ircII-20040820
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.
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§ion=1) as discussed in the [pkgsrc-using.html Pkgsrc section of the Handbook].
291 ### Packages and Disk Space
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.
299 ### Upgrading Packages
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.
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!
311 pkg_chk requires a few steps in order to work correctly. They are listed here.
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)
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.
320 # cd /usr/pkgsrc/pkgtools/pkg_rolling-replace/
323 Once pkg_rolling-replace is installed you can update the packages through the following steps.
325 # cd /usr && make pkgsrc-update
326 # pkg_rolling-replace -u
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)
331 # env USE_DESTDIR=full bmake package
332 # bmake clean-depends clean
334 And Go to the packages directory and install the binary package with
336 # pkg_add -u <pkg_name> (i.e. the name of the .tgz file).
338 Also you can use "pkgin" to update software using binary packages just like apt or yum.
340 # cd /usr/pkgsrc/pkgtools/pkgin/
343 Once "pkgin" is installed edit "/usr/pkg/etc/pkgin/repositories.conf" to contain the line ( for i386 packages ).
345 http://avalon.dragonflybsd.org/packages/i386/DragonFly-2.5/stable/All
347 Then you can run the following commands to get the packages updated.