fix bsdtalk download links
[ikiwiki.git] / docs / howtos / HowToPkgsrc.mdwn
index dbfe03e..cbcc8d1 100644 (file)
@@ -1,35 +1,31 @@
-# pkgsrc on DragonFly
-
-The following page describes the basics of the pkgsrc system as used by DragonFly.
-
-[[!toc levels=2 ]]
+# Disclaimer 
 
-## Overview 
-
-### History 
-[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.
+DragonFly, up to and including version 3.4, used pkgsrc to manage third party software packages.  DragonFly switched to dports at the 3.6 release.
 
-### Overview
+This page is still useful for anyone wanting to use pkgsrc, but the recommended packaging method is dports, which is covered in a similar document here: 
 
-If you have used a UNIX® system before you will know that the typical procedure for installing third party software goes something like this:
+[http://www.dragonflybsd.org/docs/howtos/HowToDPorts/](http://www.dragonflybsd.org/docs/howtos/HowToDPorts/)
 
-  1. Download the software, which might be distributed in source code format, or as a binary.
+----
 
-  1. Unpack the software from its distribution format (typically a tarball compressed with [compress(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=compress&section1), [gzip(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=gzip&section=1), or [bzip2(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=bzip2&section=1)).
+# pkgsrc on DragonFly
 
-  1. Locate the documentation (perhaps an `INSTALL` or `README` file, or some files in a `doc/` subdirectory) and read up on how to install the software.
+DragonFly uses a specially crafted Makefile in /usr and a git mirror
+of the official pkgsrc repository to make pkgsrc distribution more user-friendly.
 
-  1. If the software was distributed in source format, compile it. This may involve editing a `Makefile`, or running a `configure` script, and other work.
+The basics of the pkgsrc system can be found in NetBSD's [Pkgsrc Guide](http://www.netbsd.org/docs/pkgsrc/), and can be considered the canonical resource.
 
-  1. Test and install the software.
 
-And that is only if everything goes well. If you are installing a software package that was not deliberately ported to DragonFly you may even have to go in and edit the code to make it work properly. Should you want to, you can continue to install software the ***traditional*** way with DragonFly. However, DragonFly provides technology from NetBSD, which can save you a lot of effort: pkgsrc. At the time of writing, over 8,000 third party applications have been made available in this way.
+[[!toc levels=3 ]]
 
-For any given application, the DragonFly Binary package for that application is a single file which you must download. The package contains pre-compiled copies of all the commands for the application, as well as any configuration files or documentation. A downloaded package file can be manipulated with DragonFly package management commands, such as [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_add&section1), [pkg_delete(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_delete&section=1), [pkg_info(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_info&section=1), and so on. Installing a new application can be carried out with a single command.
+## Overview 
 
+### History 
+[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.
 
+### Overview
 
-In addition the pkgsrc collection supplies a collection of files designed to automate the process of compiling an application from source code. Remember that there are a number of steps you would normally carry out if you compiled a program yourself (downloading, unpacking, patching, compiling, installing). The files that make up a pkgsrc source collection contain all the necessary information to allow the system to do this for you. You run a handful of simple commands and the source code for the application is automatically downloaded, extracted, patched, compiled, and installed for you. In fact, the pkgsrc source subsystem can also be used to generate packages which can later be manipulated with `pkg_add` and the other package management commands that will be introduced shortly.
+The pkgsrc collection supplies a collection of files designed to automate the process of compiling an application from source code. Remember that there are a number of steps you would normally carry out if you compiled a program yourself (downloading, unpacking, patching, compiling, installing). The files that make up a pkgsrc source collection contain all the necessary information to allow the system to do this for you. You run a handful of simple commands and the source code for the application is automatically downloaded, extracted, patched, compiled, and installed for you. In fact, the pkgsrc source subsystem can also be used to generate packages which can later be manipulated with `pkg_add` and the other package management commands that will be introduced shortly.
 
 Pkgsrc understands ***dependencies***. Suppose you want to install an application that depends on a specific library being installed. Both the application and the library have been made available through the pkgsrc collection. If you use the `pkg_add` command or the pkgsrc subsystem to add the application, both will notice that the library has not been installed, and automatically install the library first. You might be wondering why pkgsrc® bothers with both. Binary packages and the source tree both have their own strengths, and which one you use will depend on your own preference.
 
@@ -55,19 +51,23 @@ Pkgsrc understands ***dependencies***. Suppose you want to install an applicatio
 
 * If you have local patches, you will need the source in order to apply them.
 
-* Some people like having code around, so they can read it if they get bored, hack it, borrow from it (license permitting, of course), and so on.
+* Some people like having code around, so they can read it if they get bored, hack it, debug crashes, borrow from it (license permitting, of course), and so on.
 
-To keep track of updated pkgsrc releases subscribe to the [NetBSD pkgsrc users mailing list](http://www.netbsd.org/MailingLists/pkgsrc-users) and the [NetBSD pkgsrc users mailing list](http://www.netbsd.org/MailingLists/tech-pkgsrc). It's also useful to watch the [DragonFly User related mailing list](http://leaf.dragonflybsd.org/mailarchive/) as errors with pkgsrc on DragonFly should be reported there.
+To keep track of pkgsrc releases subscribe to the [NetBSD pkgsrc users mailing list](http://www.netbsd.org/MailingLists/pkgsrc-users) and the [NetBSD pkgsrc users mailing list](http://www.netbsd.org/MailingLists/tech-pkgsrc). It's also useful to watch the [DragonFly User related mailing list](http://leaf.dragonflybsd.org/mailarchive/) as errors with pkgsrc on DragonFly should be reported there.
 
  **Warning:** Before installing any application, you should check http://www.pkgsrc.org/ for security issues related to your application.
 
 Audit-packages will automatically check all installed applications for known vulnerabilities, a check will be also performed before any application build. Meanwhile, you can use the command `audit-packages -d` after you have installed some packages.
 
+**Note:** Binary packages and source packages are effectively the same software and can be manipulated with the same pkg_* tools.  
+
 ## Installing pkgsrc 
 
 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.  
 
-As root:
+Set GITHOST in /etc/make.conf or set it as an environment variable to select a different download location, if desired. See mirrors page for available mirrors.
+
+This downloads the stable version of the pkgsrc tree from the default mirror, if you didn't set GITHOST. As root:
 
     # cd /usr
     # make pkgsrc-create
@@ -79,31 +79,35 @@ to fetch the intial pkgsrc repository from the net, or
 
 to update.
 
-Edit /usr/Makefile to select a different download location, if desired.
+**Note**: If your DragonFly install is not up to date, you might have ended up with an old release of the pkgsrc tree.
 
-This downloads the absolute most recent version of pkgsrc.  In a production environment, you may want a more stable release.  Check the section below for more details.
+    # cd /usr/pkgsrc
+    # git branch
 
-### Tracking the stable branch 
+will show what release you are on. See Tracking the stable branch for more information.
 
-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.
+### Tracking the stable branch
 
-To see the available branches:
+There are quarterly releases of pkgsrc that are specifically designed for stability.  You should in general follow these, rather than the bleeding edge pkgsrc. When a new branch is out you need to set up a local branch tracking that one. 'make pkgsrc-update' will not do this for you.
 
-    cd /usr/pkgsrc 
-    git branch -r
+To see the available remote branches:
 
-To switch to a recent branch:
+    # cd /usr/pkgsrc 
+    # git pull
+    # git branch -r
 
-    cd /usr/pkgsrc 
-    git branch pkgsrc-2010Q3 origin/pkgsrc-2010Q3
+To create a local branch, tracking the remote quarterly release:
 
-Branch naming format is 'pkgsrc-YYYYQX', where YYYY is the year and QX is quarters 1-4 of the year.  Check [pkgsrc.org](http://www.pkgsrc.org/) to see the name of the most recently released branch.
+    # cd /usr/pkgsrc 
+    # git branch pkgsrc-2010Q4 origin/pkgsrc-2010Q4
 
-After switching to a new branch, it can be downloaded with:
+Branch naming format is 'pkgsrc-YYYYQX', where YYYY is the year and QX is quarters 1-4 of the year.  Check [pkgsrc.org](http://www.pkgsrc.org/) to see the name of the latest stable branch.
 
-    cd /usr/pkgsrc 
-    git checkout vendor
-    git pull
+After adding a new branch, it can be downloaded with:
+
+    # cd /usr/pkgsrc 
+    # git checkout pkgsrc-2010Q4
+    # git pull
 
 ## Dealing with pkgsrc packages
 
@@ -138,7 +142,18 @@ from the `/usr/pkgsrc` directory.
 
 It's also possible to browse website that show all the available pkgsrc packages, such as [http://pkgsrc.se/](http://pkgsrc.se) .
 
-### Installing applications from source
+### Installing applications
+
+Downloading a binary package is almost always faster than building from source, but not all programs in pkgsrc can be redistributed as a binary.  In most cases, you will want to download a binary package if possible, and otherwise build from source if it's not available.  
+
+The `bin-install` target on DragonFly (with pkgsrc from 2011/02/07 and later) will do just that:
+
+    # cd /usr/pkgsrc/misc/screen
+    # bmake bin-install clean
+
+This will download and install the appropriate `screen` binary package if it exists, and try building from source if it can't complete the download.
+
+### Installing applications, source only
 
 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.
 
@@ -159,35 +174,26 @@ To make these option changes permanent for every future build or upgrade of this
 
      . PKG_OPTIONS.<package_name>=-option1 option2
     
-### Installing pre-built packages 
+### Installing applications, binary only
 
 Binary packages can be installed using *pkg_radd*:
 
     # pkg_radd screen
 
-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.
+This program works by setting the `PKG_PATH` environment 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. This will install most packages, but will not upgrade packages that are already installed.
 
-You can manually set PKG_PATH and use pkg_add to get the same effect, using a different server.
+You can manually set `BINPKG_BASE` and use *pkg_add* to get the same effect, using a different server.
 
-    # setenv PKG_PATH http://mirror-master.dragonflybsd.org/packages/i386/DragonFly-2.7/stable
+    # setenv BINPKG_BASE http://mirror-master.dragonflybsd.org/packages
     # pkg_add screen
 
-*Note:* The above URL is for the DragonFly-2.7 on i386.  Adjust the file path to match your installation and what's available on the server.
-
-This will install most packages, but will not upgrade packages that are already installed.
 
-***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.
+#### Issues with pre-built packages
 
-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 it fails, try going to that package's directory and install the package manually as described above.
+* The default remote repository for binary packages tracks quarterly pkgsrc releases, so your local install of pkgsrc should be the same quarterly release.
+* 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 it fails, try going to that package's directory and install the package manually as described above.
+* If you upgrade to an new DEVELOPMENT version of DragonFly very early (i.e. shortly after the branch), it might be possible that *pkg_radd* fails to install packages. This is due the fact, that it takes some time to built binary packages and thus, there are no binary packages available on the mirrors yet. Usually you'll see an announcement on the lists once the first packages for DEVELOPMENT are ready.
 
-#### Dealing with different package versions 
-
-It is possible that you see a warning when installing binary packages on a DEVELOPMENT-version of DragonFly.  The warning could look like this:
-
-    pkg_add: Warning: package `vim-gtk2-7.1.116.tgz' was built for a different version of the OS:
-    pkg_add: DragonFly/i386 1.10.1 (pkg) vs. DragonFly/i386 1.11.0 (this host)
-
-You can safely ignore this warning.  Normally all packages build for RELEASE run fine on DEVELOPMENT unless a major API-breakage was introduced.  In this case you would see a message from the developers on the appropriate mailing list.
 
 ### List all installed applications 
 
@@ -195,7 +201,7 @@ To obtain a list of all the packages that are installed on your system:
 
     # pkg_info
 
-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:
+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:
 
     # pkg_info | grep xorg
 
@@ -209,6 +215,8 @@ If a package was installed from the source files, you can also change to the dir
 
     # bmake deinstall
 
+Note that these methods are effectively interchangeable.  Either will work whether the package was originally installed from source or binary.
+
 #### Remove associated files needed for building a package 
 
 To remove the work file from building a package, and the package's dependencies:
@@ -221,11 +229,36 @@ This can be combined with other steps:
 
 ## Upgrading packages 
 
-There's a number of ways to upgrade pkgsrc; some of these are built in and some are packages installable with pkgsrc.  This list is not necessarily comprehensive. Be sure to read the note about upgrading pkgsrc system packages at the end of this subsection!
+There's a number of ways to upgrade pkgsrc; some of these are built in and some are packages installable with pkgsrc.  This list is not necessarily comprehensive.
+
+### Update pkgsrc system packages
+
+**Note**: Sometimes basic pkgsrc tools; *bmake*, *pkg_install* and *bootstrap-mk-files* need to be upgraded.  However, they can't be deleted and replaced since you need that tool to accomplish replacement.  The solution is to build a separate package before deletion, and install that package. 
+
+    # cd /usr/pkgsrc/devel/bmake
+    or
+    # cd /usr/pkgsrc/pkgtools/pkg_install
+    or 
+    # cd /usr/pkgsrc/pkgtools/bootstrap-mk-files
+    
+    # env USE_DESTDIR=yes bmake package
+    # bmake clean-depends clean
+
+And go to the packages directory and install the binary package with
+
+    # cd /usr/pkgsrc/packages/All
+    # pkg_add -u <pkg_name> (i.e. the name of the .tgz file).
+
+
+### bmake replace
+Performed in the `/usr/pkgsrc` directory that correlates with the installed package, the software is first built and then replaced.
+
+    # cd /usr/pkgsrc/chat/ircII
+    # bmake replace
 
 ### pkg_rolling-replace
 
-*pkg_rolling-replace* replaces packages one by one and one can use it for a better way of package management. Actually it does `make replace` on one package at a time, sorting the packages being replaced according to their interdependencies, which avoids most duplicate rebuilds. Once *pkg_rolling-replace* is installed you can update the packages through the following steps.
+*pkg_rolling-replace* replaces packages one by one and you can use it for a better way of package management. Actually it does `bmake replace` on one package at a time, sorting the packages being replaced according to their interdependencies, which avoids most duplicate rebuilds. Once *pkg_rolling-replace* is installed you can update the packages through the following steps.
 
     # cd /usr && make pkgsrc-update
     # pkg_rolling-replace -u
@@ -248,25 +281,15 @@ It updates packages by removing them and rebuilding them.  Warning: programs are
 
 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. 
 
-### bmake update
-
-Performed in the `/usr/pkgsrc` directory that correlates with the installed package, the software is deleted and rebuilt.  The same warning applies as with *pkg_chk*.
-
 ### pkg_add -u
 
 Point at a local or online binary archive location to download and update packages.
 
-#### Update pkgsrc system packages
+### rpkgmanager
 
-**Note**: Sometimes, basic pkgsrc tools, like bmake or pkg_install, need to be upgraded.  However, they can't be deleted and replaced since you need that tool to accomplish replacement.  The solution is to build a separate package before deletion, and install that package. Inside the packages directory (`/usr/pkgsrc/devel/bmake` in this case)
+This requires that you've set up rpkgmanager first. Read more about rpkgmanager [[here|docs/howtos/rpkgmanager/]].
 
-    # env USE_DESTDIR=full bmake package
-    # bmake clean-depends clean
-
-And go to the packages directory and install the binary package with
-
-    # pkg_add -u <pkg_name> (i.e. the name of the .tgz file).
-    # bmake replace USE_DESTDIR=yes
+    # yes | rpkgmanager.rb
 
 ## Start pkgsrc applications on system startup
 
@@ -294,7 +317,7 @@ will show all the files installed by the package. Pay special attention to files
 
     # pkg_info | grep -i foopackage
 
-will find all the installed packages that have <i>foopackage</i> in the package name. Replace <i>foopackage</i> in your command line as necessary.
+will find all the installed packages that have *foopackage* in the package name. Replace *foopackage* in your command line as necessary.
 
 Once you have identified where the application's manual pages have been installed, review them using [man(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=man&section=1). Similarly, look over the sample configuration files, and any additional documentation that may have been provided. If the application has a web site, check it for additional documentation, frequently asked questions, and so forth. If you are not sure of the web site address it may be listed in the output from
 
@@ -318,11 +341,11 @@ Packages that can be built within the pkgsrc framework but are not yet necessari
 
 ### Links
 
-* [http://www.netbsd.org/Documentation/pkgsrc/](http://www.netbsd.org/Documentation/pkgsrc/)
+* More information: The pkgsrc guide [http://www.netbsd.org/Documentation/pkgsrc/](http://www.netbsd.org/Documentation/pkgsrc/)
 
-* [http://www.pkgsrc.se](http://www.pkgsrc.se)
+* Web interface for searching packages: [http://www.pkgsrc.se](http://www.pkgsrc.se)
 
-* [http://wiki-static.aydogan.net/How_to_upgrade_packages](http://wiki-static.aydogan.net/How_to_upgrade_packages)
+* Ways to upgrade packages [http://wiki-static.aydogan.net/How_to_upgrade_packages](http://wiki-static.aydogan.net/How_to_upgrade_packages)
 
 * To search and/or report bugs against packages in pkgsrc, look at [http://www.netbsd.org/support/send-pr.html](http://www.netbsd.org/support/send-pr.html) - use category 'pkg'.