[ikiwiki.git] / docs / howtos / HowToPkgsrc.mdwn

[[!toc levels=3 ]]�
## History and Overview 
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.

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.

## Installing pkgsrc 

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 
binary bootstrap is provided with the system. However, you still need to download the pkgsrc tree if you
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.

### Quick & Dirty Way 

As of the 1.10 release, you can use the UsrMakefile to checkout & update the pkgsrc tree quickly.

as root:

    # cd /usr
    # make pkgsrc-create

to fetch the intial pkgsrc repository from the net, or

    # cd /usr
    # make pkgsrc-update

to update.

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.

### 'Custom' Way 

In those cases where you wish to checkout pkgsrc manually, for example to track a specific pkgsrc branch,
a custom checkout may be desired.

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.

The commands to fetch and install the tarball:

    # fetch -o /tmp/pkgsrc.tar.gz ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc.tar.gz
    # cd /usr; tar -xzf /tmp/pkgsrc.tar.gz; chown -R root:wheel pkgsrc


The commands to install via CVS:

    # cd /usr
    # cvs -d anoncvs@anoncvs.us.netbsd.org:/cvsroot co pkgsrc

*Note*, you will have to be root in order for this to work.

Please check [NetBSD anoncvs mirrors](http://www.netbsd.org/mirrors/#anoncvs) for faster server.

Either of these command sets will download the pkgsrc source tree to your local machine into the /usr/pkgsrc directory.

If you wish to perform your own bootstrap of pkgsrc (not needed since the 1.4 release), for example
to customize some of the pkgsrc default settings, use the following commands:

    # cd /usr/pkgsrc/bootstrap
    # ./bootstrap --pkgdbdir /var/db/pkg --prefix /usr/pkg

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.

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.

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 /usr/pkg/etc. The command for this is:

    # cp work/mk.conf.example /usr/pkg/etc/mk.conf

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.

Note: This path alteration step is still required on a 1.4_REL CD

## Building packages 
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.

    # cd /usr/pkgsrc/misc/screen
    # bmake install clean

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.

    # bmake show-options

This will return back a message similar to the following...

    Any of the following general options may be selected:
      option1
      option2 Option2 description
      option3 Option3 description
    These options are enabled by default:
     option1
    These options are currently enabled:
 option3

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:

    # bmake PKG_OPTIONS.<package_name>="-option1 option2" install clean

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.

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:

     . PKG_OPTIONS.<package_name>=-option1 option2
    
    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.
    
    # cd /usr/pkgsrc/misc/screen
    # bmake package clean

Packages are usually placed into an appropriate category. To find out where the package you are seeking to build is located, try this command:

    # cd /usr/pkgsrc/
    # bmake search key='NameOfPackageYouWishToFind'

## Pre-built pkgsrc packages 
The pkgsrc section of the download page (http://www.dragonflybsd.org/main/download.cgi) contains a list of sites providing binary packages.

Binary packages can be installed either by using the full URL

    # pkg_add ftp://packages.stura.uni-rostock.de/pkgsrc-current/DragonFly/DEVELOPMENT/i386/All/xorg-6.8.2nb1.tgz


or by setting PKG_PATH (example for csh)

    # setenv PKG_PATH ftp://packages.stura.uni-rostock.de/pkgsrc-current/DragonFly/DEVELOPMENT/i386/All
    # pkg_add xorg

Also note that the version can be omitted, in which case the newest package will be chosen.

## Other pkgsrc commands 
This section will cover the commands in pkgsrc that will allow a user to perform the suggested action.

### Get latest list of packages 
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:

    # cvs up -dP

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.

There's also a RSS feed "NetBSD - Fresh Packages" available: http://www.netbsd.org/Changes/rss-netbsd-pkgs.xml

### Tracking the stable branch 

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:

    # cd /usr/pkgsrc
    # cvs up -rpkgsrc-200XQY -dPA

Where 'X' is the year and 'Y' is the revision, with a number from 1 to 4 (for example -rpkgsrc-2006Q2).

The stable branch will update the buggy applications, so update it frequently.

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)

### List all installed packages 
To obtain a list of all the packages that are installed on your system, the user can perform the following command:

    # pkg_info

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:

    # pkg_info | grep xorg

will return a list of all the xorg related packages installed on the system.

### Search available packages 
Packages can be found using one of two ways. You can issue the command

    # bmake search key='package you are looking for'

from the /usr/pkgsrc directory.

There is also the pkglocate tool that comes with pkgsrc. It is invoked in the following manner:

    # /usr/pkgsrc/pkglocate 'package name'

You can also utilize the UNIX file finding commands (whereis, locate, or find).

### Upgrade all Installed packages 

Note: Up to date information about this can be found in this web page: http://wiki.netbsd.se/index.php/How_to_upgrade_packages

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:

Make initial list of installed packages:

    # pkg_chk -g

Remove all packages that are not up to date and packages that depend on them:

    # pkg_chk -r

Install all missing packages (use binary packages, this is the default):

    # pkg_chk -a

Install all missing packages (build from source):

    pkg_chk -as

If you want to see a list of upgradeable packages, you can use the pkglint tool. Install the package pkgtools/lintpkgsrc and do a:

    lintpkgsrc -i

It will list the packages, which could be updated.


### Quick binary upgrades with pkgsrc 
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.

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:

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.

    
    pkg_chk -P ftp://binary/url -abg 

This command downloads all the binary packages needed to upgrade pkgsrc.

    
    pkg_chk -P ftp://binary/url -abf  

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.

    
    pkg_chk -P /wherever/previous/step/put/binaries -abu 


Note that ftp://binary/url represents the URL to an online binary pkgsrc repository, such as in the PKG_PATH example on this page.

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.

## Deinstall a package 
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:

    # bmake deinstall

### Remove associated files needed for building a package 
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.

## Additional mk.conf notes

The default location of mk.conf is /usr/pkg/etc
 
To specify where the rc.d scripts from the installed packages should go:

    RCD_SCRIPTS_DIR=/etc/rc.d

To enable the automatic installation of rc.d scripts into the $RCD_SCRIPTS_DIR directory:

    PKG_RCD_SCRIPTS=YES

This option can be set in the environment to activate it for binary packages.

If you have already partially downloaded a file, this option makes it resume the transfer:

    PKG_RESUME_TRANSFERS=YES

If the checksum is not correct, automatically download from the next download site:

    FAILOVER_FETCH=YES

To enable suffixing work directories with the machine's hostname (needed for PKGSRC_LOCKTYPE):

    OBJHOSTNAME=

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)):
 
    PKGSRC_LOCKTYPE=sleep

To enable sending of MESSAGE file upon installation of a package to a specific user:

    PKGSRC_MESSAGE_RECIPIENTS=username

To clean easly the dependencies after compiling:

    CLEANDEPENDS=YES

## Speed up compilation with ccache 
It is possible to speed up the recompilation of packages by using ccache.
The first thing is to install ccache:

    # cd /usr/pkgsrc/devel/ccache && bmake install

To use it the PKGSRC_COMPILER option must be set in your mk.conf must be set:

    PKGSRC_COMPILER = ccache gcc # if you are using gcc

It's also a good idea to set a high enough size for your cache:
    
    # ccache -M 5G

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).

## Where is my http://pkgsrc.se/wip dir? 
[[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.

## Where to go for more help 

* The NetBSD pkgsrc developers have a lot of pkgsrc documentation on this website (http://www.netbsd.org/Documentation/pkgsrc/).


* To find packages or updates, look at http://www.pkgsrc.se.


* To query and/or report bugs against packages in pkgsrc, look at http://www.netbsd.org/support/send-pr.html category 'pkg'.


* To get and update wip, look at http://pkgsrc-wip.sourceforge.net.


* This wiki has a list of some quick pkgsrc hacks to get the one or the other package building.


* The pkgsrc IRC channel on Freenode (http://www.freenode.net) (#pkgsrc) is another resource for pkgsrc users and devleopers.


* The DragonFlyBSD IRC channel on EFnet (http://www.efnet.org) (#dragonflybsd) is frequented by DragonFly users and developers using pkgsrc.


* Google (http://www.google.com/search?q#pkgsrc&sourceidopera&num=0&ie=utf-8&oe=utf-8) also has a wealth of information.

----
CategoryHowTo