New donator - thanks, Michael Roach!
[ikiwiki.git] / docs / howtos / HowToPkgsrc.mdwn
index 74b32ca..cbcc8d1 100644 (file)
@@ -1,33 +1,31 @@
-# pkgsrc on DragonFly
+# Disclaimer 
 
-The following page describes the basics of the pkgsrc system as used by DragonFly.
+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.
 
-[[!toc levels=3 ]]
+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: 
 
-## 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.
+[http://www.dragonflybsd.org/docs/howtos/HowToDPorts/](http://www.dragonflybsd.org/docs/howtos/HowToDPorts/)
 
-### Overview
+----
 
-If you have used a UNIX® system before you will know that the typical procedure for installing third party software goes something like this:
+# pkgsrc on DragonFly
 
-  1. Download the software, which might be distributed in source code format, or as a binary.
+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. 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)).
+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. 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.
 
-  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.
+[[!toc levels=3 ]]
 
-  1. Test and install the software.
+## Overview 
 
-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 10,000 third party applications have been made available in this way.
+### 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.
 
-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. Installing a new application can be carried out with a single command.
+### 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.
 
@@ -53,9 +51,9 @@ 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.
 
@@ -67,9 +65,9 @@ Audit-packages will automatically check all installed applications for known vul
 
 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.  
 
-Edit GITHOST in /usr/Makefile or set it as an environment variable to select a different download location, if desired. See mirrors page for available mirrors.
+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 latest stable version of the pkgsrc tree. As root:
+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
@@ -81,6 +79,13 @@ to fetch the intial pkgsrc repository from the net, or
 
 to update.
 
+**Note**: If your DragonFly install is not up to date, you might have ended up with an old release of the pkgsrc tree.
+
+    # cd /usr/pkgsrc
+    # git branch
+
+will show what release you are on. See Tracking the stable branch for more information.
+
 ### Tracking the stable branch
 
 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.
@@ -96,7 +101,7 @@ To create a local branch, tracking the remote quarterly release:
     # cd /usr/pkgsrc 
     # git branch pkgsrc-2010Q4 origin/pkgsrc-2010Q4
 
-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.
+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.
 
 After adding a new branch, it can be downloaded with:
 
@@ -231,6 +236,11 @@ There's a number of ways to upgrade pkgsrc; some of these are built in and some
 **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
 
@@ -275,6 +285,12 @@ The above process removes all packages at once and installs the missing packages
 
 Point at a local or online binary archive location to download and update packages.
 
+### rpkgmanager
+
+This requires that you've set up rpkgmanager first. Read more about rpkgmanager [[here|docs/howtos/rpkgmanager/]].
+
+    # yes | rpkgmanager.rb
+
 ## Start pkgsrc applications on system startup
 
 Packages often install rc.d scripts to control software running on startup.  To specify where the rc.d scripts from the installed packages should go, add the following lines to your `/usr/pkg/etc/mk.conf` file:
@@ -325,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'.