more style and content fixes
authormatthias <matthias@web>
Sat, 23 Oct 2010 16:20:37 +0000 (09:20 -0700)
committerCharlie <root@leaf.dragonflybsd.org>
Sat, 23 Oct 2010 16:20:37 +0000 (09:20 -0700)
docs/howtos/HowToPkgsrc.mdwn

index 09ef380..d7b9de2 100644 (file)
@@ -23,11 +23,9 @@ If you have used a UNIX┬« system before you will know that the typical procedure
 
   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.
-
+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.
 
+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.
 
 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.
 
@@ -165,20 +163,19 @@ 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.
+#### Issues with pre-built packages
 
-***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.
+* 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.
 
-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.
 
 #### Dealing with different package versions 
 
@@ -195,7 +192,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
 
@@ -258,7 +255,7 @@ Point at a local or online binary archive location to download and update packag
 
 #### Update pkgsrc system packages
 
-**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)
+**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)
 
     # env USE_DESTDIR=yes bmake package
     # bmake clean-depends clean
@@ -293,7 +290,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