merge new handbook pkgsrc page and the pkgsrc howto. part 1/x
authormatthias <matthias@web>
Fri, 22 Oct 2010 10:00:36 +0000 (03:00 -0700)
committerCharlie <root@leaf.dragonflybsd.org>
Fri, 22 Oct 2010 10:00:36 +0000 (03:00 -0700)
docs/howtos/HowToPkgsrc.mdwn

index df19444..f110cfb 100644 (file)
@@ -1,8 +1,65 @@
 [[!toc levels=2 ]]
 
-## History and Overview 
+
+## pkgsrc 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
+
+If you have used a UNIX® system before you will know that the typical procedure for installing third party software goes something like this:
+
+  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)).
+
+  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.
+
+  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.
+
+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.
+
+
+
+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.
+
+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.
+
+ **Binary Package Benefits** 
+
+* A compressed package tarball is typically smaller than the compressed tarball containing the source code for the application.
+
+* Packages do not require any additional compilation. For large applications, such as ***Mozilla***, ***KDE***, or ***GNOME*** this can be important, particularly if you are on a slow system.
+
+* Packages do not require any understanding of the process involved in compiling software on DragonFly.
+
+
+**Pkgsrc source Benefits** 
+
+
+* Binary packages are normally compiled with conservative options, because they have to run on the maximum number of systems. By installing from the source, you can tweak the compilation options to (for example) generate code that is specific to a Pentium IV or Athlon processor.
+
+* Some applications have compile time options relating to what they can and cannot do. For example, <i>Apache</i> can be configured with a wide variety of different built-in options. By building from the source you do not have to accept the default options, and can set them yourself. In some cases, multiple packages will exist for the same application to specify certain settings. For example, <i>vim</i> is available as a `vim` package and a `vim-gtk` package, depending on whether you have installed an X11 server. This sort of rough tweaking is possible with packages, but rapidly becomes impossible if an application has more than one or two different compile time options.
+
+* The licensing conditions of some software distributions forbid binary distribution. They must be distributed as source code.
+
+* Some people do not trust binary distributions. With source code, it is possible to check for any vulnerabilities built into the program before installing it to an otherwise secure system. Few people perform this much review, however.
+
+* 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.
+
+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.
+
+ **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.
+
 ## 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.  
@@ -21,7 +78,60 @@ to update.
 
 Edit /usr/Makefile to select a different download location, if desired.
 
-This downloads the absolute most recent version of pkgsrc.  In a production environment, you may want a more stable release.  Check the section below titled "Tracking the stable branch" for more details.
+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.
+
+### Tracking the stable branch 
+
+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.
+
+To see the available branches:
+
+    cd /usr/pkgsrc 
+    git branch -r
+
+To switch to a recent branch:
+
+    cd /usr/pkgsrc 
+    git branch pkgsrc-2010Q3 origin/pkgsrc-2010Q3
+
+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.
+
+After switching to a new branch, it can be downloaded with:
+
+    cd /usr/pkgsrc 
+    git checkout vendor
+    git pull
+
+## Finding Your Application 
+
+Before you can install any applications you need to know what you want, and what the application is called. DragonFly's list of available applications is growing all the time. Fortunately, there are a number of ways to find what you want:
+
+Since DragonFly 1.11 [pkg_search(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_search&section1) is included in the base system.  [pkg_search(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_search&section=1) searches an already installed pkgsrc® INDEX for for a given package name.  If pkgsrc is not installed or the INDEX file is missing, it fetches the [pkg_summary(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_summary&section=5) file.
+
+ **Example. Find a Package** 
+
+    # pkg_search fvwm
+    fvwm-2.4.20nb1          Newer version of X11 Virtual window manager
+    fvwm-2.5.24             Development version of X11 Virtual window manager
+    fvwm-themes-0.6.2nb8    Configuration framework for fvwm2 with samples
+    fvwm-wharf-1.0nb1       Copy of AfterStep's Wharf compatible with fvwm2
+    fvwm1-1.24rnb1          Virtual window manager for X
+
+    # pkg_search -v fvwm-2.5
+    Name    : fvwm-2.5.24-50
+    Dir     : wm/fvwm-devel                                     
+    Desc    : Development version of X11 Virtual window manager 
+    URL     : any                                               
+    Deps    : perl>#5.0 gettext-lib>0.14.5 [...]
+
+Its also possible to issue the command
+
+    # cd /usr/pkgsrc/
+    # bmake search key='package you are looking for'
+
+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 packages from source
 
@@ -57,37 +167,24 @@ You can manually set PKG_PATH and use pkg_add to get the same effect, using a di
     # setenv PKG_PATH http://avalon.dragonflybsd.org/packages/i386/DragonFly-2.7/stable
     # pkg_add screen
 
-*Note that 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 *
+*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.***
+***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.
 
 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 pkg_radd fails, try going to that package's directory in /usr/pkgsrc and using 'bmake install clean'.
 
-### Tracking the stable branch 
-
-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.
-
-To see the available branches:
-
-    cd /usr/pkgsrc 
-    git branch -r
-
-To switch to a recent branch:
-
-    cd /usr/pkgsrc 
-    git branch pkgsrc-2010Q3 origin/pkgsrc-2010Q3
+### Dealing with different package versions 
 
-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.
+Due to the fact that the official packages are only build for the RELEASE-Version of DragonFly, it is possible that you see a warning when installing binary packages on a DEVELOPMENT-version of DragonFly.  The warning could look like this:
 
-After switching to a new branch, it can be downloaded with:
+    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)
 
-    cd /usr/pkgsrc 
-    git checkout vendor
-    git pull
+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 packages 
+## List all installed packages 
 
 To obtain a list of all the packages that are installed on your system:
 
@@ -97,65 +194,74 @@ To see if certain packages have been installed, filter for the name of the packa
 
     # pkg_info | grep xorg
 
-### Searching available packages 
+## Removing packages
 
-Packages can be found using one of two ways. You can issue the command
+If a program was installed as a package:
 
-    # cd /usr/pkgsrc/
-    # bmake search key='package you are looking for'
+    # pkg_delete packagename
 
-from the /usr/pkgsrc directory.
+If a package was installed from the source files, you can also change to the directory they were installed from and issue the command:
 
-There is also the pkglocate tool that comes with pkgsrc:
+    # bmake deinstall
 
-    # /usr/pkgsrc/pkglocate 'package name'
+### Remove associated files needed for building a package 
 
-Normal UNIX file finding commands will work (whereis, locate, or find).
+To remove the work file from building a package, and the package's dependencies:
 
-It's also possible to browse website that show all the available pkgsrc packages, such as [http://pkgsrc.se/](http://pkgsrc.se)
+    # bmake clean clean-depends
 
-## Upgrading packages 
+This can be combined with other steps:
 
-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.
+    # bmake install clean clean-depends
 
-pkg_rolling-replace: Rebuilds packages from source in dependency order.
+## Upgrading packages 
 
-pkgin: Downloads and installs binary packages.  Check the [[mirrors]] page for sites carrying binary packages to use with pkgin. 
+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!
 
-pkg_chk: will update package by removing them and rebuilding them.  Warning: programs are unavailable until a rebuild finishes.  If they don't rebuild, it won't work.
+### pkg_rolling-replace
 
-'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_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_add -u': point at a local or online binary archive location to download and update packages.
+    # cd /usr && make pkgsrc-update
+    # pkg_rolling-replace -u
 
-**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.
+### pkgin
 
-    bmake replace USE_DESTDIR=yes
+Downloads and installs binary packages.  Check the [[mirrors]] page for sites carrying binary packages to use with pkgin. You can run the following commands to get the packages updated.
 
-or
+    # pkgin update
+    # pkgin full-upgrade 
 
-    pkg_add -u /path/to/newer/pkg
+### pkg_chk
 
-## Removing packages
+It updates packages by removing them and rebuilding them.  Warning: programs are unavailable until a rebuild finishes.  If they don't rebuild, it won't work. pkg_chk requires a few steps in order to work correctly. They are listed here.
 
-If a program was installed as a package:
+    # pkg_chk -g # make initial list of installed packages
+    # pkg_chk -r  # remove all packages that are not up to date and packages that depend on them
+    # pkg_chk -a  # install all missing packages (use binary packages, this is the default)
+    # pkg_chk -as # install all missing packages (build from source)
 
-    # pkg_delete packagename
+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. 
 
-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 update
 
-    # bmake deinstall
+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.
 
-### Remove associated files needed for building a package 
+### pkg_add -u
 
-To remove the work file from building a package, and the package's dependencies:
+Point at a local or online binary archive location to download and update packages.
 
-    # bmake clean clean-depends
+#### Update pkgsrc system packages
 
-This can be combined with other steps:
+**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)
 
-    # bmake install clean clean-depends
+    # 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
 ## Additional /usr/pkg/etc/mk.conf notes
 
 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: