First run at cleaning this up; still some sections to go
authorjustin <justin@web>
Sun, 26 Sep 2010 03:19:33 +0000 (20:19 -0700)
committerCharlie <root@leaf.dragonflybsd.org>
Sun, 26 Sep 2010 03:19:33 +0000 (20:19 -0700)
docs/howtos/HowToPkgsrc.mdwn

index 71203b7..ee94453 100644 (file)
@@ -1,20 +1,13 @@
-[[!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.
+[[!toc levels=1 ]]
 
-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.
+## History and Overview 
+[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.
 
 ## 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.
+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:
+As root:
 
     # cd /usr
     # make pkgsrc-create
@@ -26,157 +19,97 @@ to fetch the intial pkgsrc repository from the net, or
 
 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.
+Edit /usr/Makefile to select a different download location, if desired.
 
-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.
+## Installing packages from source
+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.
+To find out the options that can affect how a program is built:
 
     # 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:
+To change options:
 
     # 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.
+Listing an option enables it.  Listing an option with a "-" before it disables the option.
 
-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:
+To make these option changes permanent for every future build or upgrade of this package, put a similar line in /usr/pkg/etc/mk.conf:
 
      . 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
+## Installing pre-built packages 
 
-Packages are usually placed into an appropriate category. To find out where the package you are seeking to build is located, try this command:
+Binary packages can be installed using pkg_radd:
 
-    # 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
+    # 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.
 
-or by setting PKG_PATH (example for csh)
+You can manually set PKG_PATH and use pkg_add to get the same effect, using a different server.
 
-    # setenv PKG_PATH ftp://packages.stura.uni-rostock.de/pkgsrc-current/DragonFly/DEVELOPMENT/i386/All
-    # pkg_add xorg
+    # setenv PKG_PATH http://avalon.dragonflybsd.org/packages/i386/DragonFly-2.7/stable
+    # pkg_add screen
 
-Also note that the version can be omitted, in which case the newest package will be chosen.
+This will install most packages, but will not upgrade packages that are already installed.
 
-## Other pkgsrc commands 
-This section will cover the commands in pkgsrc that will allow a user to perform the suggested action.
+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.
 
-### 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:
+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'.
 
-    # cvs up -dP
+### Tracking the stable branch 
 
-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 are quarterly releases of pkgsrc that are specifically designed for stability.  You should in general follow the latest branch, rather than bleeding edge pkgsrc.
 
-There's also a RSS feed "NetBSD - Fresh Packages" available: http://www.netbsd.org/Changes/rss-netbsd-pkgs.xml
+To see the available branches:
 
-### Tracking the stable branch 
+    cd /usr/pkgsrc 
+    git branch -r
 
-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:
+To switch to the most recent branch:
 
-    # cd /usr/pkgsrc
-    # cvs up -rpkgsrc-200XQY -dPA
+    cd /usr/pkgsrc 
+    git branch pkgsrc-2010Q3 origin/pkgsrc-2010Q3
 
-Where 'X' is the year and 'Y' is the revision, with a number from 1 to 4 (for example -rpkgsrc-2006Q2).
+Branch naming format is 'pkgsrc-YYYYQX', where YYYY is the year and QX is quarters 1-4 of the year.
 
-The stable branch will update the buggy applications, so update it frequently.
+After switching to a new branch, it can be downloaded with:
 
-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)
+    cd /usr/pkgsrc 
+    git checkout vendor
+    git pull
 
 ### 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:
+
+To obtain a list of all the packages that are installed on your system:
 
     # 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:
+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
 
-will return a list of all the xorg related packages installed on the system.
+### Searching available packages 
 
-### Search available packages 
 Packages can be found using one of two ways. You can issue the command
 
+    # cd /usr/pkgsrc/
     # 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:
+There is also the pkglocate tool that comes with pkgsrc:
 
     # /usr/pkgsrc/pkglocate 'package name'
 
-You can also utilize the UNIX file finding commands (whereis, locate, or find).
+Normal UNIX file finding commands will work (whereis, locate, or find).
 
-### Upgrade all Installed packages 
+It's also possible to browse website that show all the available pkgsrc packages, such as [http://pkgsrc.se/](pkgsrc.se)
+
+## Upgrading 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
 
@@ -230,7 +163,7 @@ Note that ftp://binary/url represents the URL to an online binary pkgsrc reposit
 
 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 
+## Removing packages
 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
@@ -276,22 +209,6 @@ 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.
 
@@ -299,26 +216,14 @@ More infomration can be found in [ccaches manual page](http://ccache.samba.org/c
 
 * 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
+There's also a RSS feed "NetBSD - Fresh Packages" available: http://www.netbsd.org/Changes/rss-netbsd-pkgs.xml